Update docs for prepare review migration-precheck in ACM runtime

Update docs for prepare, review, migration-precheck and  using stage
in ACM states and ACM runtime.

Issue-ID: POLICY-5109
Change-Id: I059a57d406f9588ef11a694882e7324dad643805
Signed-off-by: FrancescoFioraEst <francesco.fiora@est.tech>

24 files changed, 393 insertions, 16 deletions

diff --git a/docs/clamp/acm/acm-states.rst b/docs/clamp/acm/acm-states.rst
index a6cfc2e1..7a3222a5 100644
--- a/docs/clamp/acm/acm-states.rst
+++ b/docs/clamp/acm/acm-states.rst
@@ -80,6 +80,12 @@ Delete
 
 .. image:: images/acm-states/AcInstanceStatesDelete.png
 
+Automation Composition Instance Sub State
+=========================================
+The sub states that an Automation Composition Instance can have are shown in the diagram below.
+
+.. image:: images/acm-states/AcInstanceSubStates.png
+
 How State are saved in DB
 =========================
 Any state will be saved in DB as number:
@@ -111,8 +117,8 @@ Automation Composition Type State
 |  DEPRIMING     |         3  |
 +----------------+------------+
 
-Automation Composition Instance State
-=====================================
+Automation Composition Instance DeployState
+===========================================
 
 +---------------+------------+
 |  DeployState  |  Database  |
@@ -134,5 +140,36 @@ Automation Composition Instance State
 |  MIGRATING    |         7  |
 +---------------+------------+
 
+Automation Composition Instance Lock State
+==========================================
+
++-------------+------------+
+|  LockState  |  Database  |
++=============+============+
+|  LOCKED     |         0  |
++-------------+------------+
+|  LOCKING    |         1  |
++-------------+------------+
+|  UNLOCKED   |         2  |
++-------------+------------+
+|  UNLOCKING  |         3  |
++-------------+------------+
+|  NONE       |         4  |
++-------------+------------+
+
+Automation Composition Instance Sub State
+=========================================
+
++-------------------------+------------+
+|  SubState               |  Database  |
++=========================+============+
+|  NONE                   |         0  |
++-------------------------+------------+
+|  MIGRATION_PRECHECKING  |         1  |
++-------------------------+------------+
+|  PREPARING              |         2  |
++-------------------------+------------+
+|  REVIEWING              |         3  |
++-------------------------+------------+
 
 End of Document
diff --git a/docs/clamp/acm/api-protocol/system-level-dialogues.rst b/docs/clamp/acm/api-protocol/system-level-dialogues.rst
index f3612b49..ec03353c 100644
--- a/docs/clamp/acm/api-protocol/system-level-dialogues.rst
+++ b/docs/clamp/acm/api-protocol/system-level-dialogues.rst
@@ -133,7 +133,22 @@ The ACM Runtime receives and stores the responses, when all instances element ar
 
 .. image:: ../images/system-dialogues/DeleteResponseStored.png
 
-3.3 Deploy Automation Composition Instance
+3.3 Prepare Automation Composition Instance
+-------------------------------------------
+Prepare is a check system from participant before the deployment of an instance, the result will stored in outProperties and not other changes are allowed.
+The user requests the AC Instance to be prepared using a REST endpoint. The ACM Runtime orders the AC Instance to be prepared to Participants.
+
+.. image:: ../images/system-dialogues/PrepareAcInstance.png
+
+Each participant prepares its AC Element Instances from the AC Instance.
+
+.. image:: ../images/system-dialogues/PrepareAcInstanceElements.png
+
+The ACM Runtime receives and stores the responses, and send sync message to all replicas.
+
+.. image:: ../images/system-dialogues/PrepareResponseStored.png
+
+3.4 Deploy Automation Composition Instance
 ------------------------------------------
 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.
 
@@ -147,7 +162,22 @@ The ACM Runtime receives and stores the responses, and send sync message to all
 
 .. image:: ../images/system-dialogues/DeployResponseStored.png
 
