Merge "Updated participant protocol docs"

diff --git a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
index d9d24ce..6ebc76f 100644 (file)
--- a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
+++ b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
@@ -12,18 +12,19 @@ Automation Composition Element state.
 
 Terminology
 -----------
-- Broadcast message: a message for all participants (participantId=null and participantType=null)
-- Message to a participant: a message only for a participant (participantId and participantType properly filled)
+- 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: supported message Broker are DMaap and Strimzi-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_UPDATE: a message received from clamp-acm runtime server for a clamp-acm update with clamp-acm instances
-- PARTICIPANT_UPDATE: a message received from clamp-acm runtime server for a participant update with tosca definitions 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
 
 Outbound messages
@@ -32,98 +33,86 @@ Outbound messages
 - 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
-- AUTOMATIONCOMPOSITION_UPDATE_ACK: is an acknowledgement sent by a participant as a response to AutomationCompositionUpdate
-- PARTICIPANT_UPDATE_ACK: is an acknowledgement sent by a participant as a response to ParticipantUpdate
+- 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
-- ParticipantRegisterListener collects the message from DMaap
-- if participant is not present in DB, it saves participant reference with status UNKNOWN to DB
-- if participant is present in DB, it triggers the execution to send a PARTICIPANT_UPDATE message to the participant registered (message of Priming)
-- the message is built by ParticipantUpdatePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition)
+- A participant starts and send a PARTICIPANT_REGISTER message with participantId 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
-- MessageIntercept intercepts that event, if PARTICIPANT_UPDATE message has been sent, it will be add a task to handle PARTICIPANT_REGISTER in SupervisionScanner
-- SupervisionScanner starts the monitoring for participantUpdate
 
 Design of a PARTICIPANT_DEREGISTER message
 ------------------------------------------
-- A participant starts and send a PARTICIPANT_DEREGISTER message
-- ParticipantDeregisterListener collects the message from DMaap
-- if participant is not present in DB, do nothing
-- if participant is present in DB, it triggers the execution to send a PARTICIPANT_UPDATE message to the participant registered (message of DePriming)
-- the message is built by ParticipantUpdatePublisher using Tosca Service Template data as null
-- ParticipantHandler removes the tosca definitions stored
-- It triggers the execution to send a PARTICIPANT_DEREGISTER_ACK message to the participant registered
+- 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
+- if participant has AC-elements instance, it updates with UNDEPLOYED deployStatus
+- It triggers the execution to send a PARTICIPANT_DEREGISTER_ACK message to the participant deregistered
 - Participant is not monitored.
 
-Design of a creation of an Automation Composition Type
-------------------------------------------------------
-- If there are participants registered with CL-runtime, it triggers the execution to send a broadcast PARTICIPANT_UPDATE message
-- the message is built by ParticipantUpdatePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition)
-- Participant-intermediary will receive a PARTICIPANT_UDPATE message and stores the Tosca Service Template data on ParticipantHandler
-
-Design of a deletion of an Automation Composition Type
-------------------------------------------------------
-- if there are participants registered, CL-runtime triggers the execution to send a broadcast PARTICIPANT_UPDATE message
-- the message is built by ParticipantUpdatePublisher with an empty list of ParticipantDefinition
-- It deletes the Automation Composition Type from DB
-- Participant-intermediary will receive a PARTICIPANT_UDPATE message and deletes the Tosca Service Template data on ParticipantHandler
-
-Design of a creation of an Automation Composition
--------------------------------------------------
-- AUTOMATION_COMPOSITION_UPDATE message with instantiation details and UNINITIALISED state is sent to participants
-- Participant-intermediary validates the current state change
-- Participant-intermediary will recieve AUTOMATION_COMPOSITION_UPDATE message and sends the details of AutomationCompositionElements to participants
-- Each participant performs its designated job of deployment by interacting with respective frameworks
+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 ParticipantHandler
 
-Design of a deletion of an Automation Composition
--------------------------------------------------
-- AUTOMATION_COMPOSITION_STATE_CHANGE message with UNINITIALISED state is sent to participants
-- Participant-intermediary validates the current state change
-- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of AutomationCompositionElements to participants
-- Each participant performs its designated job of undeployment by interacting with respective frameworks
+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 ParticipantHandler
 
-Design of "issues automation composition commands to automation compositions" - case UNINITIALISED to PASSIVE
--------------------------------------------------------------------------------------------------------------
-- AUTOMATION_COMPOSITION_STATE_CHANGE message with state changed from UNINITIALISED to PASSIVE is sent to participants
-- Participant-intermediary validates the current state change
-- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of state change to participants
-- Each participant performs its designated job of state change by interacting with respective frameworks
-
-Design of "issues automation composition commands to automation compositions" - case PASSIVE to UNINITIALISED
--------------------------------------------------------------------------------------------------------------
-- AUTOMATION_COMPOSITION_STATE_CHANGE message with state changed from PASSIVE to UNINITIALISED is sent to participants
-- Participant-intermediary validates the current state change
-- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of state change to participants
-- Each participant performs its designated job of state change by interacting with respective frameworks
-
-Design of "issues automation composition commands to automation compositions" - case PASSIVE to RUNNING
+Design of "issues automation composition commands to automation compositions" - case UNDEPLOY to DEPLOY
 -------------------------------------------------------------------------------------------------------
