You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: hull-vidispine-addon/README.md
+6-2Lines changed: 6 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -102,7 +102,7 @@ Describes a particular entity on a subresource on an endpoint which is communica
102
102
| `identifier` | Optional field to specify the objects __identifier__, if not specified or empty the object __identifier__ will be set to the key of the entity. A typical usecase for specifying this explcititly and not using the key is having an object being identified by a GUID but wanting to use a more speaking name for the entity key or utilize the ordering via suitable key names instead of using a non-speaking GUID.' <br><br> The __identifier__ is important for different usecases and can be used accordingly.<br><br> First if making a standard API GET call to determine if the entity already exists, the __identifier__ by default provides the last part of the GET uri, for example `https://host.com/API/notifications/groups/NOTIFICATION-VX-99`. If `noGet` is set, the __identifier__ is not revevant for the GET call because it is not exectuted at all. If `getUriExcludeIndentifier` is set to `true`, the __identifier__ is explicitly not appended to the GET uri. To identify existence of objects with such an API style, it may be required to use a `getCustomScript` (see below) or add the __identifier__ to the `getQueryParams` (see below) to allow identification of the targeted object <br>Analogously, for PUT calls the combination of `putUriExcludeIdentifier: true` and `putUriQueryParams` and for DELETE calls the combination of `deleteUriExcludeIdentifier` and `deleteUriQueryParams` is available to address objects via query parameter identification | | `GET` <br> `POST`<br>`PUT`<br>`DELETE`
103
103
| `getQueryParams` | Query Parameters to add to the Url of a GET command, for example for filtering from a list of objects. This is a key-value style dictionary<br><br>It is a very common scenario that you want to refer to the __identifier__ in your query parameters in case the API identifies objects via query parameter filtering. For this scenario you can use the `$identifier` placeholder in your values and this placeholder will be replaced with the actual identifier (either the value of `identifier` or the objects key if `identifier` is not provided). | | `GET`
104
104
| `getUriExcludeIdentifier` | Normally in a REST style API GET calls include the identifier of the object as the last segment of the URI. By setting this to `true` GET calls will not include the identifier segment. The use of this is for some specific APIs the usual REST style is not used and it may be required to make a GET call to the object resource and process the result via `getCustomScript` functionality or get the object via query parameters with `getQueryParams`. | `false` | `GET`
105
-
| `getCustomScript` | Offers the possibility to provide a custom Powershell script that further processes the result of the GET call. May be used in conjunction with setting `getUriExcludeIdentifier` to true.<br><br>Using a custom script, variables from the outer script can be read and used within the script, so you may find it useful to access the following local variables in the script: <br><br>`$responseGet`: the string result of the GET call<br>`$apiEndpoint`: the apiEndpoint field of the subresource<br><br>The script can return either a boolean value for general success of the GET call (translating to a 200 or 404 status code) or it may return a JSON with additional information useful for adjusting a subsequent PUT or DELETE call. The JSON is allowed to return the following fields that will update the local PowerShell variables accordingly if present:<br><br>`statusCode`: sets the virtual statusCode for further processing<br>`uriPut`: sets the full URI used for putting the `config` content.<br>`uriDelete`: sets the full URI used for deleting the entity.<br>`identifier`: sets the `identifier` for all further PUT or DELETE operations.<br><br>A JSON returned from `getCustomScript` may look like this: `{"statusCode":200, "uriPut":"https://host.com/API/notifications/groups/NOTIFICATION-VX-99"}`<br>An example of this coming together is the usage of notifications in VidiCore, to find out whether a particular notification needs to be updated it is required to get a list of all existing notifications and update the POST/DELETE uri to correctly address the targeted resource. See the VidiCore or MediaPortal Helm Chart for the implementation of this. | | `GET`
105
+
| `getCustomScript` | Offers the possibility to provide a custom Powershell script that further processes the result of the GET call. May be used in conjunction with setting `getUriExcludeIdentifier` to true so you can take custom actions given all found existing objects.<br><br>Using a custom script, variables from the outer script can be read and used within the script, so you may find it useful to access the following local variables in the script: <br><br>`$responseGet`: the string result of the GET call<br>`$apiEndpoint`: the apiEndpoint field of the subresource<br>`$entity`: the entity configuration options<br><br>As a further usage improvement, you can add additional properties (names need to be different from well-known properties, best add a `_` prefix to the variable name) to `$entity` configuration which contain Helm templating expressions that are resolved when rendering the chart. Then access these variables via the `$entity` object in the script. Here is an example:<br><br>`entity:`<br>  `_helm_chart_name_:` `_HT!{{ (index . "$").Chart.Name }}`<br>  `_helm_chart_version_:` `_HT!{{ (index . "$").Chart.Version }}`<br><br> where in the `getCustomScript` you can simply access the current Helm chart name with `$entity._helm_chart_name_` and version with `$entity._helm_chart_version_`<br><br> The script can return either a boolean value for general success of the GET call (translating to a 200 or 404 status code) or it may return a JSON with additional information useful for adjusting a subsequent PUT or DELETE call. The JSON is allowed to return the following fields that will update the local PowerShell variables accordingly if present:<br><br>`statusCode`: sets the virtual statusCode for further processing<br>`uriPut`: sets the full URI used for putting the `config` content.<br>`uriDelete`: sets the full URI used for deleting the entity.<br>`identifier`: sets the `identifier` for all further PUT or DELETE operations.<br><br>A JSON returned from `getCustomScript` may look like this: `{"statusCode":200, "uriPut":"https://host.com/API/notifications/groups/NOTIFICATION-VX-99"}`<br><br>An example of this coming together is the usage of notifications in VidiCore, to find out whether a particular notification needs to be updated it is required to get a list of all existing notifications and update the POST/DELETE uri to correctly address the targeted resource. See the VidiCore or MediaPortal Helm Chart for the implementation of this. | | `GET`
106
106
| `noGet` | If `true` the check for existence is skipped and a PUT or POST is done directly. This is treated same as receiving a 404 on the GET request. | `false` | `GET`
107
107
| `customGetScriptJsonResponseConfigReplacements` | An optional dictionary with key value pairs where the keys specify placeholders that are supposed to be contained in the `config` contents and values specify keys in a JSON response from `getCustomScript` which are supposed to be set by the script. <br><br> The idea behind this setting is to allow reading custom data from an API, store the results in a JSON key value dictionary and use the values to dynamically modify the `config` contents. It only works if a) a `getCustomScript` is used, b) the response JSON from the script populates keys with values, c) the `config` contains placeholder keys that are substituted with the JSON response values.<br><br>As an example let us assume a case where it is not possible to address a particular object instance via a GET call with an `identifier` because the `identifier` was dynamically created by a prior call and it is unknown if the object already exists or not. However it is known that for example a `name` property exists on the instances which is also unique for all object instances. To find out if an instance already exists, it may be possible to get a list of all objects of a particular kind and filter them via their `name` property in order to find the instance in question if it already exists, this would be the content of a `customGetScript`. Thus the JSON response from `getCustomScript` could look like this: `{"statusCode":200, "identifier":"123923213123"` in case an instance was already found via its name. Now it becomes possible to setup the <br><br>`customGetScriptJsonResponseConfigReplacements:`<br>  `'$$identifier$$':` `identifier`<br><br>and a<br><br>`config:`<br>  `id:` `'$$identifier$$'`<br>  `value:` `something`<br><br>The value of `$$identifier$$` is then replaced in the `config` and now when doing a PUT call the correct object is being updated:<br><br>`config:`<br>  `id:` `'123923213123'`<br>  `value:` `something`<br><br> | | `GET`
108
108
| `readConfigFromFile` | Allows to either map complete file contents to the `config` value or the contents from a particular JSON key from a file to `config`. The content of this field if provided must be a dictionary which can have the following fields: <br><br>`path`: mandatory and points to the mounted file's path, the source file can be of any text format. Optionally you can additionally specify `putPath` and/or `postPath` to use different source files depending on PUT or POST case. Note that when specifying `putPath` and/or `postPath` you also need to specify `path` which is resorted to in case the PUT or POST case is not matched with a `putPath` or `postPath`<br> `key`: optional and if specified declares the source files JSON key to import from, for this to work the source file must be a JSON file.<br><br>To use this feature, the file being refered to needs to be mounted into the `hull-install` or `hull-configure` job's pod via providing an additional `volume` and `volumeMount`. | | `POST`<br>`PUT` | `readConfigFromFile:`<br>  `path:` `workflow-deploy.json`
@@ -118,7 +118,7 @@ Describes a particular entity on a subresource on an endpoint which is communica
118
118
| `remove` | The entity will be DELETEd if it exists. If both `register` and `remove` is true, any found entity is first removed if it exists before it is being created. | `false` | `DELETE`
119
119
| `deleteUriExcludeIdentifier` | Some APIs handle DELETEing of entities by calling DELETE to the parent resource and specifying the entity to delete in query params. If the subresource handles DELETEing in that way, set this parameter to `true` and provide the subresource `identifierQueryParam` to identify the entity. If `false` or unspecified, DELETE calls will be made to the path which ends with the entities identifier name. | `false` | `DELETE`
120
120
| `deleteQueryParams` | Query Parameters to add to the Url of a DELETE command. Not a frequent use case but required to delete an entity in auth service. | `false` | `DELETE`
121
-
121
+
| `processNoOp` | Normally when both `register: false` and `remove: false` are set this is equals a no-op where no substantial action is to be done and the complete entity is skipped. In some exceptional and complex cases like the handling of SBOM licenses the whole logic to pull and push SBOM licenses is handled completely by the `getCustomScript`. To enforce execution of a `getCustomScript` with `register: false` and `remove: false` set you need to set `processNoOp: true`. | `false` | `POST`<br>`PUT`<br>`DELETE`
122
122
123
123
## Activation and Preconfiguration
124
124
Execution of Jobs can generally be selectively enabled or not by setting the `hull.objects.job.<jobKey>.enabled` field to `true` or `false`.
@@ -953,6 +953,7 @@ _COMPONENTS_: The `component`s from `hull.config.specific.components` as a comma
953
953
_ENDPOINT_: The endpoint for which the URIs created from _COMPONENTS_ are all defined
954
954
_PORTNAME_: The name of the port that is targeted, defaults to "http" if not set
955
955
_SERVICENAME_: The name of the service that is targeted
956
+
_PATHTYPE_: The pathType value of field, defaults to `ImplementationSpecific` if not provided
956
957
_STATIC_SERVICENAME_: Set `staticName` on service name accordingly, default is false
957
958
958
959
Usage:
@@ -986,6 +987,7 @@ Parameters:
986
987
_PARENT_CONTEXT_: The Helm charts global context
987
988
_COMPONENT_: The `component` to create a database job for
988
989
_TYPE_: The type of Job. Allowed values: create|reset
990
+
_CREATE_SCRIPT_CONFIGMAP: Name of an existing ConfigMap which contains a custom `create-database.sh` script. Only if set to a non-empty ConfigMap name a custom 'create-database.sh'script is executed from the ConfigMap, otherwise the built-in script is executed for _TYPE_ `create`
989
991
Usage:
990
992
991
993
This function full renders job objects that either create or reset a database defined for _COMPONENT_. The container used for these database operations is found in the `hull.config.specific.images.dbTools.repository` field (default is 'vpms/dbtools') and the tag to use is given in the `hull.config.specific.images.dbTools.tag` field (default "1.8"). In order to work correctly, the following environment variables are provided to each 'vpms/dbtools' instance executed:
@@ -1003,6 +1005,8 @@ For _TYPE_=create the following is happening:
1003
1005
1. Check if database server can be reached
1004
1006
2. Verify the database with name DBNAME is accessible for DBUSER. If DBADMINUSER and DBADMINPASSWORD is given, the DBNAME and DBUSER are created in the database so that database with name DBNAME is also accessible for DBUSER. If no DBADMINUSER and DBADMINPASSWORD is given, only successful access for DBUSER to DBNAME is checked.
1005
1007
1008
+
_Note_: When CUSTOM_SCRIPT_CONFIGMAP is set this overwrites the above step 2.
0 commit comments