.. _user/services/interservice:

Inter-Service Referencing
=========================

A service in one commissioning file describes resources and their relations by
referencing resources with each other. In addition to the resources within the
same file, one can also reference resources from other services and other files.
This is called *inter-service referencing*.

With inter-service referencing, resources in one service can depend on resources
in other services. For example, some *Endpoint* definitions in one file can
belong to a *Connection* resource that was defined in another service by
referencing that Connection in the other service.

When using inter-service referencing to reference e.g. a Connection
``myConnection`` in a service with *service id* ``serviceB``, one needs to refer
to that connection by writing ``!ref serviceB::myConnection``. In other words,
the *resource id* must be prefixed with the *service id* and a double colon,
``::``. See also :ref:`service id <user/services/service-id>` and :ref:`resource
id <user/services/structure/resources/resource-id>`.

For more flexibility, the *service id* is usually not specified directly, but
instead a :ref:`parameter <user/services/structure/parameters>` is defined where
the respective service id is given at installation time. To use such a
parameter, e.g. `otherServiceName`, one will write ``!ref
'${otherServiceName}::resourceId'``.

This is shown in the :ref:`example with multiple files
<user/examples/modbus/baz-multiple-files>`. In that example, the commissioning
file which wants to reference the resources of other services has the parameter
`machineService`, and the inter-service reference is written as  ``!ref
'${machineService}::defaultRole'``.


Interactions across Referenced Services
========================================

Given the flexibility Connectware offers to build advance relationships between
services it is important to understand what behaviors are expected in different
scenarios.

- Let's define services that reference other services ``Children Services``
- Let's define a service that is referenced by other services ``Parent Service``


Expected Behaviors
-------------------

Following are four scenarios and how the services behave in each case:

#. All services are installed and then enabled in parents/children order
    #. This behaves as any other set of services
    #. Disabling a ``Parent Service`` will disable all its ``Children Services``
#. All services are installed and then enabled in random order
    #. ``Children Services`` will wait on `Enabling` state
    #. Once the ``Parent Service`` becomes available they will switch to `Enabled`
#. ``Children Services`` are installed first without ``Parent Service`` present
    #. Trying to enable these services will fail with logs in Service Manger indicating the reason
    #. You will see a log starting with ``Failed enabling service because: Could not resolve cross-service reference...`` and some extra details about the unresolvable reference
#. Parents services are installed first without children presents
    #. No special behavior, once ``Children Services`` are added this is the same scenario as cases 1 and 2



Example
--------

The following Service Commissioning Files will be deployed:

#. A Cybus::Container running a database
    * Service id will be ``mssqldatabase``
#. A Cybus::Connection connecting to the database
    * Service id will be ``serviceaconnection``
#. A Cybus::Endpoint using referencing to use that Connection
    * Service id will be ``servicebendpoint``

You can reproduce all the behaviors described above using these Service Commissioning Files.

SQL Database:

.. code-block:: yaml

  description: MSSQL Database
  metadata:
    name: MSSQL Database

  definitions:
    password: password1234!

  resources:
    mssqlDatabase:
      type: Cybus::Container
      properties:
        image: mcr.microsoft.com/mssql/server
        ports:
        - "1433:1433"
        environment:
          ACCEPT_EULA: "Y"
          SA_PASSWORD: !ref password

SQL Connection:

.. code-block:: yaml

  description: MSSQL Connection
  metadata:
    name: Service A Connection

  parameters:

    ip_host:
      type: string
      title: IP address or hostname where Connectware is installed

  definitions:
    port: 1433
    database: master
    username: sa
    password: password1234!

  resources:
    mssqlConnection:
      type: Cybus::Connection
      properties:
          protocol: Mssql
          connection:
            host: !ref ip_host
            port: !ref port
            username: !ref username
            password: !ref password
            database: !ref database
            useEncryption: false

SQL Endpoint:

.. code-block:: yaml

  description: Service B
  metadata:
    name: Service B Endpoint

  parameters:
    mssqlConnectionServiceId:
      type: string
      title: Service id of the MSSQL Connection

  resources:
    mssqlVersionB:
      type: Cybus::Endpoint
      properties:
        protocol: Mssql
        connection: !ref '${mssqlConnectionServiceId}::mssqlConnection'
        subscribe:
          query: 'SELECT @@version'
          interval: 1000