Updated participant protocol docs

Added new puml for state and update diagrams
Updated diagrams
Added table as csv - easier for updating later

Issue-ID: POLICY-4602
Change-Id: Iaca291057688b0a856192036816685d3b9676b4f
Signed-off-by: saul.gill <saul.gill@est.tech>

19 files changed, 252 insertions, 384 deletions

diff --git a/docs/clamp/acm/api-protocol/acm-participant-protocol.rst b/docs/clamp/acm/api-protocol/acm-participant-protocol.rst
index 449e2096..2dae2b00 100644
--- a/docs/clamp/acm/api-protocol/acm-participant-protocol.rst
+++ b/docs/clamp/acm/api-protocol/acm-participant-protocol.rst
@@ -5,7 +5,7 @@
 The ACM Automation Composition Participant Protocol
 ###################################################
 
-The CLAMP Automation Composition protocol is an asynchronous protocol that is used by the CLAMP
+The ACM Automation Composition protocol is an asynchronous protocol that is used by the ACM
 runtime to coordinate lifecycle management of Automation Composition instances. The protocol
 supports the functions described in the sections below.
 
@@ -18,32 +18,42 @@ The protocol supports the dialogues described below.
 Participant Registration and De-Registration
 --------------------------------------------
 
-Registration when a participant comes up and update of participant with Automation Composition type
-information and common parameter values for its Automation Composition types.
+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.
 
-.. image:: ../images/acm-participants-protocol/participant-registering.png
+.. image:: ../images/system-dialogues/RegisterParticipant.png
 
 
-De-registration is executed as a participant goes down.
+Participant Deregistration is performed by a Participant when it shuts down. It deregisters its ID and type with the ACM runtime. The participant should already have cleared down all its' ACM Element instances and set their states to “Not In Service”.
 
-.. image:: ../images/acm-participants-protocol/participant-deregistration.png
+.. image:: ../images/system-dialogues/DeregisterParticipant.png
 
 
 Automation Composition Priming and De-Priming
 ---------------------------------------------
 
-When an Automation Composition is primed, the portion of the Automation Composition Type Definition
-and Common Property values for the participants of each participant type mentioned in the
-Automation Composition Definition are sent to the 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. The ParticipantPrime message type is sent to trigger priming and depriming in participants in participants
 
-.. image:: ../images/acm-participants-protocol/acm-priming.png
+.. image:: ../images/system-dialogues/PrimeAcTypeOnPpnts.png
 
-When an Automation Composition is de-primed, the portion of the Automation Composition Type
-Definition and Common Property values for the participants of each participant type mentioned in
-the Automation Composition Definition are deleted on participants.
+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.
 
-.. image:: ../images/acm-participants-protocol/acm-depriming.png
+.. image:: ../images/system-dialogues/PrimeAcTypeMultiplePpnts.png
 
+The ACM Runtime updates the priming information in the database.
+
+.. image:: ../images/system-dialogues/PrimeInfoUpdatedInDb.png
+
+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
+
+A participant should respond for each Automation Composition Element Type, thus causing the full Automation Composition Type to become deprimed.
+
+.. image:: ../images/system-dialogues/DeprimeElements.png
+
+The ACM Runtime updates the priming information in the database.
+
+.. image:: ../images/system-dialogues/UpdateDeprimeInDb.png
 
 Automation Composition Update
 -----------------------------
@@ -72,26 +82,28 @@ The *startPhase* in the `Definition of TOSCA fundamental Automation Composition
 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/AutomationCompositionTOSCAServiceTemplateTypes.yaml>`_
 is particularly important in Automation Composition state changes because sometimes the user wishes
 to control the order in which the state changes in Automation Composition Elements in an Automation
-Composition. In-state changes from *UNITITIALISED → PASSIVE* and from *PASSIVE → RUNNING*,
+Composition. In-state changes from *UNDEPLOYED → DEPLOYED*,
 Automation Composition elements are started in increasing order of their startPhase. In-state
-changes from *RUNNING → PASSIVE* and from *PASSIVE → UNITITIALISED*, Automation Composition
+changes from *DEPLOYED → UNDEPLOYED*, Automation Composition
 elements are started in decreasing order of their *startPhase*.
 
