# 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**

{% code lineNumbers="true" %}

```yaml
!ref Cybus::MqttHost
```

{% endcode %}

### 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**

{% code lineNumbers="true" %}

```yaml
!sub 'Connected to ${hostname}'
```

{% endcode %}

{% hint style="info" %}
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.
{% endhint %}

## 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](#string-specific-properties).
* `number`: Decimal or integer values. See also [Number-Specific Properties](#number-specific-properties).
* `integer`: Whole numbers only. See also [Number-Specific Properties](#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](#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](https://docs.cybus.io/2-0-6/documentation/rule-engine/data-processing-rules#expression) 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 fulfill. 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

{% code lineNumbers="true" %}

```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
```

{% endcode %}

## 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](https://docs.cybus.io/2-0-6/documentation/services/serviceid) that uniquely identifies the currently running service, as defined by the user when [installing](https://docs.cybus.io/2-0-6/documentation/services/setting-up-and-configuring-services/installing-services) 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](https://docs.cybus.io/2-0-6/documentation/services/setting-up-and-configuring-services/installing-services).

The default Cybus::MqttRoot can be overridden by defining the `CYBUS_MQTT_ROOT` variable in the [definitions](https://docs.cybus.io/2-0-6/documentation/services/service-commissioning-files/definitions) section of the service 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 service 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:

{% code lineNumbers="true" %}

```yaml
definitions:
  CYBUS_MQTT_ROOT: 'your/custom/prefix'
```

{% endcode %}

{% hint style="warning" %}
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.
{% endhint %}