aboutsummaryrefslogtreecommitdiffstats
path: root/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
blob: 493022d1e8d29b9dd6762bd38f11ef6e18eb7fa5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
.. This work is licensed under a Creative Commons Attribution 4.0 International License.

.. _clamp-acm-participant-intermediary:

Participant Intermediary
########################

The CLAMP Participant Intermediary is a common library in ONAP, which does common message and
state handling for participant implementations. It provides a Java API, which participant
implementations implement to receive and send messages to the CLAMP runtime and to handle
Automation Composition Element state.

Terminology
-----------
- Broadcast message: a message for all participants (participantId=null)
- Message to a participant: a message only for a participant (participantId properly filled)
- MessageSender: a class that takes care of sending messages from participant-intermediary
- GUI: graphical user interface, Postman or a Front-End Application
- Message Broker: It supports the message Broker Kafka

Inbound messages to participants
--------------------------------
- PARTICIPANT_REGISTER_ACK: received as a response from clamp-acm runtime server as an acknowledgement to ParticipantRegister message sent from a participant
- PARTICIPANT_DEREGISTER_ACK: received as a response from clamp-acm runtime server as an acknowledgement to ParticipantDeregister message sent from a participant
- AUTOMATION_COMPOSITION_STATE_CHANGE: a message received from clamp-acm runtime server for a state change of clamp-acm
- AUTOMATION_COMPOSITION_DEPLOY: a message received from clamp-acm runtime server for a clamp-acm deploy with clamp-acm instances
- PARTICIPANT_PRIME: a message received from clamp-acm runtime server for a participant update with tosca definitions of clamp-acm
- PARTICIPANT_STATUS_REQ: A status request received from clamp-acm runtime server to send an immediate ParticipantStatus from all participants
- PROPERTIES_UPDATE: a message received from clamp-acm runtime server for updating the Ac instance property values
- AUTOMATION_COMPOSITION_MIGRATION: a message received from clamp-acm runtime server for migrating the Ac instance from a composition definition to a composition definition target
- PARTICIPANT_SYNC_MSG: a message received from clamp-acm runtime server with tosca definitions and the Ac instances to handle synchronization

Outbound messages
-----------------
- PARTICIPANT_REGISTER: is sent by a participant during startup
- PARTICIPANT_DEREGISTER: is sent by a participant during shutdown
- PARTICIPANT_STATUS: is sent by a participant as heartbeat with the status and health of a participant
- AUTOMATIONCOMPOSITION_STATECHANGE_ACK: is an acknowledgement sent by a participant as a response to AutomationCompositionStateChange
- AUTOMATION_COMPOSITION_DEPLOY_ACK: is an acknowledgement sent by a participant as a response to AutomationCompositionDeploy
- PARTICIPANT_PRIME_ACK: is an acknowledgement sent by a participant as a response to ParticipantPrime

Design of a PARTICIPANT_REGISTER message
----------------------------------------
- A participant starts and send a PARTICIPANT_REGISTER message with participantId, replicaId and Supported Element Definition Types
- in AC-runtime ParticipantRegisterListener collects the message from Message Broker
- if participant is not present in DB, it saves participant reference with status ON_LINE to DB
- It triggers the execution to send a PARTICIPANT_REGISTER_ACK message to the participant registered
- if participant is present in DB and there are AC Definitions related to the Participant, 
  it triggers the execution to send a PARTICIPANT_SYNC_MSG message to synchronize participant

Design of a PARTICIPANT_DEREGISTER message
------------------------------------------
- A participant is going to close and undeploys all AC-elements and send a PARTICIPANT_DEREGISTER message
- in AC-runtime, ParticipantDeregisterListener collects the message from Message Broker
- It saves participant reference with status OFF_LINE to DB
- It triggers the execution to send a PARTICIPANT_DEREGISTER_ACK message to the participant deregistered
- Participant is not monitored.

Prime of an Automation Composition Definition Type
--------------------------------------------------
- AC-runtime assigns the AC Definition to the participants based of Supported Element Definition Type by participant
- it triggers the execution to send a broadcast PARTICIPANT_PRIME message
- the message is built by ParticipantPrimePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition)
- Participant-intermediary will receive a PARTICIPANT_PRIME message and stores the Tosca Service Template data on CacheProvider

DePrime of an Automation Composition Definition Type
----------------------------------------------------
- AC-runtime triggers the execution to send a broadcast PARTICIPANT_PRIME message
- the message is built by ParticipantPrimePublisher with an empty list of ParticipantDefinition
- Participant-intermediary will receive a PARTICIPANT_PRIME message and deletes the Tosca Service Template data on CacheProvider