-The CLAMP runtime controls the state change process described in the diagram below. The CLAMP
-runtime sends an Automation Composition state change message on DMaaP to all participants in a
+The ACM runtime controls the state change process described in the diagram below. The ACM
+runtime sends an Automation Composition state change message on the messaging system (e.g. Kafka) to all participants in a
 particular start phase so, in each state change multiple Automation Composition State Change
 messages are sent, one for each start phase in the Automation Composition. If more than one
 Automation Composition Element has the same start phase, those Automation Composition Elements
-receive the same Automation Composition State Change message from DMaaP and start in parallel.
+receive the same Automation Composition State Change message from Kafka and start in parallel.
 
-The Participant reads each State Change Message it sees on DMaaP. If the start phase on the
+The Participant reads each State Change Message it sees on Kafka. If the start phase on the
 Automation Composition State Change message matches the Start Phase of the Automation Composition
 Element, the participant processes the state change message. Otherwise, the participant ignores the
 message.
 
 .. image:: ../images/acm-participants-protocol/acm-state-change.png
 
-The handling of an ACMStateChange message in each participant is as shown below.
+The flow of the DEPLOY/UNDEPLOY state change messages are shown below. But the same flow is true for LOCK/UNLOCK
+
+.. note:: More details of the state machine are available on :ref:`ACM States <acm-states-label>`
 
 .. image:: ../images/acm-participants-protocol/acm-state-change-msg.png
 
@@ -115,369 +127,9 @@ see the `CLAMP code at Github
 <https://github.com/onap/policy-clamp/tree/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/dmaap/participant>`_
 . All messages are carried on DMaaP.
 
