Parameters

The parameters section is an optional component of service commissioning files that enables service customization for different use cases. When installing or reconfiguring a service, users will be prompted to either input custom values for these parameters or confirm their default values.

Using Parameter Values

Parameter values can be utilized within the service commissioning file by reference (!ref) or by string substitution (!sub).

Reference Method (!ref)

Use the reference method to directly insert a parameter's value at a specific property location. The syntax consists of !ref followed by the parameter name.

Example

!ref Cybus::MqttHost

String Substitution Method (!sub)

Use string substitution to replace the parameter name inside the a string by the parameter’s value. The resulting string with the substituted value will be used at the specified property location. The syntax uses !sub followed by a string containing the parameter name enclosed in ${...}.

Example

!sub 'Connected to ${hostname}'

Parameters can only be used in their complete, unmodified form. This limitation applies to all data types, including arrays. For example, when working with array-type parameters, you can only reference or substitute the entire array—individual element access is not supported.

Parameter Properties

The parameters section of a service commissioning file allows you to define configurable values using specific properties for each parameter. These properties follow the JSON Schema specification, which provides a robust framework for defining and validating parameter data types and constraints.

For a comprehensive reference of the JSON Schema specification used in parameter definitions, refer to the ajv library documentation at: https://ajv.js.org/json-schema.html#json-data-type

The following properties can be specified for each parameter:

Core Properties

type

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

• string: Text values (e.g. "MyUserName"). See also String-Specific Properties.
• number: Decimal or integer values. See also Number-Specific Properties.
• integer: Whole numbers only. See also Number-Specific Properties.
• boolean: true/false values. When referenced with !ref within service commissioning files, it will evaluate to true/false.

• array: A JSON array of literal values, which in turn can be either strings or numbers. Requires the items: property as described in Array-Specific Properties. 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 service 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: [...]

String-Specific Properties

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

Number-Specific Properties

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.

Array-Specific Properties

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 service commissioning file, the following global parameters are always pre-defined by Connectware 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.

Resource Isolation and Namespacing

Connectware implements resource isolation between services through a systematic namespacing approach. This ensures that resources from different services remain protected and separated from each other.

The namespacing principle automatically applies unique prefixes to all resource identifiers that could potentially conflict across services. This isolation extends to multiple aspects including:

• Generated URLs

• Persistent storage

• MQTT communication topics

• Docker container names

MQTT Namespacing

For MQTT communication, Connectware automatically prepends all service-specific topics with a unique prefix based on the service instance. This prefix is available within the commissioning file through the global parameter Cybus::MqttRoot.

Custom Prefix Configuration

While automatic namespacing works well for most cases, some applications may require custom prefix configurations. This typically occurs when working with Docker containers that have fixed MQTT topic requirements that cannot be easily configured through environment variables.

In such cases, you can manually define the Cybus::MqttRoot prefix by setting the CYBUS_MQTT_ROOT variable in the service commissioning file's definitions section:

definitions:
    CYBUS_MQTT_ROOT: 'your/custom/prefix'

When manually setting the MQTT root prefix:

• You become responsible for preventing naming collisions between service instances

• Ensure your prefix choice doesn't conflict with other services running on the same Connectware installation

• Consider this approach only when automatic namespacing cannot meet your application's requirements

This manual configuration should be used sparingly, as the automatic namespacing feature provides built-in protection against resource conflicts.