-3.4 Update Automation Composition Instance
+3.5 Review Automation Composition Instance
+------------------------------------------
+Review is a check system from participant after the deployment of an instance, the result will stored in outProperties and not other changes are allowed.
+The user requests the AC Instance to be Reviewed using a REST endpoint. The ACM Runtime orders the AC Instance to be reviewed to Participants.
+
+.. image:: ../images/system-dialogues/ReviewAcInstance.png
+
+Each participant reviews its AC Element Instances from the AC Instance.
+
+.. image:: ../images/system-dialogues/ReviewAcInstanceElements.png
+
+The ACM Runtime receives and stores the responses, and send sync message to all replicas.
+
+.. image:: ../images/system-dialogues/ReviewResponseStored.png
+
+3.6 Update Automation Composition Instance
 ------------------------------------------
 The user requests the AC Instance to be updated using a REST endpoint. The ACM Runtime orders the AC Instance to be updated.
 
@@ -161,7 +191,22 @@ The ACM Runtime receives and stores the responses, and send sync message to all
 
 .. image:: ../images/system-dialogues/UpdateAcElementsResponse.png
 
-3.5 Migrate Automation Composition Instance
+3.7 Migration Precheck Automation Composition Instance
+------------------------------------------------------
+Migration Precheck is a check system from participant before the migration of an instance, the result will stored in outProperties and not other changes are allowed.
+The user requests a Migration Precheck for the AC Instance using a REST endpoint. The ACM Runtime orders the Migration Precheck for AC Instance to Participants.
+
+.. image:: ../images/system-dialogues/MigrationPrecheckAcInstance.png
+
+Each participant execute a Migration Precheck to its AC Element Instances from the AC Instance.
+
+.. image:: ../images/system-dialogues/MigrationPrecheckAcInstanceElements.png
+
+The ACM Runtime receives and stores the responses, and send sync message to all replicas.
+
+.. image:: ../images/system-dialogues/MigrationPrecheckResponseStored.png
+
+3.8 Migrate Automation Composition Instance
 -------------------------------------------
 The user requests the AC Instance to be migrated using a REST endpoint. The ACM Runtime orders the AC Instance to be migrated.
 
@@ -175,7 +220,7 @@ The ACM Runtime receives and stores the responses, and send sync message to all
 
 .. image:: ../images/system-dialogues/MigrateAcElementsResponse.png
 
-3.6 Undeploy Automation Composition Instance
+3.9 Undeploy Automation Composition Instance
 --------------------------------------------
 The user requests the AC Instance to be undeployed using a REST endpoint. The ACM Runtime orders the AC Instance to be undeployed.
 
@@ -189,13 +234,13 @@ The ACM Runtime receives and stores the responses, and send sync message to all
 
 .. image:: ../images/system-dialogues/UndeployResponseStored.png
 
-3.7 Read Automation Composition Instances
------------------------------------------
+3.10 Read Automation Composition Instances
+------------------------------------------
 
 .. image:: ../images/system-dialogues/ReadAcInstances.png
 
-3.8 Unlock Automation Composition Instance
-------------------------------------------
+3.11 Unlock Automation Composition Instance
+-------------------------------------------
 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.
 
 .. image:: ../images/system-dialogues/OrderInstanceUnlock.png
@@ -208,8 +253,8 @@ The ACM Runtime receives and stores the responses, and send sync message to all
 
 .. image:: ../images/system-dialogues/UnlockResponseStored.png
 
-3.9 Lock Automation Composition Instance
-----------------------------------------
+3.12 Lock Automation Composition Instance
+-----------------------------------------
 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.
 
 .. image:: ../images/system-dialogues/LockAcInstance.png
@@ -222,12 +267,12 @@ The ACM Runtime receives and stores the responses, and send sync message to all
 
 .. image:: ../images/system-dialogues/LockResponseStored.png
 
-3.10 Update Operational State, Use State and outProperties on Automation Composition Instance
+3.13 Update Operational State, Use State and outProperties on Automation Composition Instance
 ---------------------------------------------------------------------------------------------
 
 .. image:: ../images/system-dialogues/UpdateOperationalState.png
 
-3.11 Failure handling in ACM
+3.14 Failure handling in ACM
 ----------------------------
 After any ACM operation is completed, one of the following result messages will be updated in the ACM. These result values are
 updated along with the overall state of the ACM instance.
@@ -272,7 +317,7 @@ The following flow shown and example of deployment that get stuck, and the user
 .. image:: ../images/system-dialogues/TimeoutParticipant.png
 
 