Design of "issues automation composition commands to automation compositions" - case UNDEPLOYED to DEPLOYED
-----------------------------------------------------------------------------------------------------------
- AUTOMATION_COMPOSITION_DEPLOY message with instantiation details and DEPLOY order state is sent to participants
- Participant-intermediary validates the current deployState change
- Participant-intermediary will receive AUTOMATION_COMPOSITION_DEPLOY message and sends the details of AutomationCompositionElements to participants
- Each participant performs its designated job of deployment by interacting with respective frameworks

Design of "issues automation composition commands to automation compositions" - case DEPLOYED to UNDEPLOYED
-----------------------------------------------------------------------------------------------------------
- AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and UNDEPLOY order state is sent to participants
- Participant-intermediary validates the current deployState change
- Participant-intermediary will receive AUTOMATION_COMPOSITION_STATE_CHANGE message and sends AC-element details to participants
- Each participant performs its designated job of undeployment by interacting with respective frameworks

Update of an Automation Composition Instance
--------------------------------------------
- AC-runtime updates the instance properties of the deployed Ac instances
- it triggers the execution to send a broadcast PROPERTIES_UPDATE message
- the message is built by AcElementPropertiesPublisher using the REST request payload (to fill the list of elements with the updated property values)
- Participant-intermediary will receive a PROPERTIES_UPDATE message and stores the updated values of the elements on CacheProvider

Migrate of an Automation Composition Instance
---------------------------------------------
- AC-runtime saves the compositionTargetId and updates the instance properties of the deployed Ac instances
- it triggers the execution to send a broadcast AUTOMATION_COMPOSITION_MIGRATION message
- the message is built by AutomationCompositionMigrationPublisher using the REST request payload (to fill the compositionTargetId and list of elements with the updated property values)
- Participant-intermediary will receive a AUTOMATION_COMPOSITION_MIGRATION message and stores the compositionTargetId and the updated values of the elements on CacheProvider

Design of "issues automation composition commands to automation compositions" - case LOCKED to UNLOCKED
-------------------------------------------------------------------------------------------------------
- AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and UNLOCK order state is sent to participants
- Participant-intermediary validates the current lockState change
- Participant-intermediary will receive AUTOMATION_COMPOSITION_STATE_CHANGE message

Design of "issues automation composition commands to automation compositions" - case UNLOCKED to LOCKED
-------------------------------------------------------------------------------------------------------
- AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and LOCK order state is sent to participants
- Participant-intermediary validates the current lockState change

Design of Delete - case UNDEPLOYED to DELETED
---------------------------------------------
- AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and DELETE order state is sent to participants
- Participant-intermediary validates the current deployState change
- Participant-intermediary will receive AUTOMATION_COMPOSITION_STATE_CHANGE message and sends AC-element details to participants
- Each participant performs its designated job of removing instantiation data if not done in undeployment
- Participant-intermediary will remove instantiation data

Design of a PARTICIPANT_STATUS_REQ message
------------------------------------------
- AC-runtime triggers the execution to send a broadcast PARTICIPANT_STATUS_REQ message or to send it to a specific participant
- the message is built by ParticipantStatusReqPublisher
- Participant-intermediary will receive a PARTICIPANT_STATUS_REQ message

Design of a PARTICIPANT_STATUS message
--------------------------------------
- A participant sends a scheduled PARTICIPANT_STATUS message or in response to a PARTICIPANT_STATUS_REQ message
- This message will hold the state and healthStatus of all the participants running actively
- PARTICIPANT_STATUS message holds a special attribute to return Tosca definitions, this attribute is populated only in response to PARTICIPANT_STATUS_REQ

Design of a AUTOMATION_COMPOSITION_DEPLOY_ACK message
-----------------------------------------------------
- A participant sends AUTOMATION_COMPOSITION_DEPLOY_ACK message in response to a AUTOMATION_COMPOSITION_DEPLOY message.
- For each AC-elements moved to the ordered state as indicated by the AUTOMATION_COMPOSITION_DEPLOY
- AutomationCompositionUpdateAckListener in AC-runtime collects the messages from Message Broker
- It checks the deployStatus of all automation composition elements
- It updates the AC-instance in DB accordingly

Design of a AUTOMATIONCOMPOSITION_STATECHANGE_ACK message
---------------------------------------------------------
- A participant sends AUTOMATIONCOMPOSITION_STATECHANGE_ACK message in response to a AUTOMATIONCOMPOSITION_STATECHANGE message.
- For each AC-elements moved to the ordered state as indicated by the AUTOMATIONCOMPOSITION_STATECHANGE
- AutomationCompositionStateChangeAckListener in AC-runtime collects the messages from Message Broker
- It checks the deployStatus/lockStatus of all automation composition elements
- It updates the AC-instance in DB accordingly