-
-.. list-table::
-   :widths: 15 10 10 15 15 35
-   :header-rows: 1
-
-   * - Message
-     - Source
-     - Target
-     - Purpose
-     - Important Fields
-     - Field Descriptions
-   * - ParticipantRegister
-     - Participant
-     - CLAMP Runtime
-     - Participant registers with the CLAMP runtime
-     - ParticipantId
-     - The ID of this participant
-   * -
-     -
-     -
-     -
-     - ParticipantType
-     - The type of the participant; maps to the capabilities of the participant in Automation
-       Composition Type Definitions
-   * - ParticipantRegisterAck
-     - CLAMP Runtime
-     - Participant
-     - Acknowledgment of Participant Registration
-     - ParticipantId
-     - The ID of this participant
-   * -
-     -
-     -
-     -
-     - ParticipantType
-     - The type of the participant; maps to the capabilities of the participant in Automation
-       Composition Type Definitions
-   * -
-     -
-     -
-     -
-     - Result
-     - Success/Fail
-   * -
-     -
-     -
-     -
-     - Message
-     - A message indicating the reason for failure
-   * - ParticipantUpdate
-     - CLAMP Runtime
-     - Participant
-     - CLAMP Runtime sends Automation Composition Element Definitions and Common Parameter Values
-       to Participants
-     - ParticipantDefinitionUpdateMap
-     - Map with Participant ID as its key, each value on the map is an ACMElementDefintionMap
-   * -
-     -
-     -
-     -
-     - ACMElementDefintionMap
-     - List of ACMElementDefinition values for a particular participant, keyed by its Automation
-       Composition Element Definition ID
-   * -
-     -
-     -
-     -
-     - ACMElementDefinition
-     - An ACMElementToscaServiceTemplate containing the definition of the Automation Composition
-       Element and a CommonPropertiesMap with the values of the common property values for
-       Automation Composition Elements of this type
-   * -
-     -
-     -
-     -
-     - ACMElementToscaServiceTemplate
-     - The definition of the Automation Composition Element in TOSCA
-   * -
-     -
-     -
-     -
-     - CommonPropertiesMap
-     - A <String, String> map indexed by the property name. Each map entry is the serialized value
-       of the property, which can be deserialized into an instance of the type of the property.
-   * - ParticipantUpdateAck
-     - Participant
-     - CLAMP Runtime
-     - Acknowledgment of Participant Update
-     - ParticipantId
-     - The ID of this participant
-   * -
-     -
-     -
-     -
-     - ParticipantType
-     - The type of the participant; maps to the capabilities of the participant in Automation
-       Composition Type Definitions
-   * -
-     -
-     -
-     -
-     - Result
-     - Success/Fail
-   * -
-     -
-     -
-     -
-     - Message
-     - A message indicating the reason for failure
-   * - ParticipantDeregister
-     - Participant
-     - CLAMP Runtime
-     - Participant deregisters with the CLAMP runtime
-     - ParticipantId
-     - The ID of this participant
-   * -
-     -
-     -
-     -
-     - ParticipantType
-     - The type of the participant; maps to the capabilities of the participant in Automation
-       Composition Type Definitions
-   * - ParticipantDeregisterAck
-     - CLAMP Runtime
-     - Participant
-     - Acknowledgment of Participant Deegistration
-     - ParticipantId
-     - The ID of this participant
-   * -
-     -
-     -
-     -
-     - ParticipantType
-     - The type of the participant; maps to the capabilities of the participant in Automation
-       Composition Type Definitions
-   * -
-     -
-     -
-     -
-     - Result
-     - Success/Fail
-   * -
-     -
-     -
-     -
-     - Message
-     - A message indicating the reason for failure
-   * - ACMUpdate
-     - CLAMP Runtime
-     - Participant
-     - CLAMP Runtime sends Automation Composition Element instances and Instance Specific Parameter
-       Values for an Automation Composition Instance to Participants
-     - ACMId
-     - The name and version of the Automation Composition
-   * -
-     -
-     -
-     -
-     - ParticipantUpdateMap
-     - Map with Participant ID as its key, each value on the map is an ACMElementList
-   * -
-     -
-     -
-     -
-     - ACMElementList
-     - List of ACMElement values for the Automation Composition
-   * -
-     -
-     -
-     -
-     - ACMElement
-     - An ACMElement, which contains among other things a PropertiesMap with the values of the
-       property values for this Automation Composition Element instance and a
-       ToscaServiceTemplateFragment with extra concept definitions and instances that a participant
-       may need.
-   * -
-     -
-     -
-     -
-     - PropertiesMap
-     - A <String, String> map indexed by the property name. Each map entry is the serialized value
-       of the property, which can be deserialized into an instance of the type of the property.
-   * -
-     -
-     -
-     -
-     - ToscaServiceTemplateFragment
-     - A well-formed TOSCA service template containing extra concept definitions and instances that
-       a participant may need. For example, the Policy Participant may need policy type definitions
-       or policy instances to be provided if they are not already stored in the Policy Framework.
-   * - ACMUpdateAck
-     - Participant
-     - CLAMP Runtime
-     - Acknowledgment of Automation Composition Update
-     - ParticipantId
-     - The ID of this participant
-   * -
-     -
-     -
-     -
-     - ParticipantType
-     - The type of the participant; maps to the capabilities of the participant in Automation
-       Composition Type Definitions
-   * -
-     -
-     -
-     -
-     - ACMId
-     - The name and version of the Automation Composition
-   * -
-     -
-     -
-     -
-     - ACMResult
-     - Holds a Result and Message for the overall operation on the participant and a map of Result
-       and Message fields for each Automation Composition Element of the Automation Composition on
-       this participant
-   * -
-     -
-     -
-     -
-     - Result
-     - Success/Fail
-   * -
-     -
-     -
-     -
-     - Message
-     - A message indicating the reason for failure
-   * - ACMStateChange
-     - CLAMP Runtime
-     - Participant
-     - CLAMP Runtime asks Participants to change the state of an Automation Composition
-     - ACMId
-     - The name and version of the Automation Composition
-   * -
-     -
-     -
-     -
-     - currentState
-     - The current state of the Automation Composition
-   * -
-     -
-     -
-     -
-     - orderedState
-     - The state that the Automation Composition should transition to
-   * -
-     -
-     -
-     -
-     - startPhase
-     - The start phase to which this ACMStateChange message applies
-   * - ACMStateChangeAck
-     - Participant
-     - CLAMP Runtime
-     - Acknowledgment of Automation Composition State Change
-     - ParticipantId
-     - The ID of this participant
-   * -
-     -
-     -
-     -
-     - ParticipantType
-     - The type of the participant; maps to the capabilities of the participant in Automation
-       Composition Type Definitions
-   * -
-     -
-     -
-     -
-     - ACMId
-     - The name and version of the Automation Composition
-   * -
-     -
-     -
-     -
-     - startPhase
-     - The start phase to which this ACMStateChangeAck message applies
-   * -
-     -
-     -
-     -
-     - ACMResult
-     - Holds a Result and Message for the overall operation on the participant and a map of Result
-       and Message fields for each Automation Composition Element of the Automation Composition on
-       this participant
-   * -
-     -
-     -
-     -
-     - Result
-     - Success/Fail
-   * -
-     -
-     -
-     -
-     - Message
-     - A message indicating the reason for failure
-   * - ParticipantStatusReq
-     - CLAMP Runtime
-     - Participant
-     - Request that the specified participants return a ParticipantStatus message immediately
-     - ParticipantId
-     - The ID of this participant, if not specified, all participants respond.
-   * - ParticipantStatus
-     - Participant
-     - CLAMP Runtime
-     - Periodic or on-demand report for heartbeat, Participant Status, Automation Composition
-       Status, and Automation Composition Statistics
-     - ParticipantId
-     - The ID of this participant
-   * -
-     -
-     -
-     -
-     - ParticipantType
-     - The type of the participant; maps to the capabilities of the participant in Automation
-       Composition Type Definitions
-   * -
-     -
-     -
-     -
-     - ParticipantDefinitionUpdateMap (returned in repsonse to ParticipantStatusReq only)
-     - See ParticipantUpdate message above for definition of this field
-   * -
-     -
-     -
-     -
-     - ParticipantStatus
-     - The current status of the participant for monitoring
-   * -
-     -
-     -
-     -
-     - ParticipantStatistics
-     - Statistics on the participant such as uptime, or messages processed. Can include participant
-       specific data in a string blob that is opaque to CLAMP
-   * -
-     -
-     -
-     -
-     - ACMInfoMap
-     - A map of ACMInfo types indexed by ACMId, one entry for each Automation Composition
-       running on the participant
-   * -
-     -
-     -
-     -
-     - ACMInfo
-     - The ACMStatus and ACMStatistics for a given Automation Composition
-   * -
-     -
-     -
-     -
-     - ACMStatus
-     - The current status of the Automation Composition for monitoring
-   * -
-     -
-     -
-     -
-     - ACMStatistics
-     - Statistics on the Automation Composition such as uptime, or messages processed. Can include
-       participant specific data in a string blob that is opaque to CLAMP
+.. csv-table:: ACM Messages
+  :file: ../files/ACM-Message-Table.csv
+  :header-rows: 1
 
 
 End of Document
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml b/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml
new file mode 100644
index 00000000..589e2cc3
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml
@@ -0,0 +1,11 @@
+@startuml
+Commissioning_REST -> CLAMP_Runtime: De-Prime Automation Composition Type Definition
+alt Automation Composition Instances exist for Automation Composition Type
+	Commissioning_REST <- CLAMP_Runtime: Cannot decommission Automation Composition Type Definition
+else No Automation Composition Instances exist for Automation Composition Type
+	Participant <- CLAMP_Runtime: Participant Update\n[Remove Automation Composition Element Definitions\nfrom Participants in Automation Composition]
+	activate Participant
+	Participant -> Participant: Delete Automation Composition Element\nType Definitions and\nCommon Property Values
+	Participant -> CLAMP_Runtime: Participant Update Ack [from each Participant mentioned in Participant Update message]
+	deactivate Participant
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml b/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml
new file mode 100644
index 00000000..8b6a18ea
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml
@@ -0,0 +1,5 @@
+@startuml
+Participant -> CLAMP_Runtime: Participant Deregistration
+Participant <- CLAMP_Runtime: Participant Deregistration Ack
+Participant -> Participant: Shutdown Participant
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml b/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml
new file mode 100644
index 00000000..8429c227
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml
@@ -0,0 +1,52 @@
+@startuml
+
+(*) --> "Process State Change Message"
+
+if "All Automation Composition Elements with my Participant ID processed?" then
+  --> [yes] "Send State Change Ack Message"
+  --> (*)
+else
+  --> [no] "Process next Automation Composition Element with my ID"
+  if "State Change Message Start Phase equals Automation Composition Element start phase" then
+    [true] if "Current State is DEPLOYED?" then
+     [true] if "Change to UNDEPLOYED?" then
+      --> [true] "Change Automation Composition Element to state UNDEPLOYED"
+      --> "Wait for DEPLOYED->UNDEPLOYED State Change to complete"
+      if "State Change?" then
+        --> [success] "Record Success for State Change Ack message"
+        --> "Process State Change Message"
+      else
+        --> [fail] "Record Error for State Change Ack message"
+        --> "Process State Change Message"
+      endif
+      else
+        --> [false] "Record Error for State Change Ack message"
+        --> "Process State Change Message"
+      endif
+    else
+      [false] if "Current State is UNDEPLOYED?" then
+        [true] if "Change to DEPLOYED?" then
+          --> [true] "Change Automation Composition Element to state DEPLOYED"
+          --> "Wait for UNDEPLOYED->DEPLOYED State Change to complete"
+          if "State Change?" then
+            --> [success] "Record Success for State Change Ack message"
+            --> "Process State Change Message"
+          else
+            --> [fail] "Record Error for State Change Ack message"
+            --> "Process State Change Message"
+          endif
+        else
+          --> [false] "Record Error for State Change Ack message"
+          --> "Process State Change Message"
+        endif
+      else
+        --> [false] "Record Error for State Change Ack message"
+        --> "Process State Change Message"
+      endif
+    endif
+  else
+    --> [false] "Skip Automation Composition Element"
+    --> "Process State Change Message"
+endif
+
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml b/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml
new file mode 100644
index 00000000..24f25d7c
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml
@@ -0,0 +1,3 @@
+@startuml
+Participant -> CLAMP_Runtime: Participant Status [periodically from each Participant in all Automation Compositions]
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml b/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml
new file mode 100644
index 00000000..064f913e
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml
@@ -0,0 +1,13 @@
+@startuml
+Commissioning_REST -> CLAMP_Runtime: Prime Automation Composition Type Defintions and\nset values of Common Properties
+activate CLAMP_Runtime
+loop over Participant Types in Automation Composition Type Definition
+	CLAMP_Runtime -> CLAMP_Runtime: Collect Automation Composition Element Type Definitions and\nCommon Property Values for Participant Type
+end
+Participant <- CLAMP_Runtime: Participant Update\n[Automation Composition Element Type Definitions and\nCommon Property Values for Participant Types]
+deactivate CLAMP_Runtime
+activate Participant
+Participant -> Participant: Store Automation Composition Element Type Definitions and\nCommon Property Values
+Participant -> CLAMP_Runtime: Participant Update Ack\n[from each Participant mentioned in Participant Update message]
+deactivate Participant
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml b/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml
new file mode 100644
index 00000000..af42d571
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml
@@ -0,0 +1,17 @@
+@startuml
+activate Participant
+Participant -> Participant: Start Participant
+deactivate Participant
+Participant -> CLAMP_Runtime: Participant Registration
+Participant <- CLAMP_Runtime: Participant Registration Ack
+activate CLAMP_Runtime
+loop over Automation Composition Type Definitions
+	CLAMP_Runtime -> CLAMP_Runtime: Collect Automation Composition Element Type Definitions and\nCommon Property Values for\nParticipant Type of this Participant
+end
+deactivate CLAMP_Runtime
+Participant <- CLAMP_Runtime: Participant Update\n[Automation Composition Element Type Definitions and\nCommon Property Values for\nParticipant Type of Participant]
+activate Participant
+Participant -> Participant: Store Automation Composition Element Type Definitions and\nCommon Property Values
+Participant -> CLAMP_Runtime: Participant Update Ack
+deactivate Participant
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml b/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml
new file mode 100644
index 00000000..af8779da
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml
@@ -0,0 +1,35 @@
+@startuml
+
+activate CLAMP_Runtime
+CLAMP_Runtime -> CLAMP_Runtime: Build an ordered list of the Start Phases in the Automation Composition Instance
+deactivate CLAMP_Runtime
+
+alt "State Change UNDEPLOYED_to_DEPLOYED or LOCKED_to_UNLOCKED"
+  loop over Start Phases list in increasing order
+    CLAMP_Runtime -> Participant: Automation Composition State Change\n[to all Participants in Automation Composition with this Start Phase]
+    CLAMP_Runtime -> CLAMP_Runtime: Asynchronously wait for answers from Participants
+    CLAMP_Runtime <- Participant: Automation Composition State Change Ack [from each Participant in this Start Phase of Automation Composition]
+    alt "State Change Ack reports success"
+      CLAMP_Runtime -> CLAMP_Runtime: Log success
+    else "State Change Ack reports an error"
+      CLAMP_Runtime -> CLAMP_Runtime: Log error
+      CLAMP_Runtime -> CLAMP_Runtime: Reset state of Automation Composition CLAMP_Runtime -> CLAMP_Runtime: Abort State Change operation
+    end
+  end
+else "State Change DEPLOYED_to_UNDEPLOYED or UNLOCKED_to_LOCKED"
+ loop over Start Phases list in decreasing order
+    CLAMP_Runtime -> Participant: Automation Composition State Change\n[to all Participants in Automation Composition with this Start Phase]
+    CLAMP_Runtime -> CLAMP_Runtime: Asynchronously wait for answers from Participants
+    CLAMP_Runtime <- Participant: Automation Composition State Change Ack [from each Participant in this Start Phase of Automation Composition]
+    alt "State Change Ack reports success"
+      CLAMP_Runtime -> CLAMP_Runtime: Log success
+    else "State Change Ack reports an error"
+      CLAMP_Runtime -> CLAMP_Runtime: Log error
+      CLAMP_Runtime -> CLAMP_Runtime: Reset state of Automation Composition CLAMP_Runtime -> CLAMP_Runtime: Abort State Change operation
+    end
+  end
+end
+
+CLAMP_Runtime -> CLAMP_Runtime: Set overall state of Automation Composition
+
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml b/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml
new file mode 100644
index 00000000..ccf7acc9
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml
@@ -0,0 +1,48 @@
+@startuml
+
+(*) --> "Process Update Message"
+
+if "All Automation Composition Elements with my Participant ID processed?" then
+  --> [yes] "Send Update Ack Message"
+  --> (*)
+else
+  --> [no] "Process next Automation Composition Element with my ID"
+  if "New Automation Composition Element?" then
+	--> [yes] "Create Automation Composition Element"
+	--> "Set Automation Composition Element to state UNDEPLOYED/LOCKED"
+	--> "Order Deployment/Unlock of Automation Composition Element"
+	--> "Pass Parameters to Automation Composition Element"
+	--> "Wait for Deployment/Unlock to complete"
+	if "Automation Composition Element Deployed/Unlocked?" then
+      --> [success] "Record Success for Update Ack message"
+      --> "Process Update Message"
+    else
+      --> [fail] "Delete Automation Composition Element"
+      --> "Record Error for Update Ack message"
+      --> "Process Update Message"
+    endif
+  else
+  	--> [no] "Check Automation Composition Element State"
+  endif
+  if "DEPLOYED/UNLOCKED and Automation Composition Version change != patch?" then
+	--> [true] "Record Error for Update Ack message"
+    --> "Process Update Message"
+  else
+  	[false] if "NOT DEPLOYED/UNLOCKED and Automation Composition Version change == major?" then
+      --> [true] "Record Error for Update Ack message"
+      --> "Process Update Message"
+  else
+	--> [false] "Pass Changed Parameters to Automation Composition Element"
+	--> "Wait for reconfiguration to complete"
+    if "Automation Composition Element Reconfiguration?" then
+      --> [success] "Record Success for Update Ack message"
+      --> "Process Update Message"
+    else
+      --> [fail] "Roll back reconfiguration"
+      --> "Record Error for Update Ack message"
+      --> "Process Update Message"
+    endif
+  endif
+endif
+
+@enduml
diff --git a/docs/clamp/acm/files/ACM-Message-Table.csv b/docs/clamp/acm/files/ACM-Message-Table.csv
new file mode 100644
index 00000000..725ac1ec
--- /dev/null
+++ b/docs/clamp/acm/files/ACM-Message-Table.csv
@@ -0,0 +1,32 @@
+Message,Source,Target,Purpose,Important Fields,Field Descriptions
+ParticipantRegister,Participant,ACM Runtime,Participant registers with the ACM runtime,participantId,The ID of this participant – in UUID format
+,,,,participantSupportedElementTypes,A list of element types that this participant supports
+ParticipantRegisterAck,ACM Runtime,Participant,Acknowledgment of Participant Registration,participantId,The ID of this participant – in UUID format
+,,,,Result,Success/Fail
+,,,,Message,A message indicating the reason for failure
+ParticipantDeregister,Participant,ACM Runtime,Participant deregisters with the ACM runtime,participantId,The ID of this participant – in UUID format
+ParticipantDeregisterAck,ACM Runtime,Participant,Acknowledgment of Participant Deegistration,participantId,The ID of this participant – in UUID format
+,,,,Result,Success/Fail
+,,,,Message,A message indicating the reason for failure
+ParticipantPrime,ACM Runtime,Participant,Trigger priming/depriming in the participant,participantId,The ID of this participant – in UUID format
+,,,,participantDefinitionUpdates,Contains AC element definition values for a particular participant
+,,,,Result,Success/Fail
+,,,,Message,A message indicating the reason for failure
+ParticipantPrimeAck,Participant,ACM Runtime,Message to confirm participant has been primed/deprimed,participantId,The ID of this participant – in UUID format
+,,,,Result,Success/Fail
+,,,,Message,A message indicating the reason for failure
+ParticipantStatusReq,ACM Runtime,Participant,Message sent to reques a status update from the participant,participantId,The ID of the participant to request update from – in UUID format
+,,,,messageType,Enum indicating the type of message PARTICIPANT_STATUS_REQ
+ParticipantStatus,Participant,ACM Runtime,Status update message,state,Enum indicating the current state of the participant
+,,,,participantDefinitionUpdates,"A list of ParticipantDefinition updates, returned in response to ParticipantStatusReq only"
+,,,,automationCompositionInfoList,List of AutomationCompositionInfo types with AutomationCompositionId and its state
+,,,,participantSupportedElementTypes,Ac element types that this participant is capable for deployinh/supporting
+AutomationCompositionDeploy,ACM Runtime,Participant,Message to request change state of composition to DEPLOY,participantUpdatesList,A list of ParticipantUpdates instances which carries details of an updated participant.
+,,,,startPhase,Integer indicating the start up order of the elements
+,,,,participantId,UUID indicating the participant the message is intended for
+AutomationCompositionDeployAck,Participant,ACM Runtime,Message to acknowledge that deploy or state change message has been received by participant,automationCompositionResultMap,"A map with AutomationCompositionElementID as its key, and a pair of result and message as value per AutomationCompositionElement"
+,,,,automationCompositionId,The id of the automation composition related to this message
+AutomationCompositionStateChange,ACM Runtime,Participant,Message to request change state of composition to states other than DEPLOY,deployOrderedState,Enum indicating the deployment state being requested
+,,,,lockOrderedState,Enum indicating the lock state being requested
+,,,,startPhase,Integer indicating the start up order of the elements
+,,,,participantId,UUID indicating the participant the message is intended for
diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-depriming.png b/docs/clamp/acm/images/acm-participants-protocol/acm-depriming.png
index 7bcc9b15..7ea51967 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/acm-depriming.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/acm-depriming.png
diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-monitoring.png b/docs/clamp/acm/images/acm-participants-protocol/acm-monitoring.png
index dcc996e4..ec9ba5e1 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/acm-monitoring.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/acm-monitoring.png
diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-priming.png b/docs/clamp/acm/images/acm-participants-protocol/acm-priming.png
index 918a292e..4aec6a4a 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/acm-priming.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/acm-priming.png
diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-state-change-msg.png b/docs/clamp/acm/images/acm-participants-protocol/acm-state-change-msg.png
index d1393bab..1211b8ce 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/acm-state-change-msg.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/acm-state-change-msg.png
diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-state-change.png b/docs/clamp/acm/images/acm-participants-protocol/acm-state-change.png
index fd55a069..f2966763 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/acm-state-change.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/acm-state-change.png
diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-update-msg.png b/docs/clamp/acm/images/acm-participants-protocol/acm-update-msg.png
index 3886e440..f9ea2331 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/acm-update-msg.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/acm-update-msg.png
diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-update.png b/docs/clamp/acm/images/acm-participants-protocol/acm-update.png
index 2a7aac1f..3dc124d4 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/acm-update.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/acm-update.png
diff --git a/docs/clamp/acm/images/acm-participants-protocol/participant-deregistration.png b/docs/clamp/acm/images/acm-participants-protocol/participant-deregistration.png
index bb2ec9a3..9c86d626 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/participant-deregistration.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/participant-deregistration.png
diff --git a/docs/clamp/acm/images/acm-participants-protocol/participant-registering.png b/docs/clamp/acm/images/acm-participants-protocol/participant-registering.png
index 2f7b5d8e..7bc68751 100644
--- a/docs/clamp/acm/images/acm-participants-protocol/participant-registering.png
+++ b/docs/clamp/acm/images/acm-participants-protocol/participant-registering.png