1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
3 .. _acm-participant-protocol-label:
5 The ACM Automation Composition Participant Protocol
6 ###################################################
8 The CLAMP Automation Composition protocol is an asynchronous protocol that is used by the CLAMP
9 runtime to coordinate lifecycle management of Automation Composition instances. The protocol
10 supports the functions described in the sections below.
16 The protocol supports the dialogues described below.
18 Participant Registration and De-Registration
19 --------------------------------------------
21 Registration when a participant comes up and update of participant with Automation Composition type
22 information and common parameter values for its Automation Composition types.
24 .. image:: ../images/acm-participants-protocol/participant-registering.png
27 De-registration is executed as a participant goes down.
29 .. image:: ../images/acm-participants-protocol/participant-deregistration.png
32 Automation Composition Priming and De-Priming
33 ---------------------------------------------
35 When an Automation Composition is primed, the portion of the Automation Composition Type Definition
36 and Common Property values for the participants of each participant type mentioned in the
37 Automation Composition Definition are sent to the participants.
39 .. image:: ../images/acm-participants-protocol/acm-priming.png
41 When an Automation Composition is de-primed, the portion of the Automation Composition Type
42 Definition and Common Property values for the participants of each participant type mentioned in
43 the Automation Composition Definition are deleted on participants.
45 .. image:: ../images/acm-participants-protocol/acm-depriming.png
48 Automation Composition Update
49 -----------------------------
51 Automation Composition Update handles creation, change, and deletion of Automation Compositions on
52 participants. Change of Automation Compositions uses a semantic versioning approach and follows the
53 semantics described on the page :ref:`4.1 Management of Automation Composition Instance
54 Configurations <management-acm-instance-configs>`.
56 .. image:: ../images/acm-participants-protocol/acm-update.png
58 The handling of an *ACMUpdate* message in each participant is as shown below.
60 .. image:: ../images/acm-participants-protocol/acm-update-msg.png
62 Automation Composition State Change
63 -----------------------------------
65 This dialogue is used to change the state of Automation Compositions and their Automation
66 Composition Elements. The CLAMP Runtime sends an Automation Composition State Change message on the
67 Automation Composition to all participants. Participants that have Automation Composition Elements
68 in that Automation Composition attempt an update on the state of the Automation Composition
69 elements they have for that Automation Composition, and report the result back.
71 The *startPhase* in the `Definition of TOSCA fundamental Automation Composition Types
72 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/AutomationCompositionTOSCAServiceTemplateTypes.yaml>`_
73 is particularly important in Automation Composition state changes because sometimes the user wishes
74 to control the order in which the state changes in Automation Composition Elements in an Automation
75 Composition. In-state changes from *UNITITIALISED → PASSIVE* and from *PASSIVE → RUNNING*,
76 Automation Composition elements are started in increasing order of their startPhase. In-state
77 changes from *RUNNING → PASSIVE* and from *PASSIVE → UNITITIALISED*, Automation Composition
78 elements are started in decreasing order of their *startPhase*.
80 The CLAMP runtime controls the state change process described in the diagram below. The CLAMP
81 runtime sends an Automation Composition state change message on DMaaP to all participants in a
82 particular start phase so, in each state change multiple Automation Composition State Change
83 messages are sent, one for each start phase in the Automation Composition. If more than one
84 Automation Composition Element has the same start phase, those Automation Composition Elements
85 receive the same Automation Composition State Change message from DMaaP and start in parallel.
87 The Participant reads each State Change Message it sees on DMaaP. If the start phase on the
88 Automation Composition State Change message matches the Start Phase of the Automation Composition
89 Element, the participant processes the state change message. Otherwise, the participant ignores the
92 .. image:: ../images/acm-participants-protocol/acm-state-change.png
94 The handling of an ACMStateChange message in each participant is as shown below.
96 .. image:: ../images/acm-participants-protocol/acm-state-change-msg.png
98 Automation Composition Monitoring and Reporting
99 -----------------------------------------------
101 This dialogue is used as a heartbeat mechanism for participants, to monitor the status of
102 Automation Composition Elements, and to gather statistics on Automation Compositions. The
103 *ParticipantStatus* message is sent periodically by each participant. The reporting interval for
104 sending the message is configurable.
106 .. image:: ../images/acm-participants-protocol/acm-monitoring.png
112 The CLAMP Automation Composition Participant Protocol uses the following messages. The
113 descriptions below give an overview of each message. For the precise definition of the messages,
114 see the `CLAMP code at Github
115 <https://github.com/onap/policy-clamp/tree/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/dmaap/participant>`_
116 . All messages are carried on DMaaP.
120 :widths: 15 10 10 15 15 35
129 * - ParticipantRegister
132 - Participant registers with the CLAMP runtime
134 - The ID of this participant
140 - The type of the participant; maps to the capabilities of the participant in Automation
141 Composition Type Definitions
142 * - ParticipantRegisterAck
145 - Acknowledgment of Participant Registration
147 - The ID of this participant
153 - The type of the participant; maps to the capabilities of the participant in Automation
154 Composition Type Definitions
166 - A message indicating the reason for failure
167 * - ParticipantUpdate
170 - CLAMP Runtime sends Automation Composition Element Definitions and Common Parameter Values
172 - ParticipantDefinitionUpdateMap
173 - Map with Participant ID as its key, each value on the map is an ACMElementDefintionMap
178 - ACMElementDefintionMap
179 - List of ACMElementDefinition values for a particular participant, keyed by its Automation
180 Composition Element Definition ID
185 - ACMElementDefinition
186 - An ACMElementToscaServiceTemplate containing the definition of the Automation Composition
187 Element and a CommonPropertiesMap with the values of the common property values for
188 Automation Composition Elements of this type
193 - ACMElementToscaServiceTemplate
194 - The definition of the Automation Composition Element in TOSCA
199 - CommonPropertiesMap
200 - A <String, String> map indexed by the property name. Each map entry is the serialized value
201 of the property, which can be deserialized into an instance of the type of the property.
202 * - ParticipantUpdateAck
205 - Acknowledgment of Participant Update
207 - The ID of this participant
213 - The type of the participant; maps to the capabilities of the participant in Automation
214 Composition Type Definitions
226 - A message indicating the reason for failure
227 * - ParticipantDeregister
230 - Participant deregisters with the CLAMP runtime
232 - The ID of this participant
238 - The type of the participant; maps to the capabilities of the participant in Automation
239 Composition Type Definitions
240 * - ParticipantDeregisterAck
243 - Acknowledgment of Participant Deegistration
245 - The ID of this participant
251 - The type of the participant; maps to the capabilities of the participant in Automation
252 Composition Type Definitions
264 - A message indicating the reason for failure
268 - CLAMP Runtime sends Automation Composition Element instances and Instance Specific Parameter
269 Values for an Automation Composition Instance to Participants
271 - The name and version of the Automation Composition
276 - ParticipantUpdateMap
277 - Map with Participant ID as its key, each value on the map is an ACMElementList
283 - List of ACMElement values for the Automation Composition
289 - An ACMElement, which contains among other things a PropertiesMap with the values of the
290 property values for this Automation Composition Element instance and a
291 ToscaServiceTemplateFragment with extra concept definitions and instances that a participant
298 - A <String, String> map indexed by the property name. Each map entry is the serialized value
299 of the property, which can be deserialized into an instance of the type of the property.
304 - ToscaServiceTemplateFragment
305 - A well-formed TOSCA service template containing extra concept definitions and instances that
306 a participant may need. For example, the Policy Participant may need policy type definitions
307 or policy instances to be provided if they are not already stored in the Policy Framework.
311 - Acknowledgment of Automation Composition Update
313 - The ID of this participant
319 - The type of the participant; maps to the capabilities of the participant in Automation
320 Composition Type Definitions
326 - The name and version of the Automation Composition
332 - Holds a Result and Message for the overall operation on the participant and a map of Result
333 and Message fields for each Automation Composition Element of the Automation Composition on
346 - A message indicating the reason for failure
350 - CLAMP Runtime asks Participants to change the state of an Automation Composition
352 - The name and version of the Automation Composition
358 - The current state of the Automation Composition
364 - The state that the Automation Composition should transition to
370 - The start phase to which this ACMStateChange message applies
371 * - ACMStateChangeAck
374 - Acknowledgment of Automation Composition State Change
376 - The ID of this participant
382 - The type of the participant; maps to the capabilities of the participant in Automation
383 Composition Type Definitions
389 - The name and version of the Automation Composition
395 - The start phase to which this ACMStateChangeAck message applies
401 - Holds a Result and Message for the overall operation on the participant and a map of Result
402 and Message fields for each Automation Composition Element of the Automation Composition on
415 - A message indicating the reason for failure
416 * - ParticipantStatusReq
419 - Request that the specified participants return a ParticipantStatus message immediately
421 - The ID of this participant, if not specified, all participants respond.
422 * - ParticipantStatus
425 - Periodic or on-demand report for heartbeat, Participant Status, Automation Composition
426 Status, and Automation Composition Statistics
428 - The ID of this participant
434 - The type of the participant; maps to the capabilities of the participant in Automation
435 Composition Type Definitions
440 - ParticipantDefinitionUpdateMap (returned in repsonse to ParticipantStatusReq only)
441 - See ParticipantUpdate message above for definition of this field
447 - The current status of the participant for monitoring
452 - ParticipantStatistics
453 - Statistics on the participant such as uptime, or messages processed. Can include participant
454 specific data in a string blob that is opaque to CLAMP
460 - A map of ACMInfo types indexed by ACMId, one entry for each Automation Composition
461 running on the participant
467 - The ACMStatus and ACMStatistics for a given Automation Composition
473 - The current status of the Automation Composition for monitoring
479 - Statistics on the Automation Composition such as uptime, or messages processed. Can include
480 participant specific data in a string blob that is opaque to CLAMP