-- AUTOMATION_COMPOSITION_STATE_CHANGE message with state changed from PASSIVE to RUNNING is sent to participants
-- Participant-intermediary validates the current state change
-- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of state change to participants
-- Each participant performs its designated job of state change by interacting with respective frameworks
+- 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 RUNNING to PASSIVE
+Design of "issues automation composition commands to automation compositions" - case DEPLOY to UNDEPLOY
 -------------------------------------------------------------------------------------------------------
-- AUTOMATION_COMPOSITION_STATE_CHANGE message with state changed from RUNNING to PASSIVE is sent to participants
-- Participant-intermediary validates the current state change
-- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of state change to participants
-- Each participant performs its designated job of state change by interacting with respective frameworks
+- 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
+
+Design of "issues automation composition commands to automation compositions" - case LOCK to UNLOCK
+---------------------------------------------------------------------------------------------------
+- 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 UNLOCK to LOCK
+---------------------------------------------------------------------------------------------------
+- 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 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
+- 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 AUTOMATIONCOMPOSITION_UPDATE_ACK message
-----------------------------------------------------
-- A participant sends AUTOMATIONCOMPOSITION_UPDATE_ACK message in response to a AUTOMATIONCOMPOSITION_UPDATE message.
-- For each CL-elements moved to the ordered state as indicated by the AUTOMATIONCOMPOSITION_UPDATE
-- AutomationCompositionUpdateAckListener in CL-runtime collects the messages from DMaap
-- It checks the status of all automation composition elements and checks if the automation composition is primed
-- It updates the clamp-acm in DB accordingly
-
-Design of a AUTOMATIONCOMPOSITION_STATECHANGE_ACK is similar to the design for AUTOMATIONCOMPOSITION_UPDATE_ACK
+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

diff --git a/docs/clamp/acm/design-impl/participants/policy-framework-participant.rst b/docs/clamp/acm/design-impl/participants/policy-framework-participant.rst
index 9ce120c..3ebdae5 100644 (file)
--- a/docs/clamp/acm/design-impl/participants/policy-framework-participant.rst
+++ b/docs/clamp/acm/design-impl/participants/policy-framework-participant.rst
@@ -12,9 +12,9 @@ Automation Composition Elements in the Policy Framework Participant are configur
 
 The Policy Framework participant receives messages through participant-intermediary common code, and handles them by invoking REST APIs towards policy-framework.
 
-For example, When a AutomationCompositionUpdate message is received by policy participant, it contains full ToscaServiceTemplate describing all components participating in an automation composition. When the automation composition element state changed from UNINITIALIZED to PASSIVE, the Policy-participant triggers the creation of policy-types and policies in Policy-Framework.
+For example, When a PARTICIPANT_UPDATE message is received by policy participant prompted by a PRIME, it contains the Automation Composition Element Definitions from the Tosca Service Template that was commissioned. An Automation Composition Instance can then be created from the commissioned definitions. When the automation composition instance element state changed from UNDEPLOYED to DEPLOYED, the Policy-participant receives a AUTOMATION_COMPOSITION_DEPLOY message, which triggers the creation of policy-types and policies in Policy-Framework.
 
-When the state changes from PASSIVE to UNINITIALIZED, Policy-Participant deletes the policies, policy-types by invoking REST APIs towards the policy-framework.
+When the state changes from DEPLOYED to UNDEPLOYED, Policy-Participant deletes the policies, policy-types by invoking REST APIs towards the policy-framework.
 
 Run Policy Framework Participant command line using Maven
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -31,7 +31,9 @@ Distributing Policies
 
 The Policy Framework participant uses the Policy PAP API to deploy and undeploy policies.
 
-When a Policy Framework Automation Composition Element changes from state UNINITIALISED to state PASSIVE, the policy is deployed. When it changes from state PASSIVE to state UNINITIALISED, the policy is undeployed.
+When a Policy Framework Automation Composition Element changes from state UNDEPLOYED to state DEPLOYED, the policy is deployed. When it changes from state DEPLOYED to state UNDEPLOYED, the policy is undeployed.
+
+For more complete detail of the state machines please go to the state machines page :ref:`acm-states-label`.
 
 The PDP group to which the policy should be deployed is specified in the Automation Composition Element metadata, see the Policy Automation Composition Element type definition. If the PDP group specified for policy deployment does not exist, an error is reported.
 
@@ -76,4 +78,4 @@ The Policy Participant uses the following steps for Policy References:
      successfully stored, execution proceeds, otherwise an error is reported.
 
   #. If the Policy has not been specified, the Participant checks that the Policy is already in the Policy framework. If
-     the Policy already exists, execution proceeds, otherwise an error is reported.
\ No newline at end of file
+     the Policy already exists, execution proceeds, otherwise an error is reported.