.. _user/services/usage/index:

########################################
Working with Service Commissioning Files
########################################

This page explains how to work with services from the service overview page of
the *Connectware* web interface.

.. important::

   If your service fails to install, remove, enable or disable, already created
   resources will be rolled back and removed to avoid cluttering the Connectware
   with unused data.

.. _user/services/usage/install-service:

Installing Services
===================
Commissioning files are installed using the web-based interface of the
*Connectware* on the service overview page:

1. On the navigation panel, click ``Services``.

  .. figure:: ../../../resources/service/install/1_service_menu_toolbar.png
     :width: 500px

2. Click ``Upload Service`` to add a new service.

  .. figure:: ../../../resources/service/install/2_service_menu.png
      :width: 600px

3. In the `Create Service` dialog, click ``Choose File``,
   select a commissioning file from your local computer in the file browser, and
   click ``Ok``.

  .. figure:: ../../../resources/service/install/3_select_service_file_dialog.png
      :width: 600px

4. This will fill in the information in the right part of this dialog window, the
   `Configure the new service` section. If your service commissioning file
   provides configurable parameters, you can now enter customized values for
   your service. Depending on the commissioning file, parameter descriptions and
   default values may be available. Additionally, the commissioning file can be
   reviewed by expanding the ``Click to see commissioning file`` tab in the left
   part. Once you are finished click ``Install``.

  .. figure:: ../../../resources/service/install/4_service_configure_dialog.png
      :width: 600px

5. In case everything was configured correctly, you should see the new service
   added to the service list, initially in the `Disabled` state.

  .. figure:: ../../../resources/service/install/5_service_install_success.png
      :width: 600px

.. _user/services/usage/enable-service:

Enabling Services
=================

Enabling, updating, or reconfiguring a service can only be done from the
:ref:`user/services/usage/details` by selecting the service in the list.

  .. figure:: ../../../resources/service/details/service_select.png
      :width: 600px

Continue here: :ref:`user/services/usage/details/enable`

Your service now enters the `Enabling` state, in which all resources which
were defined in the commissioning file are being created.

  .. figure:: ../../../resources/service/enable/3_service_enabling.png
      :width: 600px

Once the `Enabling` has finished successfully, your service will reach the
`Enabled` status and a confirmation message is displayed.

  .. figure:: ../../../resources/service/enable/4_service_enable_success.png
      :width: 600px

.. _user/services/usage/disable-service:

Disabling Services
==================

1. To disable a running service, select the service from the service list
   (1.) and click ``Disable`` (2.) on the toolbar.

  .. figure:: ../../../resources/service/disable/1_disable_service_toolbar.png
      :width: 600px

2. This will open the ``Disable Service`` dialog. To disable the
   running service, confirm your selection by clicking `Disable`.

  .. figure:: ../../../resources/service/disable/2_disable_service_dialog.png
      :width: 500px

.. important::

  Disabling a service will destroy running containers, enabled connections,
  endpoints and mappings. Volumes however will remain in its current state and
  will reattach to the service once it is enabled again.


.. _user/services/usage/delete:

Removing Services
=================

.. note::

   To remove a running service, you must disable it first. Follow the
   instructions contained in the preceding section
   :ref:`user/services/usage/disable-service` section to do so.

1. To remove a disabled service, select the service from the service list
   (1.) and click ``Delete`` (2.) on the toolbar.

  .. figure:: ../../../resources/service/delete/1_delete_service_toolbar.png
      :width: 600px

2. This will open the ``Delete Service`` dialog. To complete the service deletion,
   confirm your selection by clicking ``Delete`` in the bottom right corner of the
   dialog window.

  .. figure:: ../../../resources/service/delete/2_delete_service_dialog.png
      :width: 360px

.. important::

  Removing a service will not remove *volumes* defined by the service
  commissioning file. These volumes will remain in its current state and
  reattach to the service once it is installed and enabled again.

.. _user/services/usage/update:

Updating Services
=================

Enabling, updating, or reconfiguring a service can only be done from the
:ref:`user/services/usage/details` by selecting the service in the list.

  .. figure:: ../../../resources/service/details/service_select.png
      :width: 600px

Continue here: :ref:`user/services/usage/details/update`