.. _user/services/structure/parameters: ********** parameters ********** In this optional section, parameters to customize commissioning files for multiple use cases can be defined. Each time a service is :ref:`installed ` or :ref:`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 :ref:`user/services/structure/parameters/properties/strings`. number Can be used for integer or float. See also :ref:`user/services/structure/parameters/properties/numbers`. integer An integer value, which is a numeric value with no decimals. See also :ref:`user/services/structure/parameters/properties/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 :ref:`user/services/structure/parameters/properties/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 :ref:`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: [...]`` .. noEcho - not yet implemented, as noted here: CYB-2107 .. _user/services/structure/parameters/properties/strings: 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 .. _user/services/structure/parameters/properties/numbers: 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. .. _user/services/structure/parameters/properties/arrays: 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 ======= .. code-block:: yaml 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 .. _user/services/structure/parameters/global: 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 :ref:`user/services/service-id` that uniquely identifies the currently running service, as defined by the user when :ref:`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) .. _user/services/structure/parameters/global/mqtt-root: Cybus::MqttRoot Topic prefix for all MQTT topics within this service instance. This global parameter by default has the value ``services/`` where ```` is replaced with the actual :ref:`user/services/service-id` of the current service, as specified by the user during :ref:`installing a service `. The default `Cybus::MqttRoot` can be overridden by defining the ``CYBUS_MQTT_ROOT`` variable in the :ref:`user/services/structure/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 :ref:`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 :ref:`user/services/structure/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.