Service ID

Unique identifier for services and inter-service communication.

A service ID uniquely identifies each service and enables inter-service referencing. It ensures that services can be reliably referenced, managed, and deployed. When you are using the same service commissioning file for multiple service instances, you must define a unique service ID for each instance.

Default Service ID

A default service ID is automatically generated from the name property in the service commissioning file's metadata when uploading a service commissioning file to Connectware. Non-permitted characters are removed and remaining characters are converted to lowercase during this process.

However, the name field in the service commissioning file does not define the service ID. It only influences the default value.

You must change the default service ID to a unique value if the service commissioning file is used for more than one instance. See Defining Service IDs.

Defining Service IDs

You can define service IDs manually via:

• Admin UI: After uploading a service commissioning file, Connectware creates a default service ID based on the name property. You can edit the default service ID in the Create Service dialog before confirming the installation. See Defining the Service ID via the Admin UI.

• Deployment pipeline: If your service commissioning files are deployed automatically in a rollout process, the service IDs must be calculated and set to prevent setup conflicts. For example, a single service commissioning file could be deployed multiple times with different IDs and parameterization to provide resources to multiple distributed agents.

We provide an Ansible Collection to simplify automated Connectware deployments.

Defining the Service ID via the Admin UI

The default service ID is auto-generated when uploading the service commissioning file to Connectware. You must change the default service ID to a unique value if the service commissioning file is used for more than one instance.

1. In the Services View, click Upload Service to add a new service commissioning file.

2. In the Create Service dialog, click Choose File.

3. In your file browser, select your service commissioning file and click Open.

4. The default service ID is displayed in the Configure the new service section.

Example: If the name property in the service commissioning file is set to PressLine_TempSensor-01...

press_line_12.yml

metadata:
  name: PressLine_TempSensor-01

...the auto-generated service ID will be presslinetempsensor01.

Example of the resulting service ID presslinetempsensor01 displayed during upload to Connectware in the Create Service dialog.

1. Change the default service ID to a unique service ID. This is particularly relevant when using the same service commissioning file for multiple service instances. Adhere to the Service ID Requirements.

2. Optional: Make additional configurations in the Create Service dialog.

3. Click Install.

Service ID Requirements

Follow these requirements when defining service IDs:

• Length: See Service ID Length Restrictions.

• Allowed characters:

  • ASCII letters (both lowercase and uppercase)

  • Numbers

  • Underscore (_)

  • Period (.)

• Pattern: Must follow the regular expression pattern: [a-zA-Z0-9][a-zA-Z0-9_.]*

• Restrictions: Hyphens (-) are not permitted in service IDs as they serve as special separators between service IDs and usernames in Connectware's Docker container resource management.

This is validated automatically when you are installing a service via the Create Service dialog. See Defining the Service ID via the Admin UI.

Service ID Length Restrictions

The maximum length of the service ID and the resource ID are interdependent. The combination of service ID + hyphen + resourceName forms the resource ID. Make sure to stay within the limit of the resource ID when defining service IDs and resource names.

• General restriction: The combination of serviceId + hyphen + resourceName must be 100 characters or fewer.

• Docker hostname restriction: When a service includes Cybus::Container or Cybus::Volume, the combination of serviceId + hyphen + resourceName must be 63 characters or fewer.

• If you have long resource names, consider abbreviations to keep the combined string within the applicable limit.

• Do not add an extra hyphen. Connectware adds one automatically.

Determining the Service ID Length (Examples)

Here are examples on how you can determine the maximum length of a service ID.

A) Example for the General Limit (100 Characters)

• Resource name: 10 characters

• Calculation: max.length - hyphen - resourceName.length

• Remaining for the service ID: 100 - 1 - 10 = 89

• Result: The service ID must be 89 characters or fewer.

B) Example for the Docker-Only Limit (63 Characters)

The following length limitation only applies to Docker-based deployments where service IDs are used in hostnames for containers (Cybus::Container) or volumes (Cybus::Volume).

• Resource name: 10 characters

• Calculation: max.length - hyphen - resourceName.length

• Remaining for service ID: 63 - 1 - 10 = 52

• Result: The service ID must be 52 characters or fewer.