-3.12 OFF_LINE handling in ACM
+3.15 OFF_LINE handling in ACM
 -----------------------------
 Runtime marks the participant state with the value 'OFF_LINE' when the participant replica fails to report the periodic heartbeat,
 the participant replica state is then marked as 'OFF_LINE' by the ACM-R after the configured waiting limit is reached.
diff --git a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
index ba73eb04..81b7376f 100644
--- a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
+++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
@@ -18,7 +18,7 @@ Terminology
 - ThreadPoolExecutor: ThreadPoolExecutor executes the given task, into SupervisionAspect class is configured to execute tasks in ordered manner, one by one
 - Spring Scheduling: into SupervisionAspect class, the @Scheduled annotation invokes "schedule()" method every "runtime.participantParameters.heartBeatMs" milliseconds with a fixed delay
 - MessageIntercept: "@MessageIntercept" annotation is used into SupervisionHandler class to intercept "handleParticipantMessage" method calls using spring aspect oriented programming
-- GUI: swagger-ui, Postman or policy-gui
+- GUI: swagger-ui or Postman
 - Message Broker: It supports the message Broker Kafka
 
 Design of Rest Api
@@ -80,6 +80,17 @@ Update of a Automation Composition Instance
 - the Rest-Api call returns the instanceId and the list of AC Element Instance
 - the runtime sends an update event to the participants which performs the update operation on the deployed instances.
 
+Migrate-Precheck of a Automation Composition Instance
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- GUI has already a new composition definition primed
+- GUI calls POST "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances" endpoint with a Automation Composition Instance as body. It have to contain the compositionId, the compositionTargetId and the instanceId
+- ACM-runtime receives the call by Rest-Api (InstantiationController)
+- It checks that AC Instance is in DEPLOYED deployState
+- It checks that compositionTargetId is related to a primed composition definition
+- It only set the subState of the Automation Composition to DB
+- the Rest-Api call returns the instanceId and the list of AC Element Instance
+- the runtime sends a migrate-precheck event to the participants which performs the check operation on the deployed instances.
+
 Migrate of a Automation Composition Instance
 ++++++++++++++++++++++++++++++++++++++++++++
 - GUI has already a new composition definition primed
@@ -94,6 +105,15 @@ Migrate of a Automation Composition Instance
 Issues AC instance to change status
 +++++++++++++++++++++++++++++++++++
 
+case **subOrder: PREPARE**
+
+- GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with PREPARE as subOrder
+- ACM-runtime receives the call by Rest-Api (InstantiationController)
+- It validates the status order issued (related AC Instance has UNDEPLOYED as deployState)
+- It updates the AC Instance to DB with PREPARING subState
+- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_PREPARE message with preDeploy set to true
+- the message is built by AcPreparePublisher using Instance data.
+
 case **deployOrder: DEPLOY**
 
 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with DEPLOY as deployOrder
@@ -103,6 +123,15 @@ case **deployOrder: DEPLOY**
 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_DEPLOY message
 - the message is built by AutomationCompositionDeployPublisher using Tosca Service Template data and Instance data. (with startPhase = first startPhase)
 
+case **subOrder: REVIEW**
+
+- GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with REVIEW as subOrder
+- ACM-runtime receives the call by Rest-Api (InstantiationController)
+- It validates the status order issued (related AC Instance has DEPLOYED as deployState)
+- It updates the AC Instance to DB with REVIEWING subState
+- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_PREPARE message with preDeploy set to false
+- the message is built by AcPreparePublisher using Instance data.
+
 case **lockOrder: UNLOCK**
 
 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with UNLOCK as lockOrder
@@ -210,6 +239,61 @@ Example of DEPLOY order with Http_PMSHMicroserviceAutomationCompositionElement w
 
 In that scenario the message AUTOMATION_COMPOSITION_DEPLOY has been sent two times.
 
