.. _user/services/service-id:

ServiceID
=========

A :ref:`commissioning file <user/services/structure>` 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 :ref:`installing <user/services/usage/install-service>` 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 [#f1]_ (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 :ref:`metadata name
<user/services/structure/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 :ref:`inter-service referencing <user/services/interservice>`.

The length of the *serviceId* is generally not restricted, except if there are
any :ref:`user/services/structure/resources/container` or
:ref:`user/services/structure/resources/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.

.. rubric:: Footnotes

.. [#f1] 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.