.. _system-level-label:
-System Level Dialogues
-######################
+ACM System Level Dialogues
+##########################
+Priming The CLAMP Automation Composition Runtime Lifecycle Management uses the following system-level dialogues. These dialogues enable the CLAMP runtime capabilities described in Section 2 of TOSCA Defined Automation Compositions: Architecture and Design. Design Time dialogues will be described in future releases of the system.
.. contents::
:depth: 4
-The CLAMP Control Loop Runtime Lifecycle Management uses the following system level dialogues.
-These dialogues enable the CLAMP runtime capabilities described in :ref:`Section 2 of
-TOSCA Defined Control Loops: Architecture and Design <controlloop-capabilities>`.
-Design Time dialogues will be described in future releases of the system.
+1 Dialogues on Participants
+===========================
+1.1 Register a Participant
+--------------------------
+Participant Registration is performed by a Participant when it starts up. It registers its ID and the ACM Element Types it supports with the ACM runtime.
-1 Commissioning Dialogues
-=========================
+.. image:: ../images/system-dialogues/RegisterParticipant.png
-Commissioning dialogues are used to commission and decommission Control Loop Type definitions
-and to set the values of Common Parameters.
+1.2 Deregister a Participant
+----------------------------
+Participant Deregistration is performed by a Participant when it shuts down. It deregisters its ID and type with the ACM runtime.
-Commissioning a Control Loop Type is a three-step process:
+.. image:: ../images/system-dialogues/DeregisterParticipant.png
-#. The Control Loop Type must be created, that is the Control Loop Type definition must be
- loaded and stored in the database. This step may be carried out over the REST interface or
- using SDC distribution.
+1.3 Supervise Participants
+--------------------------
+Participant Supervision is performed periodically between participants and the ACM runtime server to ensure that registered participants are available over time. Participants send a heartbeat message to the ACM runtime at a configured interval. The heartbeat message contains updated status information for each AC Element Instance that has changed status since the last Heartbeat message sent by the participant.
-#. The Common Properties of the Control Loop type must be assigned values and those values
- must be stored in the database. This step is optional only if all mandatory common properties
- have default values. The Common Property values may be set and amended over and over again
- in multiple sessions until the Control Loop Type is primed.
+.. image:: ../images/system-dialogues/SuperviseParticipantsStatusUpdate.png
-#. The Control Loop Type Definition and the Common Property values must be primed, that is
- sent to the concerned participants. Once a Control Loop Type is primed, its Common Property
- values can no longer be changed. To change Common Properties on a primed Control Loop Type,
- all instances of the Control Loop Type must be removed and the Control Loop Type must be
- de-primed.
+The ACM runtime regularly checks the heartbeat reports from participants and takes action if participants time out. If a heartbeat message is not received for a participant in the Timeout Interval, the participant is marked as timed out and its ACM element instances are informed.
-1.1 Commissioning a Control Loop Type Definition using the CLAMP GUI
---------------------------------------------------------------------
+.. image:: ../images/system-dialogues/SuperviseParticipantsTimeout.png
-This dialogue corresponds to a "File → Import" menu on the CLAMP GUI. The documentation of
-future releases of the system will describe how the Design Time functionality interacts
-with the Runtime commissioning API.
+1.4 Get Participant Information
+-------------------------------
+The information on participants is available over a REST endpoint.
-.. image:: ../images/system-dialogues/comissioning-clamp-gui.png
+.. image:: ../images/system-dialogues/GetParticipantInformation.png
-1.2 Commissioning a Control Loop Type Definition using SDC
-----------------------------------------------------------
+1.5 Order Full Participant Report
+---------------------------------
-.. image:: ../images/system-dialogues/comissioning-sdc.png
+.. image:: ../images/system-dialogues/FullParticipantReport.png
-1.3 Setting Common Properties for a Control Loop Type Definition
-----------------------------------------------------------------
+2 Dialogues on Automation Composition Types
+===========================================
+Commissioning dialogues are used to commission and decommission Automation Composition Types and to set the values of Common Parameters. The values of common parameters are included in the TOSCA YAML file that defines the full Automation Composition Type.
-This dialogue sets the values of common properties. The values of the common properties
-may be set, updated, or deleted at will, as this dialogue saves the properties to the
-database but does not send the definitions or properties to the participants. However,
-once a Control Loop Type Definition and its properties are primed
-(See :ref:`Section 1.4 <priming-cl-label>`), the properties cannot be changed until the control loop type
-definition is de-primed (See :ref:`Section 1.5 <depriming-cl-label>`).
+2.1 Commission or Update an Automation Composition Type
+-------------------------------------------------------
+Create on a POST and update on a PUT.
-.. image:: ../images/system-dialogues/common-properties-type-definition.png
+.. image:: ../images/system-dialogues/CommissionUpdateAcType.png
-.. _priming-cl-label:
+2.2 Commission an Automation Composition Type using SDC
+-------------------------------------------------------
-1.4 Priming a Control Loop Type Definition on Participants
-----------------------------------------------------------
-The Priming operation sends Control Loop Type definitions and common property values
-to participants. Once a Control Loop Type definition is primed, its property values
-can on longer be changed until it is de-primed.
+.. image:: ../images/system-dialogues/CommissionAcTypeSDC.png
-.. image:: ../images/system-dialogues/priming-cl-type-definition.png
+2.3 Decommission an Automation Composition Type
+-----------------------------------------------
-.. _depriming-cl-label:
+.. image:: ../images/system-dialogues/DecommissionAcType.png
-1.5 De-Prime a Control Loop Type Definition on Participants
------------------------------------------------------------
+2.4 Prime an Automation Composition Type on Participants
+--------------------------------------------------------
+The Priming operation sends Automation Composition Types and common property values to participants for each Automation Composition Element Type in the Automation Composition Type.
-This dialogue allows a Control Loop Type Definition to be de-primed so that it can be
-deleted or its common parameter values can be altered.
+.. image:: ../images/system-dialogues/PrimeAcTypeOnPpnts.png
-.. image:: ../images/system-dialogues/depriming-cl-type-definition.png
+A participant should respond for each Automation Composition Element Type, thus causing the full Automation Composition Type to become primed. Note that if more than one participant can support an Automation Composition Element Type the ACM Runtime uses the participant in the first response it receives for that Automation Composition Element Type.
-1.6 Decommissioning a Control Loop Type Definition in CLAMP
------------------------------------------------------------
+.. image:: ../images/system-dialogues/PrimeAcTypeMultiplePpnts.png
-.. image:: ../images/system-dialogues/decommission-cl-type-definition.png
+The ACM Runtime updates the priming information in the database.
-1.7 Reading Commissioned Control Loop Type Definitions
-------------------------------------------------------
+.. image:: ../images/system-dialogues/PrimeInfoUpdatedInDb.png
-.. image:: ../images/system-dialogues/read-commision-cl-type-definition.png
+2.5 Deprime an Automation Composition Type on Participants
+----------------------------------------------------------
+The Depriming operation removes Automation Composition Types and common property values on participants for each Automation Composition Element Type in the Automation Composition Type.
+.. image:: ../images/system-dialogues/DeprimeOnParticipants.png
-2. Instantiation Dialogues
-==========================
+A participant should respond for each Automation Composition Element Type, thus causing the full Automation Composition Type to become deprimed.
-Instantiation dialogues are used to create, set parameters on, instantiate, update,
-and remove Control Loop instances.
+.. image:: ../images/system-dialogues/DeprimeElements.png
-Assume a suitable Control Loop Definition exists in the Commissioned Control Loop Inventory.
-To get a Control Loop instance running one would, for example, execute dialogues
-:ref:`2.1 <creating-cl-instance>`, :ref:`2.3 <updating-cl-instance-config>`, and
-:ref:`2.4 <changing-cl-instance-state>`.
+The ACM Runtime updates the priming information in the database.
-.. _creating-cl-instance:
+.. image:: ../images/system-dialogues/UpdateDeprimeInDb.png
-2.1 Creating a Control Loop Instance
+2.6 Get Automation Composition Types
------------------------------------
+This dialogue allows an Automation Composition Type to be read.
-.. image:: ../images/system-dialogues/create-cl-instance.png
+.. image:: ../images/system-dialogues/GetAcTypes.png
-.. note::
- This dialogue creates the Control Loop Instance in the Instantiated Control Loop Inventory.
- The instance is sent to the participants using the process described in the dialogue in
- :ref:`Section 2.3 <updating-cl-instance-config>`.
+3. Instantiation Dialogues
+==========================
+Instantiation dialogues are used to create, set parameters on, instantiate, update, and remove Automation Composition instances.
-2.2 Updating Instance Specific Parameters on a Control Loop Instance
---------------------------------------------------------------------
+3.1 Create an Automation Composition Instance
+---------------------------------------------
-.. image:: ../images/system-dialogues/update-instance-params-cl.png
+.. image:: ../images/system-dialogues/CreateAcInstance.png
-.. _updating-cl-instance-config:
+Note that this dialogue creates the Automation Composition Instance in the ACM database. The instance is sent to the participants using the process described in the dialogue in Section 3.3.
-2.3 Updating a Control Loop Instance with a Configuration on Participants
--------------------------------------------------------------------------
+3.2 Delete an Automation Composition Instance
+---------------------------------------------
+The user requests the AC Instance to be deleted using a REST endpoint. The ACM Runtime orders the AC Instance to be deleted.
-.. image:: ../images/system-dialogues/update-cl-instance-config-participants.png
+.. image:: ../images/system-dialogues/DeleteAcInstance.png
-.. _changing-cl-instance-state:
+Each participant deletes its AC Element Instances from the AC Instance
-2.4 Changing the state of a Control Loop Instance on Participants
------------------------------------------------------------------
+.. image:: ../images/system-dialogues/DeleteInstanceElements.png
-.. image:: ../images/system-dialogues/change-cl-instance-state-participants.png
+The ACM Runtime receives and stores the responses, when all instances element are deleted, it delete the instance.
-2.5 De-instantiating a Control Loop Instance from Participants
---------------------------------------------------------------
+.. image:: ../images/system-dialogues/DeleteResponseStored.png
-.. image:: ../images/system-dialogues/deinstantiate-cl-from-participants.png
+3.3 Deploy Automation Composition Instance
+------------------------------------------
+The user requests the AC Instance to be deployed using a REST endpoint. The ACM Runtime orders the AC Instance to be deployed to Participants.
-2.6 Deleting a Control Loop Instance
-------------------------------------
+.. image:: ../images/system-dialogues/DeployAcInstance.png
-.. image:: ../images/system-dialogues/delete-cl-instance.png
+Each participant deploys its AC Element Instances from the AC Instance.
-2.7 Reading Control Loop Instances
-----------------------------------
+.. image:: ../images/system-dialogues/DeployAcInstanceElements.png
-.. image:: ../images/system-dialogues/read-cl-instance.png
+The ACM Runtime receives and stores the responses.
+.. image:: ../images/system-dialogues/DeployResponseStored.png
-1. Monitoring Dialogues
-=======================
+3.4 Update Automation Composition Instance
+------------------------------------------
+The user requests the AC Instance to be updated using a REST endpoint. The ACM Runtime orders the AC Instance to be updated.
-Monitoring dialogues are used to monitor and to read statistics on Control Loop Instances.
+.. image:: ../images/system-dialogues/UpdateAcInstance.png
-3.1 Reporting of Monitoring Information and Statistics by Participants
-----------------------------------------------------------------------
+Each participant updates its AC Element from the AC Instance
-.. image:: ../images/system-dialogues/monitoring-by-participants.png
+.. image:: ../images/system-dialogues/UpdateAcElements.png
-3.2 Viewing of Monitoring Information
--------------------------------------
+The ACM Runtime receives and stores the responses.
-.. image:: ../images/system-dialogues/view-monitoring-info.png
+.. image:: ../images/system-dialogues/UpdateAcElementsResponse.png
-3.2 Viewing of Statistics
--------------------------
+3.5 Migrate Automation Composition Instance
+-------------------------------------------
+The user requests the AC Instance to be migrated using a REST endpoint. The ACM Runtime orders the AC Instance to be migrated.
-.. image:: ../images/system-dialogues/view-statistics.png
+.. image:: ../images/system-dialogues/MigrateAcInstance.png
-3.3 Statistics Housekeeping
----------------------------
+Each participant migrated its AC Element from the AC Instance
-.. image:: ../images/system-dialogues/statistics-housekeeping.png
+.. image:: ../images/system-dialogues/MigrateAcElements.png
+The ACM Runtime receives and stores the responses.
-4. Supervision Dialogues
-========================
+.. image:: ../images/system-dialogues/MigrateAcElementsResponse.png
-Supervision dialogues are used to check the state of Control Loop Instances and Participants.
+3.6 Undeploy Automation Composition Instance
+--------------------------------------------
+The user requests the AC Instance to be undeployed using a REST endpoint. The ACM Runtime orders the AC Instance to be undeployed.
-4.1 Supervise Participants
---------------------------
+.. image:: ../images/system-dialogues/UndeployInstance.png
+
+Each participant undeploys its AC Element Instances from the AC Instance
+
+.. image:: ../images/system-dialogues/UndeployInstanceElements.png
+
+The ACM Runtime receives and stores the responses.
+
+.. image:: ../images/system-dialogues/UndeployResponseStored.png
+
+3.7 Read Automation Composition Instances
+-----------------------------------------
+
+.. image:: ../images/system-dialogues/ReadAcInstances.png
+
+3.8 Unlock Automation Composition Instance
+------------------------------------------
+The user requests the AC Instance to be unlocked using a REST endpoint. The ACM Runtime orders the AC Instance to be unlocked on Participants.
+
+.. image:: ../images/system-dialogues/OrderInstanceUnlock.png
+
+Each participant unlocks its AC Element Instances from the AC Instance.
+
+.. image:: ../images/system-dialogues/UnlockInstanceElements.png
+
+The ACM Runtime receives and stores the responses.
+
+.. image:: ../images/system-dialogues/UnlockResponseStored.png
+
+3.9 Lock Automation Composition Instance
+----------------------------------------
+The user requests the AC Instance to be locked using a REST endpoint. The ACM Runtime orders the AC Instance to be locked on Participants.
+
+.. image:: ../images/system-dialogues/LockAcInstance.png
+
+Each participant locks its AC Element Instances from the AC Instance.
+
+.. image:: ../images/system-dialogues/LockAcInstanceElements.png
+
+The ACM Runtime receives and stores the responses.
+
+.. image:: ../images/system-dialogues/LockResponseStored.png
+
+3.10 Update Operational State on Automation Composition Instance
+----------------------------------------------------------------
+
+.. image:: ../images/system-dialogues/UpdateOperationalState.png
+
+3.11 Update Usage State on Automation Composition Instance
+----------------------------------------------------------
+
+.. image:: ../images/system-dialogues/UpdateUsageState.png
-.. image:: ../images/system-dialogues/supervise-participants.png
+3.12 Failure handling in ACM
+----------------------------
+After any ACM operation is completed, one of the following result messages will be updated in the ACM. These result values are
+updated along with the overall state of the ACM instance.
-4.2 Supervise Control Loops
----------------------------
+ - NO_ERROR
+ - TIMEOUT
+ - FAILED
-.. image:: ../images/system-dialogues/supervise-controlloops.png
+The enum result values 'NO_ERROR' and 'FAILED' have to be set by the participants while reporting the CompositionState back to the runtime.
+
+If the operation succeeds, the participant is required to update the result value with 'NO_ERROR' while reporting the composition state.
+
+.. image:: ../images/system-dialogues/SuccessAcmResult.png
+
+The result value should be updated as 'FAILED' by the participants when any failures occurred.
+Also in case of failures, the overall state of the composition/instance remains in any of the transitioning states (DEPLOYING, UNDEPLOYING, PRIMING, DEPRIMING, UPDATING, MIGRATING)
+with the appropriate result values updated by the participant.
+
+.. image:: ../images/system-dialogues/FailedAcmResult.png
+
+Runtime marks the operation result with the value 'TIMEOUT' when the participant fails to report the message back during an ACM operation,
+the operation result is then marked as 'TIMEOUT' by the ACM-R after the configured waiting limit is reached.
+
+.. image:: ../images/system-dialogues/TimeoutAcmResult.png
+
+The following parameter is set in the application properties for the runtime to configure the 'TIMEOUT' value in milliseconds.
+
+.. code-block:: yaml
+
+ runtime:
+ participantParameters:
+ maxStatusWaitMs: 100000 --> Denotes the maximum wait time by the runtime to receive the periodic status update from the participants
+
+An ACM operation has to be completed and updated with any of the above specified result values in order to allow the user to trigger subsequent requests.
+The user cannot trigger any state change events before the operation gets completed. When an operation is marked 'TIMEOUT', the following scenarios are applicable.
+
+ - The participant might complete the operation to mark the result with 'NO_ERROR' or 'FAILED'
+ - The user can trigger another state change event to the ACM.
+
+The following flow shown and example of deployment that get stuck, and the user decide to undeploy.
+
+.. image:: ../images/system-dialogues/TimeoutParticipant.png
+
+
+3.13 OFF_LINE handling in ACM
+-----------------------------
+Runtime marks the participant state with the value 'OFF_LINE' when the participant fails to report the periodic heartbeat,
+the participant state is then marked as 'OFF_LINE' by the ACM-R after the configured waiting limit is reached.
+That scenario might happen when participant is shutdown, in that scenario all on going operations with that participant are marked 'TIMEOUT' due the missing messages back.
+
+The user cannot trigger any state change events when participant state is 'OFF_LINE'.
+
+.. image:: ../images/system-dialogues/OfflineAcmResult.png
+
+When a participant state is marked 'OFF_LINE', it might come back ONLINE and the user can trigger state change events to the ACM.
End of Document
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Code Review / policy / parent.git / blobdiff