+Migration using Stage
+*********************
+The stage is particularly important in Automation Composition migration because sometime the user wishes to control
+not only the order in which the state changes in Automation Composition Elements but also to execute again using the same Automation Composition Elements.
+
+How to define Stage
++++++++++++++++++++
+Stage is defined as shown below in the Definition of TOSCA fundamental Automation Composition Types yaml file.
+
+.. code-block:: YAML
+
+  stage:
+    type: list
+    required: false
+    description: A list indicating the stages in which this automation composition element will be started, the
+                 first stage is zero. Automation Composition Elements are started in their stage order.
+                 Automation Composition Elements with the same stage are started simultaneously.
+    metadata:
+      common: true
+
+Example where it could be used:
+
+.. code-block:: YAML
+
+  org.onap.domain.database.Http_PMSHMicroserviceAutomationCompositionElement:
+    # Consul http config for PMSH.
+    version: 1.2.3
+    type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
+    type_version: 1.0.1
+    description: Automation Composition element for the http requests of PMSH microservice
+    properties:
+      provider: ONAP
+      uninitializedToPassiveTimeout: 180
+      stage: [0,2]
+
+How Stage works
++++++++++++++++
+In state changes in MIGRATING Automation Composition elements starts in increasing order from stage 0.
+
+Example of MIGRATE order with Http_PMSHMicroserviceAutomationCompositionElement with stage [0,2] and PMSH_K8SMicroserviceAutomationCompositionElement with startPhase to [0,1]:
+
+- ACM-runtime sends a broadcast AUTOMATION_COMPOSITION_MIGRATION message to all participants with stage = 0
+- participant receives the AUTOMATION_COMPOSITION_MIGRATION message and runs to DEPLOYED state (only AC elements that contains stage 0: Http_PMSHMicroserviceAutomationCompositionElement and PMSH_K8SMicroserviceAutomationCompositionElement)
+- ACM-runtime receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
+- ACM-runtime calculates that all AC elements with stage = 0 are set to proper state and sends a broadcast AUTOMATION_COMPOSITION_MIGRATION message with stage = 1
+- participant receives the AUTOMATION_COMPOSITION_MIGRATION message and runs to DEPLOYED state (only AC elements that contains stage 1: PMSH_K8SMicroserviceAutomationCompositionElement)
+- ACM-runtime receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
+- ACM-runtime calculates that all AC elements with stage = 1 are set to proper state and sends a broadcast AUTOMATION_COMPOSITION_MIGRATION message with stage = 2
+- participant receives the AUTOMATION_COMPOSITION_MIGRATION message and runs to DEPLOYED state (only AC elements that contains stage 2: Http_PMSHMicroserviceAutomationCompositionElement)
+- ACM-runtime receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
+- ACM-runtime calculates that all AC elements are set to proper state and set AC to DEPLOYED
+
+In that scenario the message AUTOMATION_COMPOSITION_MIGRATION has been sent three times,
+Http_PMSHMicroserviceAutomationCompositionElement and PMSH_K8SMicroserviceAutomationCompositionElement will be executed two times.
+
 Configure custom namings for TOSCA node types
 *********************************************
 
diff --git a/docs/clamp/acm/files/ACM-Message-Table.csv b/docs/clamp/acm/files/ACM-Message-Table.csv
index da17374a..0ade0b81 100755
--- a/docs/clamp/acm/files/ACM-Message-Table.csv
+++ b/docs/clamp/acm/files/ACM-Message-Table.csv
@@ -38,6 +38,7 @@ AutomationCompositionDeploy,ACM Runtime,Participant,Message to request change st
 ,,,,participantId,UUID indicating the participant the message is intended for
 ,,,,messageType,Enum indicating the type of message AUTOMATION_COMPOSITION_DEPLOY
 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"
+,,,,stage,The next stage that participant is supposed to receiving
 ,,,,replicaId,The replica ID of this participant – in UUID format
 ,,,,compositionId,The id of the AC Definition related to this message
 ,,,,automationCompositionId,The id of the automation composition related to this message
@@ -66,8 +67,14 @@ ParticipantSync,ACM Runtime,Participant,Message to request sync,participantId,Th
 ,,,,restarting,Flag - if true it is a restarting scenario
 ,,,,messageType,Enum indicating the type of message PARTICIPANT_SYNC_MSG
 AutomationCompositionMigration,ACM Runtime,Participant,Message to request update,participantUpdatesList,A list of ParticipantUpdates instances which carries details of an updated participant.
+,,,,precheck,Flag - if true it is a Migration Precheck
 ,,,,compositionId,The id of the AC Definition related to this message
 ,,,,compositionTargetId,The id of the AC Definition target
 ,,,,automationCompositionId,The id of the automation composition related to this message
 ,,,,participantId,UUID indicating the participant the message is intended for
 ,,,,messageType,Enum indicating the type of message PROPERTIES_UPDATE
