parameters¶

In this optional section, parameters to customize commissioning files for multiple use cases can be defined. Each time a service is installed or reconfigured, 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}'

Note: 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).

Parameter Properties¶

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: https://ajv.js.org/json-schema.html#json-data-type

type

Required. The data type for the parameter (DataType), specified by one of the following strings.

The following parameter types are supported:

string: A literal string. For example, users could specify “MyUserName”. See also Additional properties for strings.
number: Can be used for integer or float. See also Additional properties for numbers.
integer: An integer value, which is a numeric value with no decimals. See also Additional properties for numbers.
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 Additional properties for arrays 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 expressions 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: [...]

Additional properties for strings¶

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: 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 https://ajv.js.org/json-schema.html#format

Additional properties for numbers¶

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.

Additional properties for arrays¶

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.

Example¶

parameters:
  modbusPort:
    type: integer
    default: 10922
    description: The modbus port number

  someString:
    type: string
    description: This should be a string to be used somewhere else in the service

  hostname:
    type: string
    format: hostname
    description: The hostname for the xy connection

  hostname_array:
    description: List of hostnames or IP addresses
    type: array
    items: { type: string }
    default: [ '123.123.123.123:4567', '124.124.124.124:5678' ]

  mixedArray:
    type: array
    items: [{type: 'integer'}, {type: 'string'}]
    default: [1, 'abc']

  anotherArray:
    type: array
    items: {type: 'number'}
    minItems: 2
    maxItems: 4
    uniqueItems: true

Global pre-defined parameters¶

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: This is the ServiceID that uniquely identifies the currently running service, as defined by the user when installing and configuring the service
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

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 installing a service.

The default Cybus::MqttRoot can be overridden by defining the CYBUS_MQTT_ROOT variable in the definitions 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.

Important

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 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 environment variables. 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 definitions section of the commissioning file.

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.