ServiceID

A commissioning file acts as a template for creating a concrete service. It is the template only, much like in a programming language the class serves as a template for concrete object instantiations. When installing a service, the concrete service can be configured by choosing different values for the parameters of the commissioning file. In this configuration step, the serviceId is chosen as a unique identifier for this concrete service.

The serviceId may consist of ascii characters (lower and upper case), numbers, underscore, and period (decimal point), identical to how Docker container names may be chosen [1] (regular expression pattern: [a-zA-Z0-9][a-zA-Z0-9_.]*). If no serviceId is specified explicitly, an auto-generated one is used, and also proposed as default when installing a service. The auto-generated serviceId is taken from the metadata name property with all non-allowed characters removed. For backward-compatibility reasons, the auto-generated serviceId in 1.0.x changes all characters to lowercase and also removes all punctuation, including underscore and period.

Due to different parameter choices, the concrete services may be very different once enabled, even when the same commissioning file was used. Hence, the serviceId is used as the unique identifier for each enabled service.

The serviceId is also important when referencing resources in other services for inter-service referencing.

The length of the serviceId is generally not restricted, except if there are any Cybus::Container or Cybus::Volume resources in the given service commissioning file. For any of these resources, the resulting resource name from serviceId and resourceId together must be not longer than 63 characters, which is a limitation from the Docker container hostname property. If any of these resources exist in the file, the serviceId will be checked to be not longer than what is possible while still fulfilling the resource name restriction on the container resources. For example, if there is a Cybus::Container resource with a 10 character long resourceId, the serviceId must be at most 52 characters long (63, minus 10, minus 1 hyphen character). This check will be performed upon installation of the service.

Footnotes

[1]

There is one exception from the Docker analogy: The hyphen character - (also called minus) is intentionally not allowed for identifiers within the Connectware, because it is used internally as the separator character between service ID and resource ID e.g. for Docker container resources.