docs/clamp/acm/api-protocol/system-level-dialogues.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _system-level-label:
   4
   5 ACM System Level Dialogues
   6 ##########################
   7 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.
   8
   9
  10 .. contents::
  11     :depth: 4
  12
  13
  14 1 Dialogues on Participants
  15 ===========================
  16 1.1 Register a Participant
  17 --------------------------
  18
  19 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.
  20
  21 .. image:: ../images/system-dialogues/RegisterParticipant.png
  22
  23 1.2 Deregister a Participant
  24 ----------------------------
  25 Participant Deregistration is performed by a Participant when it shuts down. It deregisters its ID and type with the ACM runtime.
  26
  27 .. image:: ../images/system-dialogues/DeregisterParticipant.png
  28
  29 1.3 Supervise Participants
  30 --------------------------
  31 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.
  32
  33 .. image:: ../images/system-dialogues/SuperviseParticipantsStatusUpdate.png
  34
  35 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.
  36
  37 .. image:: ../images/system-dialogues/SuperviseParticipantsTimeout.png
  38
  39 1.4 Get Participant Information
  40 -------------------------------
  41 The information on participants is available over a REST endpoint.
  42
  43 .. image:: ../images/system-dialogues/GetParticipantInformation.png
  44
  45 1.5 Order Full Participant Report
  46 ---------------------------------
  47
  48 .. image:: ../images/system-dialogues/FullParticipantReport.png
  49
  50 2 Dialogues on Automation Composition Types
  51 ===========================================
  52 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.
  53
  54 2.1 Commission or Update an Automation Composition Type
  55 -------------------------------------------------------
  56 Create on a POST and update on a PUT.
  57
  58 .. image:: ../images/system-dialogues/CommissionUpdateAcType.png
  59
  60 2.2 Commission an Automation Composition Type using SDC
  61 -------------------------------------------------------
  62
  63 .. image:: ../images/system-dialogues/CommissionAcTypeSDC.png
  64
  65 2.3 Decommission an Automation Composition Type
  66 -----------------------------------------------
  67
  68 .. image:: ../images/system-dialogues/DecommissionAcType.png
  69
  70 2.4 Prime an Automation Composition Type on Participants
  71 --------------------------------------------------------
  72 The Priming operation sends Automation Composition Types and common property values to participants for each Automation Composition Element Type in the Automation Composition Type.
  73
  74 .. image:: ../images/system-dialogues/PrimeAcTypeOnPpnts.png
  75
  76 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.
  77
  78 .. image:: ../images/system-dialogues/PrimeAcTypeMultiplePpnts.png
  79
  80 The ACM Runtime updates the priming information in the database.
  81
  82 .. image:: ../images/system-dialogues/PrimeInfoUpdatedInDb.png
  83
  84 2.5 Deprime an Automation Composition Type on Participants
  85 ----------------------------------------------------------
  86 The Depriming operation removes Automation Composition Types and common property values on participants for each Automation Composition Element Type in the Automation Composition Type.
  87
  88 .. image:: ../images/system-dialogues/DeprimeOnParticipants.png
  89
  90 A participant should respond for each Automation Composition Element Type, thus causing the full Automation Composition Type to become deprimed.
  91
  92 .. image:: ../images/system-dialogues/DeprimeElements.png
  93
  94 The ACM Runtime updates the priming information in the database.
  95
  96 .. image:: ../images/system-dialogues/UpdateDeprimeInDb.png
  97
  98 2.6 Get Automation Composition Types
  99 ------------------------------------
 100 This dialogue allows an Automation Composition Type to be read.
 101
 102 .. image:: ../images/system-dialogues/GetAcTypes.png
 103
 104 3. Instantiation Dialogues
 105 ==========================
 106 Instantiation dialogues are used to create, set parameters on, instantiate, update, and remove Automation Composition instances.
 107
 108 3.1 Create an Automation Composition Instance
 109 ---------------------------------------------
 110
 111 .. image:: ../images/system-dialogues/CreateAcInstance.png
 112
 113 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.
 114
 115 3.2 Delete an Automation Composition Instance
 116 ---------------------------------------------
 117 The user requests the AC Instance to be deleted using a REST endpoint. The ACM Runtime orders the AC Instance to be deleted.
 118
 119 .. image:: ../images/system-dialogues/DeleteAcInstance.png
 120
 121 Each participant deletes its AC Element Instances from the AC Instance
 122
 123 .. image:: ../images/system-dialogues/DeleteInstanceElements.png
 124
 125 The ACM Runtime receives and stores the responses, when all instances element are deleted, it delete the instance.
 126
 127 .. image:: ../images/system-dialogues/DeleteResponseStored.png
 128
 129 3.3 Deploy Automation Composition Instance
 130 ------------------------------------------
 131 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.
 132
 133 .. image:: ../images/system-dialogues/DeployAcInstance.png
 134
 135 Each participant deploys its AC Element Instances from the AC Instance.
 136
 137 .. image:: ../images/system-dialogues/DeployAcInstanceElements.png
 138
 139 The ACM Runtime receives and stores the responses.
 140
 141 .. image:: ../images/system-dialogues/DeployResponseStored.png
 142
 143 3.4 Update Automation Composition Instance
 144 ------------------------------------------
 145 The user requests the AC Instance to be updated using a REST endpoint. The ACM Runtime orders the AC Instance to be updated.
 146
 147 .. image:: ../images/system-dialogues/UpdateAcInstance.png
 148
 149 Each participant updates its AC Element from the AC Instance
 150
 151 .. image:: ../images/system-dialogues/UpdateAcElements.png
 152
 153 The ACM Runtime receives and stores the responses.
 154
 155 .. image:: ../images/system-dialogues/UpdateAcElementsResponse.png
 156
 157 3.5 Undeploy Automation Composition Instance
 158 --------------------------------------------
 159 The user requests the AC Instance to be undeployed using a REST endpoint. The ACM Runtime orders the AC Instance to be undeployed.
 160
 161 .. image:: ../images/system-dialogues/UndeployInstance.png
 162
 163 Each participant undeploys its AC Element Instances from the AC Instance
 164
 165 .. image:: ../images/system-dialogues/UndeployInstanceElements.png
 166
 167 The ACM Runtime receives and stores the responses.
 168
 169 .. image:: ../images/system-dialogues/UndeployResponseStored.png
 170
 171 3.6 Read Automation Composition Instances
 172 -----------------------------------------
 173
 174 .. image:: ../images/system-dialogues/ReadAcInstances.png
 175
 176 3.7 Unlock Automation Composition Instance
 177 ------------------------------------------
 178 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.
 179
 180 .. image:: ../images/system-dialogues/OrderInstanceUnlock.png
 181
 182 Each participant unlocks its AC Element Instances from the AC Instance.
 183
 184 .. image:: ../images/system-dialogues/UnlockInstanceElements.png
 185
 186 The ACM Runtime receives and stores the responses.
 187
 188 .. image:: ../images/system-dialogues/UnlockResponseStored.png
 189
 190 3.8 Lock Automation Composition Instance
 191 ----------------------------------------
 192 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.
 193
 194 .. image:: ../images/system-dialogues/LockAcInstance.png
 195
 196 Each participant locks its AC Element Instances from the AC Instance.
 197
 198 .. image:: ../images/system-dialogues/LockAcInstanceElements.png
 199
 200 The ACM Runtime receives and stores the responses.
 201
 202 .. image:: ../images/system-dialogues/LockResponseStored.png
 203
 204 3.9 Update Operational State on Automation Composition Instance
 205 ---------------------------------------------------------------
 206
 207 .. image:: ../images/system-dialogues/UpdateOperationalState.png
 208
 209 3.10 Update Usage State on Automation Composition Instance
 210 ----------------------------------------------------------
 211
 212 .. image:: ../images/system-dialogues/UpdateUsageState.png
 213
 214 3.11 Failure handling in ACM
 215 ----------------------------
 216 After any ACM operation is completed, one of the following result messages will be updated in the ACM. These result values are
 217 updated along with the overall state of the ACM instance.
 218
 219  - NO_ERROR
 220  - TIMEOUT
 221  - FAILED
 222
 223 The enum result values 'NO_ERROR' and 'FAILED' have to be set by the participants while reporting the CompositionState back to the runtime.
 224
 225 If the operation succeeds, the participant is required to update the result value with 'NO_ERROR' while reporting the composition state.
 226
 227 .. image:: ../images/system-dialogues/SuccessAcmResult.png
 228
 229 The result value should be updated as 'FAILED' by the participants when any failures occurred.
 230 Also in case of failures, the overall state of the composition remains in any of the transitioning states (DEPLOYING, UNDEPLOYING, PRIMING, UPDATING)
 231 with the appropriate result values updated by the participant.
 232
 233 .. image:: ../images/system-dialogues/FailedAcmResult.png
 234
 235 Runtime marks the operation result with the value 'TIMEOUT' when the participant gets disconnected from the ACM-R in the middle of any ACM operation.
 236 When the participant fails to report the periodic heartbeat during an ACM operation, the operation result is then marked as 'TIMEOUT' by the ACM-R after the configured waiting limit is
 237 reached.
 238
 239 .. image:: ../images/system-dialogues/TimeoutAcmResult.png
 240
 241 The following parameter is set in the application properties for the runtime to configure the 'TIMEOUT' value in milliseconds.
 242
 243 .. code-block:: yaml
 244
 245         runtime:
 246           participantParameters:
 247             maxStatusWaitMs: 100000  --> Denotes the maximum wait time by the runtime to receive the periodic status update from the participants
 248
 249 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.
 250 The user cannot trigger any state change events before the operation gets completed. When an operation is marked 'TIMEOUT', the following scenarios are applicable.
 251
 252  - The participant might come back ONLINE and complete the operation to mark the result with 'NO_ERROR' or 'FAILED'
 253  - The user can trigger another state change event to the ACM.
 254
 255 End of Document
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270