> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md).

# Parameters

Reuse a single service commissioning file across machines and environments by turning the values that differ into parameters.

The parameters section declares the values that you enter at installation instead of writing them into the service commissioning file. Connectware prompts you for each parameter when you install or reconfigure the service, and pre-fills any default you defined.

* **Optional**
* Type: `object`, with one entry per parameter

To use one service commissioning file for several machines, install it once per machine. Enter a different value each time, such as the IP address of the device.

## Using Parameter Values

You use parameter values within the service commissioning file by reference (`!ref`) or by string substitution (`!sub`). Both methods also work with [definitions](https://docs.cybus.io/data-flows/service-commissioning-files/definitions.md) and with the [global pre-defined parameters](#global-pre-defined-parameters).

### Reference Method (`!ref`)

Use the reference method to insert the value of a parameter directly at a property. Write `!ref` followed by the parameter name. The value keeps its type, so a number stays a number, and a list stays a list.

{% code lineNumbers="true" %}

```yaml
parameters:
  deviceAddress:
    type: string
    default: 192.168.1.100

resources:
  modbusConnection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      connection:
        host: !ref deviceAddress
        port: 502
```

{% endcode %}

### String Substitution Method (`!sub`)

Use string substitution to insert the value of a parameter into a string at a property. Write `!sub` followed by a string that contains the parameter name in `${...}`. Connectware replaces each `${parameterName}` with the value of that parameter. The result is a string, even when the parameter is a number or a boolean.

In `${...}`, a name can contain only letters, digits, underscores, and colons, as in `${Cybus::MqttRoot}`. Connectware leaves a placeholder with any other character unchanged, such as `${device-ip}`. To use a parameter or definition with `!sub`, name it accordingly.

{% code lineNumbers="true" %}

```yaml
parameters:
  lineNumber:
    type: integer
    default: 1

metadata:
  name: !sub 'Filling Line ${lineNumber}'
```

{% endcode %}

{% hint style="warning" %}
You can use a parameter only in its complete, unmodified form. This applies to all data types. For example, you cannot insert a part of a string parameter or a single element of an array parameter.
{% endhint %}

## Parameter Properties

Each parameter is an object with the following properties. They follow the JSON Schema specification and define the data type and the constraints of the value. Connectware checks every value you enter against them and rejects a value that does not meet them. For details on the JSON Schema keywords, see the [Ajv documentation](https://ajv.js.org/json-schema.html#json-data-type).

### Core Properties

#### type

The data type of the parameter.

* **Required**
* Type: `string`

The following types are available:

* `string`: Text values, such as `MyUserName`. See [String-Specific Properties](#string-specific-properties).
* `number`: Decimal or integer values, such as `0.5` or `1000`. See [Number-Specific Properties](#number-specific-properties).
* `integer`: Whole numbers only, such as `502`. See [Number-Specific Properties](#number-specific-properties).
* `boolean`: The values `true` and `false`. With `!ref`, the parameter inserts the boolean `true` or `false`, not a string.
* `array`: A JSON array of literal values, which can be strings, numbers, or booleans. An array parameter requires the [items](#items) property. See [Array-Specific Properties](#array-specific-properties).

#### default

The value that Connectware uses when you install the service without entering one. The default must have the type of the parameter and meet all of its constraints. A parameter without a default is required, so you must enter a value.

* **Optional**
* Type: the type of the parameter

#### description

Describes the parameter. The [Admin UI](https://docs.cybus.io/access/admin-ui.md) shows the description in the configuration dialog when you install the service.

* **Optional**
* Type: `string`
* Maximum length: 4000 characters

#### enum

A list of the values that the parameter accepts. Connectware rejects any other value, and the error message lists the allowed values under `allowedValues`.

* **Optional**
* Type: `array`

### String-Specific Properties

The following properties apply only to `string` parameters.

#### minLength

The minimum number of characters that the value must have.

* **Optional**
* Type: `integer`

#### maxLength

The maximum number of characters that the value can have.

* **Optional**
* Type: `integer`

#### pattern

A regular expression that the value must match.

* **Optional**
* Type: `string`

#### format

A format that the value must have. The following formats are available: `date`, `date-time`, `uri`, `email`, `hostname`, `ipv4`, `ipv6`, and `regex`. For details, see the [Ajv documentation on formats](https://ajv.js.org/json-schema.html#format).

* **Optional**
* Type: `string`

#### secret

If `true`, the value of the parameter is write-only. Use it for credentials such as passwords or API tokens. Setting `secret: true` on a parameter of another type makes the service commissioning file invalid. See [Secret Parameters](#secret-parameters).

* **Optional**
* Type: `boolean`

### Number-Specific Properties

The following properties apply only to `number` and `integer` parameters.

#### minimum

The smallest value that the parameter accepts.

* **Optional**
* Type: `number`

#### maximum

The largest value that the parameter accepts.

* **Optional**
* Type: `number`

### Array-Specific Properties

The following properties apply only to `array` parameters.

Like every parameter, an array parameter is inserted as a whole. You cannot address a single item, such as the first one. `!ref` inserts it as a list, for a property that takes a list. `!sub` inserts its items into a string, separated by commas. For example, the value `[test, dev, prod]` becomes `test,dev,prod`.

To use the items in a [JSONata expression](https://docs.cybus.io/data-flows/rule-engine/data-processing-rules.md#expression) of the Rule Engine, substitute them into a string and split it again with `$split`. The following mapping forwards only status messages whose `environment` is one of the values of the parameter:

{% code lineNumbers="true" %}

```yaml
parameters:
  environments:
    type: array
    items: { type: string }
    default: [test, dev, prod]

resources:
  statusMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${Cybus::MqttRoot}/status'
          publish:
            topic: !sub '${Cybus::MqttRoot}/status/filtered'
          rules:
            - filter:
                expression: !sub '$.environment in $split("${environments}", ",")'
```

{% endcode %}

With the default value, the expression becomes `$.environment in $split("test,dev,prod", ",")`.

#### items

The type of the items. For a list of strings, write `items: { type: string }`. To give each position its own type, write one object per position, for example `items: [{ type: integer }, { type: string }]`.

* **Required**
* Type: `object` or `array`

#### minItems

The minimum number of items that the array must have.

* **Optional**
* Type: `number`

#### maxItems

The maximum number of items that the array can have.

* **Optional**
* Type: `number`

#### uniqueItems

If `true`, all items must be different.

* **Optional**
* Type: `boolean`

## Example

{% code lineNumbers="true" %}

```yaml
parameters:
  deviceAddress:
    type: string
    format: ipv4
    default: 192.168.1.100
    description: IP address of the Modbus/TCP device

  modbusPort:
    type: integer
    default: 502
    description: Port of the Modbus/TCP server

  pollingInterval:
    type: integer
    minimum: 100
    maximum: 60000
    default: 1000
    description: Polling interval in milliseconds

  environment:
    type: string
    enum: [test, dev, prod]
    default: prod
    description: Environment that the service runs in

  hostnames:
    type: array
    items: { type: string }
    default: ['192.168.1.100', '192.168.1.101']
    description: List of hostnames or IP addresses

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

  setpoints:
    type: array
    items: { type: number }
    minItems: 2
    maxItems: 4
    uniqueItems: true
```

{% endcode %}

## Secret Parameters

A secret parameter is a write-only string parameter for credentials, such as passwords or API tokens. When a parameter has `secret: true`, the API omits its value from the service details. The [Admin UI](https://docs.cybus.io/access/admin-ui.md) shows a concealed field instead of the value.

{% code lineNumbers="true" %}

```yaml
parameters:
  dbHost:
    type: string
    description: Hostname of the database
  dbPassword:
    type: string
    secret: true
    description: Database password (write-only)

resources:
  mssqlConnection:
    type: Cybus::Connection
    properties:
      protocol: Mssql
      connection:
        host: !ref dbHost
        username: connectware
        password: !ref dbPassword # the value you enter at installation
        database: mes
```

{% endcode %}

The service commissioning file declares the parameter but contains no password. You enter the password in the configuration dialog when you install the service in the Admin UI. Alternatively, pass it in the `parameters` of the API request. Connectware stores it with the service and inserts it wherever the service commissioning file references `dbPassword`.

### Updating a Service with a Secret Parameter

On a service update, you can keep the stored value or replace it:

* To keep the stored value, omit the parameter from an API request or send `*****`. In the Admin UI, leave the field unchanged.
* To replace the stored value, submit a new one. An empty string counts as a new value. `*****` does not, as long as the properties of the secret parameter stay the same.

Connectware keeps the stored value only while the properties of the secret parameter stay the same. Changes to other parameters or to resources do not affect it. Suppose you installed a service with the service commissioning file from the example. The following excerpts show only its `parameters` section.

This update changes only `dbHost`. Connectware keeps the stored password, so you do not need to submit it again:

{% code lineNumbers="true" %}

```yaml
parameters:
  dbHost:
    type: string
    description: Hostname of the MES database # changed
  dbPassword:
    type: string
    secret: true
    description: Database password (write-only)
```

{% endcode %}

This update changes the `description` of `dbPassword`. Connectware does not keep the stored password, so submit it again:

{% code lineNumbers="true" %}

```yaml
parameters:
  dbHost:
    type: string
    description: Hostname of the database
  dbPassword:
    type: string
    secret: true
    description: Password for the MES database # changed
```

{% endcode %}

Adding or removing `secret` counts as a change too. If you change a property of the secret parameter and do not submit the value again, one of the following happens:

* If the parameter has no `default`, Connectware rejects the update, and the stored value stays unchanged.
* If the parameter has a `default`, Connectware accepts the update and uses the default instead of the stored value.

After such a change, `*****` in an API request no longer keeps the stored value either. Connectware then stores `*****` as the new value.

Do not send several updates to the same service at the same time. Suppose one update sets a new secret value, and another update at the same moment omits it. The second update can then bring back the previous value.

{% hint style="warning" %}

## Security Considerations

`secret` controls display, not storage encryption. The value is still stored as part of the service and remains readable by the resources that reference it.

When a resource references the parameter, the resolved value becomes part of that resource's configuration. The API masks it there only if the property name matches `CYBUS_RESOURCES_CONFIG_SENSITIVE_PROPERTY_NAME_PATTERN` (by default, names containing `pass`, `secret`, `key`, or `token`). See [Environment Variables](https://docs.cybus.io/reference/environment-variables.md). Link resources are not masked.

Do not write a real password into `default`. `secret` hides only the value entered at installation. A default is part of the service commissioning file and remains readable.

Update permissions are equally sensitive. Anyone who can update a service can edit the service commissioning file to route a referenced secret into a readable location.
{% endhint %}

## Global Pre-Defined Parameters

In addition to the parameters in your parameters section, Connectware defines the following global parameters for every service. You can use them anywhere in the service commissioning file, with `!ref` or `!sub`, like your own parameters. If you misspell one of these names, Connectware rejects the service commissioning file.

### Cybus::ServiceId

The [service ID](https://docs.cybus.io/data-flows/services/serviceid.md) that uniquely identifies the service. You set it when you [install](https://docs.cybus.io/data-flows/services/managing/installing.md) and configure the service.

### Cybus::MqttHost

The hostname of the internal MQTT broker of Connectware.

### Cybus::MqttPort

The port of the internal MQTT broker of Connectware.

### Cybus::MqttUser

A username for the internal MQTT broker. Connectware generates this user for the service.

### Cybus::MqttPassword

The password of the user in `Cybus::MqttUser`. Connectware generates it.

### Cybus::MqttRoot

The topic prefix for the MQTT topics of this service instance. The default is `services/<serviceId>`, where `<serviceId>` is the service ID. Keep the default where you can, because it keeps the topics of different services apart.

For where Connectware applies the prefix, see [MQTT Topic Prefix](#mqtt-topic-prefix). To change it, see [Custom Topic Prefix](#custom-topic-prefix).

## Service Isolation

Connectware keeps the resources of different services protected and apart. It automatically adds a prefix that is unique to the service to all resource identifiers that could conflict across services. This includes the following:

* Generated URLs
* Persistent storage
* MQTT topics
* Docker container names

### MQTT Topic Prefix

The topics of endpoints and nodes start with `Cybus::MqttRoot`, which is `services/<serviceId>` by default. Connectware uses the topics of mappings as written, so add the prefix there yourself, for example `!sub '${Cybus::MqttRoot}/temperature'`.

In a [Unified Namespace](https://docs.cybus.io/unified-namespace/unified-namespace.md), topics that Connectware builds from an [asset reference](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-asset.md#topics-of-an-asset) start with the namespace root instead, for example `factory/hall1/pump01/temperature`.

### Custom Topic Prefix

Some applications need a custom prefix. Typically, these are Docker containers that expect fixed MQTT topics, which are hard to change through environment variables. For these, replace the prefix with a definition named `CYBUS_MQTT_ROOT` in the [definitions](https://docs.cybus.io/data-flows/service-commissioning-files/definitions.md) section:

{% code lineNumbers="true" %}

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

{% endcode %}

The prefix must not start or end with `/`, and must not contain `#` or `+`.

{% hint style="warning" %}
With a custom prefix, you are responsible for keeping the topics of this service apart from other services. This includes other installations of the same service commissioning file, because they all get the same prefix. Choose a prefix that no other service on the same Connectware installation uses. Use a custom prefix only when the default prefix does not work for your application.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
