parameters
Last updated
Was this helpful?
Connectware 1.8.0
Last updated
Was this helpful?
In this optional section, parameters to customize commissioning files for multiple use cases can be defined. Each time a service is or , the user is asked to enter custom values for the parameters or to confirm the default values.
Inside of the commissioning file, the values of these parameters can be used in two ways, either by reference !ref or by string substitution !sub.
Using a parameter value by reference will fill in the parameter’s value at the property where it is mentioned. The syntax is to write !ref and then the name of the referenced parameter, without further delimiters such as curly braces or similar. Example: !ref Cybus::MqttHost
Using a parameter value by string substitution will replace the parameter name inside the given string by the parameter’s value, so that the resulting string is used for the property where it is mentioned. The syntax is to write !sub and then a yaml string which includes the parameter name with dollar sign and curly braces. Example: !sub 'Some ${param}'
Parameter substitution or referencing is implemented only for using the full parameter value in unchanged form. Even for parameters of data type array, no further element addressing or similar is implemented, only substitution of the full value (which would be an array in this case).
When defining parameters in the parameters section of the commissioning file, the following properties can be given for each parameter. Additional documentation on the used JSON schema specification can be found on the pages of the internally used “ajv” library, see here:
type
Required. The data type for the parameter (DataType), specified by one of the following strings.
string - A literal string. For example, users could specify “MyUserName”. See also .
number - Can be used for integer or float. See also .
integer - An integer value, which is a numeric value with no decimals. See also .
boolean - A boolean value: true or false. When the parameter value is referenced within the commissioning file using !ref, it will evaluate to true or false.
array - A JSON array of literal values, which in turn can be either strings or numbers. Requires the items: property as described in below. (Note: When substituting such a parameter using !sub inside the file, only the full value can be substituted. No element addressing or similar is possible inside the commissioning file.) Example: A parameter with type: array could receive the following value: [test,dev,prod]. When substituting this into e.g. JSONata of the Rule Engine, the value will evaluate to ["test","dev","prod"] which can then be processed in JSONata accordingly.
default
Optional. A value of the appropriate type for the parameter to use if no value is specified when the service is installed. If additional constraints have been defined as explained below, this default value must adhere to those constraints.
description
Optional. A string of up to 4000 characters that describes the parameter. This is shown in the configuration dialog window when installing a service in the admin UI.
enum
Optional. An array containing the list of values allowed for the parameter. If a value different from all array elements has been specified for this parameter, it will be invalid, and the resulting error message will list the allowed values as given in this property as allowedValues: [...]
minLength
Optional, and only active for string values: An integer value that specifies the minimum number of characters which the value must have.
maxLength
Optional, and only active for string values: An integer value that specifies the maximum number of characters which the value must have.
pattern
Optional, and only active for string values: A regular expression pattern which the value must match, otherwise the value is invalid.
format
minimum
Optional, and only active for number values: The minimum allowed value for the data to be valid.
maximum
Optional, and only active for number values: The maximum allowed value for the data to be valid.
items
Required. An object, or an array of objects, describing the types of the array’s items. To define an array of strings, write items: { type: string }
minItems
Optional. The value should be a number defining the minimum number of items in the array. Only applicable if items is an object and not an array, i.e. all array elements have the same type.
maxItems
Optional. The value should be a number defining the maximum number of items in the array. Only applicable if items is an object and not an array, i.e. all array elements have the same type.
uniqueItems
Optional. If the value is true, the array should have unique items only to be valid.
In addition to the parameters defined in the parameters section of the commissioning file, the following global parameters are always pre-defined by the Connectware system and can be used everywhere:
Cybus::ServiceId
Cybus::MqttHost
Hostname of the Connectware’s internal MQTT broker
Cybus::MqttPort
Hostname of the Connectware’s internal MQTT Broker
Cybus::MqttUser
Valid username for the Connectware’s internal MQTT broker (auto-generated)
Cybus::MqttPassword
Valid password for the Connectware’s internal MQTT broker (auto-generated)
Cybus::MqttRoot
It is a central goal of the Connectware to let resources from one service be automatically protected and isolated from resources defined in another service. This isolation should be implemented for as many aspects of the resources as possible, including generated URLs, persisted storage, MQTT communication topics, Docker container namings, etc.. To achieve this isolation, the namespacing principle is applied. This means a unique prefix is prepended to all named identifiers, which could otherwise collide with a name or identifier already used by other services.
With respect to MQTT data, the namespacing principle means that all MQTT topics of one service will be prepended with an auto-generated prefix named according to the service instance. This prefix is accessible in the commissioning file by the global parameter Cybus::MqttRoot mentioned above.
In those cases where Cybus::MqttRoot was set manually, you need to watch out yourself to not run into naming collisions between multiple service instances on the same Connectware installation.
Optional, and only active for string values: Specifies one of several fixed string formats which the parameter value must fulfil. Currently available formats are: date, date-time, uri, email, hostname, ipv4, ipv6, regex. For more information, see
This is the that uniquely identifies the currently running service, as defined by the user when and configuring the service
Topic prefix for all MQTT topics within this service instance. This global parameter by default has the value services/<serviceId> where <serviceId> is replaced with the actual ServiceID of the current service, as specified by the user during .
The default Cybus::MqttRoot can be overridden by defining the CYBUS_MQTT_ROOT variable in the section of the commissioning file. See below for an explanation of when this override may be needed. In the general case it is not recommended to override the default, because the auto-generated topic prefix helps keeping the services isolated from each other.
In some applications (but seldomly), this auto-generated prefixing and namespacing turns out to be not the best solution and an alternative implementation is needed. For example, there might be an application inside a Docker container (i.e. a Cybus::Container resource) that requires fixed and unchangeable MQTT topics for subscription and publishing, and those topics cannot easily be changed by configuration such as through . In that case, the auto-generated prefix (the Cybus::MqttRoot) is potentially difficult to be used, and hence this prefix can be defined manually to match the required topics of the application. To define the Cybus::MqttRoot prefix manually, you need to set a variable named CYBUS_MQTT_ROOT in the section of the commissioning file.