+AutomationCompositionPrepare,ACM Runtime,Participant,Message to request prepare/review,participantList,A list of ParticipantUpdates instances which carries details of an updated participant.
+,,,,preDeploy,Flag - if true the instance is Undeployed and the action is a Prepare - otherwise (false) the instance is Deployed and the action is a Review
+,,,,compositionId,The id of the AC Definition related to this message
+,,,,automationCompositionId,The id of the automation composition related to this message
+,,,,messageType,Enum indicating the type of message AUTOMATION_COMPOSITION_PREPARE
diff --git a/docs/clamp/acm/images/acm-states/AcInstanceSubStates.png b/docs/clamp/acm/images/acm-states/AcInstanceSubStates.png
new file mode 100644
index 00000000..f27ea679
--- /dev/null
+++ b/docs/clamp/acm/images/acm-states/AcInstanceSubStates.png
diff --git a/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstance.png b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstance.png
new file mode 100644
index 00000000..1d0514ca
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstance.png
diff --git a/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstanceElements.png b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstanceElements.png
new file mode 100644
index 00000000..3fbf7196
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstanceElements.png
diff --git a/docs/clamp/acm/images/system-dialogues/MigrationPrecheckResponseStored.png b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckResponseStored.png
new file mode 100644
index 00000000..7b66c5b2
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckResponseStored.png
diff --git a/docs/clamp/acm/images/system-dialogues/PrepareAcInstance.png b/docs/clamp/acm/images/system-dialogues/PrepareAcInstance.png
new file mode 100644
index 00000000..3220fa2a
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/PrepareAcInstance.png
diff --git a/docs/clamp/acm/images/system-dialogues/PrepareAcInstanceElements.png b/docs/clamp/acm/images/system-dialogues/PrepareAcInstanceElements.png
new file mode 100644
index 00000000..7802642e
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/PrepareAcInstanceElements.png
diff --git a/docs/clamp/acm/images/system-dialogues/PrepareResponseStored.png b/docs/clamp/acm/images/system-dialogues/PrepareResponseStored.png
new file mode 100644
index 00000000..2bf2997a
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/PrepareResponseStored.png
diff --git a/docs/clamp/acm/images/system-dialogues/ReviewAcInstance.png b/docs/clamp/acm/images/system-dialogues/ReviewAcInstance.png
new file mode 100644
index 00000000..35e12764
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/ReviewAcInstance.png
diff --git a/docs/clamp/acm/images/system-dialogues/ReviewAcInstanceElements.png b/docs/clamp/acm/images/system-dialogues/ReviewAcInstanceElements.png
new file mode 100644
index 00000000..50b49c8f
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/ReviewAcInstanceElements.png
diff --git a/docs/clamp/acm/images/system-dialogues/ReviewResponseStored.png b/docs/clamp/acm/images/system-dialogues/ReviewResponseStored.png
new file mode 100644
index 00000000..671b23fb
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/ReviewResponseStored.png
diff --git a/docs/clamp/acm/plantuml/states/AcInstanceSubStates.puml b/docs/clamp/acm/plantuml/states/AcInstanceSubStates.puml
new file mode 100644
index 00000000..918a03b3
--- /dev/null
+++ b/docs/clamp/acm/plantuml/states/AcInstanceSubStates.puml
@@ -0,0 +1,18 @@
+@startuml
+
+UNDEPLOYED --> DEPLOYING: Deploy
+DEPLOYING --> DEPLOYED: AC Instance Elements\nall DEPLOYED
+
+state UNDEPLOYED {
+ NONE:UNDEPLOYED --> PREPARING: Prepare
+ PREPARING --> NONE:UNDEPLOYED: Completed
+}
+
+state DEPLOYED {
+ NONE:DEPLOYED --> REVIEWING: Review
+ REVIEWING --> NONE:DEPLOYED: Completed
+ NONE:DEPLOYED --> MIGRATION_PRECHECKING: Migrate precheck
+ MIGRATION_PRECHECKING --> NONE:DEPLOYED: Completed
+}
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstance.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstance.puml
new file mode 100644
index 00000000..14252f22
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstance.puml
@@ -0,0 +1,18 @@
+@startuml
+participant REST
+participant "ACM Runtime"
+participant Participants
+database "ACM Database"
+
+REST -> "ACM Runtime": Migration Precheck Automation Composition Instance
+"ACM Runtime" -> "ACM Database": Read Automation Composition Instance Information
+
+alt Automation Composition Instance exists
+  "ACM Runtime" -> Participants: [ASYNC] Migration Precheck AC Element Instances for this AC Instance
+  "ACM Runtime" -> "ACM Database": Set AC Instance and its AC Element Instances to subState MIGRATION_PRECHECKING
+  "ACM Runtime" -> REST: Migration Precheck of Automation Composition Instance has been requested
+else
+  "ACM Runtime" -> REST: Automation Composition instance does not exist
+end
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstanceElements.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstanceElements.puml
new file mode 100644
index 00000000..39d71b69
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstanceElements.puml
@@ -0,0 +1,25 @@
+@startuml
+participant "ACM Runtime"
+participant Participant
+participant "Participant API"
+
+"ACM Runtime" -> Participant: [ASYNC] Migration Precheck AC Element Instances for this AC Instance
+
+loop over AC Element Instances in AC Instance
+ alt Does the primed Participant ID on this AC Element Instance\nmatch my Participant ID?
+   Participant -> "Participant API": Migration Precheck AC Element Instance
+   activate "Participant API"
+   Participant <- "Participant API": AC Element Instance Migration Precheck Response
+   deactivate "Participant API"
+   alt AC Element Migration Precheck completed
+    Participant -> Participant: Set AC Element Instance administrative subState to NONE
+    "ACM Runtime" <- Participant: [ASYNC] INFO: Migration Precheck AC Element has been completed
+   end
+ else
+  note left of Participant
+   Ignore this AC Element instance as its for another participant
+  end note
+ end
+end
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckResponseStored.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckResponseStored.puml
new file mode 100644
index 00000000..cc63e9dd
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckResponseStored.puml
@@ -0,0 +1,19 @@
+@startuml
+
+participant "ACM Runtime"
+database "ACM Database"
+participant "Participant Replica 1"
+participant "Participant Replica 2"
+
+"ACM Runtime" <- "Participant Replica 1": [ASYNC] Migration Precheck Automation Composition Element \nInstance Response
+"ACM Runtime" -> "ACM Database": Store Automation Composition Element Instance \nResponse Information
+
+alt Is Migration Precheck AC Element Instance Completed?
+ "ACM Runtime" -> "ACM Database": Set AC Element Instance SubState as NONE
+ alt Are all the other AC Element Instances in this AC Instance in state NONE?
+  "ACM Runtime" -> "ACM Database": Set AC Instance SubState as NONE
+  "ACM Runtime" -> "Participant Replica 2": [ASYNC] Send sync message
+ end
+end
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstance.puml b/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstance.puml
new file mode 100644
index 00000000..dd7cc7ee
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstance.puml
@@ -0,0 +1,18 @@
+@startuml
+participant REST
+participant "ACM Runtime"
+participant Participants
+database "ACM Database"
+
+REST -> "ACM Runtime": Prepare Automation Composition Instance
+"ACM Runtime" -> "ACM Database": Read Automation Composition Instance Information
+
+alt Automation Composition Instance exists
+  "ACM Runtime" -> Participants: [ASYNC] Prepare AC Element Instances for this AC Instance
+  "ACM Runtime" -> "ACM Database": Set AC Instance and its AC Element Instances to subState PREPARING
+  "ACM Runtime" -> REST: Prepare of Automation Composition Instance has been requested
+else
+  "ACM Runtime" -> REST: Automation Composition instance does not exist
+end
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstanceElements.puml b/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstanceElements.puml
new file mode 100644
index 00000000..5c5fbcee
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstanceElements.puml
@@ -0,0 +1,25 @@
+@startuml
+participant "ACM Runtime"
+participant Participant
+participant "Participant API"
+
+"ACM Runtime" -> Participant: [ASYNC] Prepare AC Element Instances for this AC Instance
+
+loop over AC Element Instances in AC Instance
+ alt Does the primed Participant ID on this AC Element Instance\nmatch my Participant ID?
+   Participant -> "Participant API": Prepare AC Element Instance
+   activate "Participant API"
+   Participant <- "Participant API": AC Element Instance Prepare Response
+   deactivate "Participant API"
+   alt AC Element Prepare completed
+    Participant -> Participant: Set AC Element Instance administrative subState to NONE
+    "ACM Runtime" <- Participant: [ASYNC] INFO: Prepare AC Element has been completed
+   end
+ else
+  note left of Participant
+   Ignore this AC Element instance as its for another participant
+  end note
+ end
+end
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/PrepareResponseStored.puml b/docs/clamp/acm/plantuml/system-dialogues/PrepareResponseStored.puml
new file mode 100644
index 00000000..51ff03b1
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/PrepareResponseStored.puml
@@ -0,0 +1,19 @@
+@startuml
+
+participant "ACM Runtime"
+database "ACM Database"
+participant "Participant Replica 1"
+participant "Participant Replica 2"
+
+"ACM Runtime" <- "Participant Replica 1": [ASYNC] Prepare Automation Composition Element \nInstance Response
+"ACM Runtime" -> "ACM Database": Store Automation Composition Element Instance \nResponse Information
+
+alt Is Prepare AC Element Instance Completed?
+ "ACM Runtime" -> "ACM Database": Set AC Element Instance SubState as NONE
+ alt Are all the other AC Element Instances in this AC Instance in state NONE?
+  "ACM Runtime" -> "ACM Database": Set AC Instance SubState as NONE
+  "ACM Runtime" -> "Participant Replica 2": [ASYNC] Send sync message
+ end
+end
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstance.puml b/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstance.puml
new file mode 100644
index 00000000..ce40a003
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstance.puml
@@ -0,0 +1,18 @@
+@startuml
+participant REST
+participant "ACM Runtime"
+participant Participants
+database "ACM Database"
+
+REST -> "ACM Runtime": Review Automation Composition Instance
+"ACM Runtime" -> "ACM Database": Read Automation Composition Instance Information
+
+alt Automation Composition Instance exists
+  "ACM Runtime" -> Participants: [ASYNC] Review AC Element Instances for this AC Instance
+  "ACM Runtime" -> "ACM Database": Set AC Instance and its AC Element Instances to subState REVIEWING
+  "ACM Runtime" -> REST: Review of Automation Composition Instance has been requested
+else
+  "ACM Runtime" -> REST: Automation Composition instance does not exist
+end
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstanceElements.puml b/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstanceElements.puml
new file mode 100644
index 00000000..45454e6a
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstanceElements.puml
@@ -0,0 +1,25 @@
+@startuml
+participant "ACM Runtime"
+participant Participant
+participant "Participant API"
+
+"ACM Runtime" -> Participant: [ASYNC] Review AC Element Instances for this AC Instance
+
+loop over AC Element Instances in AC Instance
+ alt Does the primed Participant ID on this AC Element Instance\nmatch my Participant ID?
+   Participant -> "Participant API": Review AC Element Instance
+   activate "Participant API"
+   Participant <- "Participant API": AC Element Instance Review Response
+   deactivate "Participant API"
+   alt AC Element Review completed
+    Participant -> Participant: Set AC Element Instance administrative subState to NONE
+    "ACM Runtime" <- Participant: [ASYNC] INFO: Review AC Element has been completed
+   end
+ else
+  note left of Participant
+   Ignore this AC Element instance as its for another participant
+  end note
+ end
+end
+
+@enduml
diff --git a/docs/clamp/acm/plantuml/system-dialogues/ReviewResponseStored.puml b/docs/clamp/acm/plantuml/system-dialogues/ReviewResponseStored.puml
new file mode 100644
index 00000000..13287e61
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/ReviewResponseStored.puml
@@ -0,0 +1,19 @@
+@startuml
+
+participant "ACM Runtime"
+database "ACM Database"
+participant "Participant Replica 1"
+participant "Participant Replica 2"
+
+"ACM Runtime" <- "Participant Replica 1": [ASYNC] Review Automation Composition Element \nInstance Response
+"ACM Runtime" -> "ACM Database": Store Automation Composition Element Instance \nResponse Information
+
+alt Is Review AC Element Instance Completed?
+ "ACM Runtime" -> "ACM Database": Set AC Element Instance SubState as NONE
+ alt Are all the other AC Element Instances in this AC Instance in state NONE?
+  "ACM Runtime" -> "ACM Database": Set AC Instance SubState as NONE
+  "ACM Runtime" -> "Participant Replica 2": [ASYNC] Send sync message
+ end
+end
+
+@enduml