Update docs for prepare review migration-precheck in ACM participant

Update docs for prepare, review, migration-precheck and using stage
in user guide and ACM participant.

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

9 files changed, 506 insertions, 140 deletions

diff --git a/docs/clamp/acm/acm-participant-guide.rst b/docs/clamp/acm/acm-participant-guide.rst
index e1f6c2de..d46c5611 100644
--- a/docs/clamp/acm/acm-participant-guide.rst
+++ b/docs/clamp/acm/acm-participant-guide.rst
@@ -91,7 +91,7 @@ AutomationCompositionElementListener:
   Every participant should implement a handler class that implements the AutomationCompositionElementListener interface
   from the Participant Intermediary. The intermediary listener class listens for the incoming events from the ACM-runtime
   and invoke the handler class implementations for various operations. This class implements the methods for deploying,
-  undeploying, locking, unlocking , deleting, updating, migrating, priming, depriming requests that are coming from the ACM-runtime.
+  undeploying, locking, unlocking , deleting, updating, preparing, reviewing, migrating, migrationPrechecking, priming, depriming requests that are coming from the ACM-runtime.
   The methods are as follows.
 
 .. code-block:: java
@@ -104,7 +104,10 @@ AutomationCompositionElementListener:
   6. void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement, InstanceElementDto instanceElementUpdated) throws PfModelException;
   7. void prime(CompositionDto composition) throws PfModelException;
   8. void deprime(CompositionDto composition) throws PfModelException;
-  9. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+  9. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate, int stage) throws PfModelException;
+  10. void migratePrecheck(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+  11. void review(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+  12. void prepare(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
 
 These method from the interface are implemented independently as per the user requirement. These methods after handling the
 appropriate requests should also invoke the intermediary's publisher apis to notify the ACM-runtime with the acknowledgement events.
@@ -117,92 +120,196 @@ ParticipantParameters:
 
   ParticipantIntermediaryParameters getIntermediaryParameters()
 
-Abstract class AcElementListenerV1
-----------------------------------
-This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener implemented in 7.1.0 version.
-So developers can decide to align to new functionality later. Any new functionality in the future will be wrapped by this class.
-
-The Abstract class AcElementListenerV1 supports the follow methods.
-
-.. code-block:: java
 
-  1. void undeploy(UUID instanceId, UUID elementId) throws PfModelException;
-  2. void deploy(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException;
-  3. void lock(UUID instanceId, UUID elementId) throws PfModelException;
-  4. void unlock(UUID instanceId, UUID elementId) throws PfModelException;
-  5. void delete(UUID instanceId, UUID elementId) throws PfModelException;
-  6. void update(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException;
-  7. void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList) throws PfModelException;
-  8. void deprime(UUID compositionId) throws PfModelException;
-  9. void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException;
+Abstract class AcElementListenerV3
+----------------------------------
+This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener from new releases.
+Any new functionality in the future will be wrapped by this class.
 
 **Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
-Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime and deprime.
+Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare.
 
-Un example of AutomationCompositionElementHandler implemented in 7.1.0 version and how to use AcElementListenerV1 abstract class:
 
-.. code-block:: java
-
-  @Component
-  @RequiredArgsConstructor
-  public class AutomationCompositionElementHandler implements AutomationCompositionElementListener {
+Methods: deploy, undeploy, lock, unlock, delete, review and prepare
+  compositionElement:
+    ======================  =======================================
+     **field**                       **description**
+    ======================  =======================================
+     compositionId           composition definition Id
+     elementDefinitionId     composition definition element Id
+     inProperties            composition definition in-properties
+     outProperties           composition definition out-properties
+    ======================  =======================================
+  instanceElement:
+    ==============================  ===========================
+     **field**                       **description**
+    ==============================  ===========================
+     instanceId                      instance id
+     elementId                       instance element id
+     toscaServiceTemplateFragment    policies and policy types
+     inProperties                    instance in-properties
+      outProperties                  instance out-properties
+    ==============================  ===========================
 
-    private final ParticipantIntermediaryApi intermediaryApi;
-    private final otherService otherService;
-    ..............................
-  }
+Method: update
+  compositionElement:
+    ======================  =======================================
+     **field**                       **description**
+    ======================  =======================================
+     compositionId           composition definition Id
+     elementDefinitionId     composition definition element Id
+     inProperties            composition definition in-properties
+     outProperties           composition definition out-properties
+    ======================  =======================================
+  instanceElement:
+    ==============================  ================================================
+     **field**                       **description**
+    ==============================  ================================================
+     instanceId                      instance id
+     elementId                       instance element id
+     toscaServiceTemplateFragment
+     inProperties                    instance in-properties **(before the update)**
+      outProperties                  instance out-properties
+    ==============================  ================================================
+  instanceElementUpdated:
+    ==============================  ======================================
+     **field**                       **description**
+    ==============================  ======================================
+     instanceId                      instance id
+     elementId                       instance element id
+     toscaServiceTemplateFragment
+     inProperties                    instance in-properties **(updated)**
+     outProperties                   instance out-properties
+    ==============================  ======================================
 
-  @Component
-  public class AutomationCompositionElementHandler extends AcElementListenerV1 {
+Methods: prime, deprime
+  composition:
+    ======================  ===================================================================
+     **field**                       **description**
+    ======================  ===================================================================
+     compositionId           composition definition Id
+     inProperties            composition definition in-properties for each definition element
+     outProperties           composition definition out-properties for each definition element
+    ======================  ===================================================================
 
-    private final OtherService otherService;
+Method: migratePrecheck
+  compositionElement:
+    ======================  =====================================================
+     **field**                       **description**
+    ======================  =====================================================
+     compositionId           composition definition Id
+     elementDefinitionId     composition definition element Id
+     inProperties            composition definition in-properties
+     outProperties           composition definition out-properties
+     state                   element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+    ======================  =====================================================
+  compositionElementTarget:
+    ======================  =====================================================
+     **field**                       **description**
+    ======================  =====================================================
+     compositionId           composition definition target Id
+     elementDefinitionId     composition definition target element Id
+     inProperties            composition definition target in-properties
+     outProperties           composition definition target out-properties
+     state                   element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+    ======================  =====================================================
+  instanceElement:
+    ==============================  ===================================================
+     **field**                       **description**
+    ==============================  ===================================================
+     instanceId                      instance id
+     elementId                       instance element id
+     toscaServiceTemplateFragment
+     inProperties                    instance in-properties **(before the migration)**
+     outProperties                   instance out-properties
+     state                           element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+    ==============================  ===================================================
+  instanceElementMigrate:
+    ==============================  ====================================================
+     **field**                       **description**
+    ==============================  ====================================================
+     instanceId                      instance id
+     elementId                       instance element id
+     toscaServiceTemplateFragment
+     inProperties                    instance in-properties **(updated)**
+     outProperties                   instance out-properties
+     state                           element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+    ==============================  ====================================================
 
-    public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi, OtherService otherService) {
-        super(intermediaryApi);
-        this.otherService = otherService;
-    }
-    ..............................
-  }
+Method: migrate
+  compositionElement:
+    ======================  =====================================================
+     **field**                       **description**
+    ======================  =====================================================
+     compositionId           composition definition Id
+     elementDefinitionId     composition definition element Id
+     inProperties            composition definition in-properties
+     outProperties           composition definition out-properties
+     state                   element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+    ======================  =====================================================
+  compositionElementTarget:
+    ======================  =====================================================
+     **field**                       **description**
+    ======================  =====================================================
+     compositionId           composition definition target Id
+     elementDefinitionId     composition definition target element Id
+     inProperties            composition definition target in-properties
+     outProperties           composition definition target out-properties
+     state                   element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+    ======================  =====================================================
+  instanceElement:
+    ==============================  ===================================================
+     **field**                       **description**
+    ==============================  ===================================================
+     instanceId                      instance id
+     elementId                       instance element id
+     toscaServiceTemplateFragment
+     inProperties                    instance in-properties **(before the migration)**
+     outProperties                   instance out-properties
+     state                           element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+    ==============================  ===================================================
+  instanceElementMigrate:
+    ==============================  ====================================================
+     **field**                       **description**
+    ==============================  ====================================================
+     instanceId                      instance id
+     elementId                       instance element id
+     toscaServiceTemplateFragment
+     inProperties                    instance in-properties **(updated)**
+     outProperties                   instance out-properties
+     state                           element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+    ==============================  ====================================================
+  stage:
+    the stage of the migration that the participant has to execute
 
 
+Abstract class AcElementListenerV2
+----------------------------------
+This abstract class is introduced to help to maintain temporarily the java backward compatibility with AutomationCompositionElementListener implemented in 8.0.0 version.
+So developers can decide to align to new functionality later. Any new functionality in the future will be wrapped by this class.
 
-A second example:
+The Abstract class AcElementListenerV2 supports the follow methods.
 
 .. code-block:: java
 
-  @Component
-  public class AutomationCompositionElementHandler implements AutomationCompositionElementListener {
-
-    @Autowired
-    private ParticipantIntermediaryApi intermediaryApi;
-
-    @Autowired
-    private otherService otherService;
-    ..............................
-  }
-
-  @Component
-  public class AutomationCompositionElementHandler extends AcElementListenerV1 {
-
-    @Autowired
-    private otherService otherService;
-
-    public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi) {
-        super(intermediaryApi);
-    }
-    ..............................
-  }
-
-Abstract class AcElementListenerV2
-----------------------------------
-This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener from new releases.
-Any new functionality in the future will be wrapped by this class.
+  1. void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+  2. void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+  3. void lock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+  4. void unlock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+  5. void delete(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+  6. void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement, InstanceElementDto instanceElementUpdated) throws PfModelException;
+  7. void prime(CompositionDto composition) throws PfModelException;
+  8. void deprime(CompositionDto composition) throws PfModelException;
+  9. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+  10. void migratePrecheck(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+  11. void review(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+  12. void prepare(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
 
 **Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
-Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime and deprime.
+Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare.
 
 
-Methods: deploy, undeploy, lock, unlock and delete
+Methods: deploy, undeploy, lock, unlock, delete, review and prepare
   compositionElement:
     ======================  =======================================
      **field**                       **description**
@@ -264,7 +371,7 @@ Methods: prime, deprime
      outProperties           composition definition out-properties for each definition element
     ======================  ===================================================================
 
-Method: migrate
+Method: migrate and migratePrecheck
   compositionElement:
     ======================  =======================================
      **field**                       **description**
@@ -304,6 +411,84 @@ Method: migrate
      outProperties                   instance out-properties
     ==============================  ======================================
 
+
+Abstract class AcElementListenerV1
+----------------------------------
+This abstract class is introduced to help to maintain temporarily the java backward compatibility with AutomationCompositionElementListener implemented in 7.1.0 version.
+So developers can decide to align to new functionality later. Any new functionality in the future will be wrapped by this class.
+
+The Abstract class AcElementListenerV1 supports the follow methods.
+
+.. code-block:: java
+
+  1. void undeploy(UUID instanceId, UUID elementId) throws PfModelException;
+  2. void deploy(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException;
+  3. void lock(UUID instanceId, UUID elementId) throws PfModelException;
+  4. void unlock(UUID instanceId, UUID elementId) throws PfModelException;
+  5. void delete(UUID instanceId, UUID elementId) throws PfModelException;
+  6. void update(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException;
+  7. void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList) throws PfModelException;
+  8. void deprime(UUID compositionId) throws PfModelException;
+  9. void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException;
+
+**Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
+Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare.
+
+Un example of AutomationCompositionElementHandler implemented in 7.1.0 version and how to use AcElementListenerV1 abstract class:
+
+.. code-block:: java
+
+  @Component
+  @RequiredArgsConstructor
+  public class AutomationCompositionElementHandler implements AutomationCompositionElementListener {
+
+    private final ParticipantIntermediaryApi intermediaryApi;
+    private final otherService otherService;
+    ..............................
+  }
+
+  @Component
+  public class AutomationCompositionElementHandler extends AcElementListenerV1 {
+
+    private final OtherService otherService;
+
+    public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi, OtherService otherService) {
+        super(intermediaryApi);
+        this.otherService = otherService;
+    }
+    ..............................
+  }
+
+
+
+A second example:
+
+.. code-block:: java
+
+  @Component
+  public class AutomationCompositionElementHandler implements AutomationCompositionElementListener {
+
+    @Autowired
+    private ParticipantIntermediaryApi intermediaryApi;
+
+    @Autowired
+    private otherService otherService;
+    ..............................
+  }
+
+  @Component
+  public class AutomationCompositionElementHandler extends AcElementListenerV1 {
+
+    @Autowired
+    private otherService otherService;
+
+    public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi) {
+        super(intermediaryApi);
+    }
+    ..............................
+  }
+
+
 APIs to invoke
 --------------
 ParticipantIntermediaryApi:
@@ -423,7 +608,7 @@ In/Out instance Properties
   * during DEPLOIYNG (Out Properties will be take from last changes matching by elementId)
   * during UNDEPLOING
   * during LOCKING/UNLOCKING
-  * during UPDATING/MIGRATING
+  * during UPDATING/MIGRATING/PREPARE/REVIEW/MIGRATION_PRECHECKING
 
 Participants will receive the in/out instance Properties related to the element by InstanceElementDto class.
 
@@ -628,7 +813,7 @@ The following example shows the Handler implementation and how could be the impl
 
     @Override
     public void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement,
-                       InstanceElementDto instanceElementUpdated) throws PfModelException {
+            InstanceElementDto instanceElementUpdated) throws PfModelException {
 
         // TODO update process
 
@@ -645,15 +830,25 @@ The following example shows the Handler implementation and how could be the impl
 
     @Override
     public void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget,
-                        InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate)
-        throws PfModelException
+            InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate, int stage)
+            throws PfModelException
 
-        // TODO migrate process
+        switch (instanceElementMigrate.state()) {
+            case NEW -> // TODO new element scenario
+            case REMOVED -> // TODO element remove scenario
+            default ->  // TODO migration process
+        }
 
         if (isMigrateSuccess()) {
-            intermediaryApi.updateAutomationCompositionElementState(
-                instanceElement.instanceId(), instanceElement.elementId(),
-                DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated");
+            if (isStageCompleted()) {
+                intermediaryApi.updateAutomationCompositionElementState(
+                    instanceElement.instanceId(), instanceElement.elementId(),
+                    DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated");
+            } else {
+                intermediaryApi.updateAutomationCompositionElementStage(
+                    instanceElement.instanceId(), instanceElement.elementId(),
+                    StateChangeResult.NO_ERROR, nextStage, "stage " + stage + " Migrated");
+            }
         } else {
             intermediaryApi.updateAutomationCompositionElementState(
                 instanceElement.instanceId(), instanceElement.elementId(),
@@ -662,6 +857,36 @@ The following example shows the Handler implementation and how could be the impl
     }
 
     @Override
+    public void migratePrecheck(UUID instanceId, UUID elementId) throws PfModelException {
+
+        // TODO migration Precheck process
+
+        intermediaryApi.updateAutomationCompositionElementState(
+            instanceElement.instanceId(), instanceElement.elementId(),
+            DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migration precheck completed");
+    }
+
+    @Override
+    public void prepare(UUID instanceId, UUID elementId) throws PfModelException {
+
+        // TODO prepare process
+
+        intermediaryApi.updateAutomationCompositionElementState(
+            instanceElement.instanceId(), instanceElement.elementId(),
+            DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Prepare completed");
+    }
+
+    @Override
+    public void review(UUID instanceId, UUID elementId) throws PfModelException {
+
+        // TODO review process
+
+        intermediaryApi.updateAutomationCompositionElementState(
+            instanceElement.instanceId(), instanceElement.elementId(),
+            DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Review completed");
+    }
+
+    @Override
     public void prime(CompositionDto composition) throws PfModelException {
 
         // TODO prime process
@@ -705,37 +930,43 @@ Allowed state from the participant perspective
 |            | PRIMED       |   FAILED            | Deprime is failed       |
 +------------+--------------+---------------------+-------------------------+
 
-+------------+-----------------+---------------+----------------+----------------------------------------+
-| **Action** | **deployState** | **lockState** | **stChResult** | **Description**                        |
-+------------+-----------------+---------------+----------------+----------------------------------------+
-|            |  DEPLOYED       |               |  NO_ERROR      |  Deploy is completed                   |
-+ Deploy     +-----------------+---------------+----------------+----------------------------------------+
-|            |  UNDEPLOYED     |               |  FAILED        |  Deploy is failed                      |
-+------------+-----------------+---------------+----------------+----------------------------------------+
-|            |  UNDEPLOYED     |               |  NO_ERROR      |  Undeploy is completed                 |
-| Undeploy   +-----------------+---------------+----------------+----------------------------------------+
-|            |  DEPLOYED       |               |  FAILED        |  Undeploy is failed                    |
-+------------+-----------------+---------------+----------------+----------------------------------------+
-|            |                 |  LOCKED       |  NO_ERROR      |  Lock is completed                     |
-+ Lock       +-----------------+---------------+----------------+----------------------------------------+
-|            |                 |  UNLOCKED     |  FAILED        |  Lock is failed                        |
-+------------+-----------------+---------------+----------------+----------------------------------------+
-|            |                 |  UNLOCKED     |  NO_ERROR      |  Unlock is completed                   |
-+ Unlock     +-----------------+---------------+----------------+----------------------------------------+
-|            |                 |  LOCKED       |  FAILED        |  Unlock is failed                      |
-+------------+-----------------+---------------+----------------+----------------------------------------+
-|            |  DEPLOYED       |               |  NO_ERROR      |  Update is completed                   |
-| Update     +-----------------+---------------+----------------+----------------------------------------+
-|            |  DEPLOYED       |               |  FAILED        |  Update is failed                      |
-+------------+-----------------+---------------+----------------+----------------------------------------+
-|            |  DEPLOYED       |               |  NO_ERROR      |  Migrate is completed                  |
-+ Migrate    +-----------------+---------------+----------------+----------------------------------------+
-|            |  DEPLOYED       |               |  FAILED        |  Migrate is failed                     |
-+------------+-----------------+---------------+----------------+----------------------------------------+
-|            |  DELETED        |               |  NO_ERROR      |  Delete is completed                   |
-| Delete     +-----------------+---------------+----------------+----------------------------------------+
-|            |  UNDEPLOYED     |               |  FAILED        |  Delete is failed                      |
-+------------+-----------------+---------------+----------------+----------------------------------------+
++------------------+-----------------+---------------+----------------+----------------------------------+
+| **Action**       | **deployState** | **lockState** | **stChResult** | **Description**                  |
++------------------+-----------------+---------------+----------------+----------------------------------+
+|                  |  DEPLOYED       |               |  NO_ERROR      |  Deploy is completed             |
++ Deploy           +-----------------+---------------+----------------+----------------------------------+
+|                  |  UNDEPLOYED     |               |  FAILED        |  Deploy is failed                |
++------------------+-----------------+---------------+----------------+----------------------------------+
+|                  |  UNDEPLOYED     |               |  NO_ERROR      |  Undeploy is completed           |
+| Undeploy         +-----------------+---------------+----------------+----------------------------------+
+|                  |  DEPLOYED       |               |  FAILED        |  Undeploy is failed              |
++------------------+-----------------+---------------+----------------+----------------------------------+
+|                  |                 |  LOCKED       |  NO_ERROR      |  Lock is completed               |
++ Lock             +-----------------+---------------+----------------+----------------------------------+
+|                  |                 |  UNLOCKED     |  FAILED        |  Lock is failed                  |
++------------------+-----------------+---------------+----------------+----------------------------------+
+|                  |                 |  UNLOCKED     |  NO_ERROR      |  Unlock is completed             |
++ Unlock           +-----------------+---------------+----------------+----------------------------------+
+|                  |                 |  LOCKED       |  FAILED        |  Unlock is failed                |
++------------------+-----------------+---------------+----------------+----------------------------------+
+|                  |  DEPLOYED       |               |  NO_ERROR      |  Update is completed             |
+| Update           +-----------------+---------------+----------------+----------------------------------+
+|                  |  DEPLOYED       |               |  FAILED        |  Update is failed                |
++------------------+-----------------+---------------+----------------+----------------------------------+
+|                  |  DEPLOYED       |               |  NO_ERROR      |  Migration is completed          |
++ Migrate          +-----------------+---------------+----------------+----------------------------------+
+|                  |  DEPLOYED       |               |  FAILED        |  Migration is failed             |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| Migrate Precheck |  DEPLOYED       |               |  NO_ERROR      |  Migration-precheck is completed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| Prepare          |  UNDEPLOYED     |               |  NO_ERROR      |  Prepare is completed            |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| Review           |  DEPLOYED       |               |  NO_ERROR      |  Review is completed             |
++------------------+-----------------+---------------+----------------+----------------------------------+
+|                  |  DELETED        |               |  NO_ERROR      |  Delete is completed             |
+| Delete           +-----------------+---------------+----------------+----------------------------------+
+|                  |  UNDEPLOYED     |               |  FAILED        |  Delete is failed                |
++------------------+-----------------+---------------+----------------+----------------------------------+
 
 
 AC Element states in failure scenarios
diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst
index 3c56f906..0f814b4b 100644
--- a/docs/clamp/acm/acm-user-guide.rst
+++ b/docs/clamp/acm/acm-user-guide.rst
@@ -232,6 +232,30 @@ Example payload to update the base url of the http request
    :language: json
 
 
+Prepare AC instance
+-------------------
+Once the AC instance is created, the user can prepare the instance which in turn activates the corresponding participants to execute the intended operations.
+In this case, the participants that support that action will be send the result by outProperties.
+
+.. code-block:: bash
+
+  Invoke a PUT request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+This returns a 202 response on a successful prepare order request. The elements will be in "PREPARING" sub state until the completion.
+The current status and result can be fetched through the following endpoint.
+
+.. code-block:: bash
+
+  Invoke a GET request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+Request payload
+
+.. literalinclude:: files/AC-prepare.json
+   :language: json
+
+
 Deploy AC instance
 ------------------
 Once the AC instance is created, the user can deploy the instance which in turn activates the corresponding participants to execute the intended operations.
@@ -265,6 +289,29 @@ Once all the AC elements are deployed, there should be a test microservice pod r
 configured to send events on the kafka by the http participant. This can be verified on the test microservice application logs.
 The AC instances can also be undeployed and deleted by the user.
 
+Review AC instance
+------------------
+Once the AC instance is deployed, the user can review the instance which in turn activates the corresponding participants to execute the intended operations.
+In this case, the participants that support that action will be send the result by outProperties.
+
+.. code-block:: bash
+
+  Invoke a PUT request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+This returns a 202 response on a successful review order request. The elements will be in "REVIEWING" sub state until the completion.
+The current status and result can be fetched through the following endpoint.
+
+.. code-block:: bash
+
+  Invoke a GET request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+Request payload
+
+.. literalinclude:: files/AC-review.json
+   :language: json
+
 Update AC instance properties after deployment (Optional)
 ---------------------------------------------------------
 After the AC instance is deployed, the user can still update the instance property values if needed. In this case, the runtime updates these new values
@@ -279,10 +326,28 @@ required operation.
 Note:
   Please refer the request payload section for updating the instance properties before deployment.
 
+Migrate-Precheck AC instance
+----------------------------
+After the AC instance is deployed, the user can trigger a migrate-precheck from it to other composition definition.
+The target composition have to be primed.
+The user can emulate an update of the instance property values if needed.
+
+.. code-block:: bash
+
+  Invoke a POST request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
+
+Request Payload
+
+Example payload to migrate-precheck
+
+.. literalinclude:: files/AC-migrate-precheck.json
+   :language: json
+
 Migrate AC instance
 -------------------
 After the AC instance is deployed, the user can migrate it to other composition definition.
-The target composition have to be primed and have to contain the same element definitions present in the source composition.
+The target composition have to be primed.
 The user can update the instance property values if needed.
 
 .. code-block:: bash
@@ -324,8 +389,8 @@ This deletes the AC instance from the database including all the element propert
 
 This returns a 202 response on successful delete order request.
 
-Deprime Ac defintions
----------------------
+Deprime Ac definitions
+----------------------
 Once the AC instance is deleted, it can be deprimed from the participants to be safely deleted from the database.
 
 .. code-block:: bash
@@ -339,8 +404,8 @@ Request payload
 .. literalinclude:: files/AC-depriming.json
    :language: json
 
-Delete AC defintion
--------------------
+Delete AC definition
+--------------------
 The AC definitions can be deleted if there are no instances are running and it is not primed to the participants.
 
 .. code-block:: bash
@@ -393,28 +458,8 @@ Parameters like delay and success/fail could be set any time using the following
 
 The Json below is an example of configuration:
 
-.. code-block:: json
-
-  {
-    "deploySuccess": true,
-    "undeploySuccess": true,
-    "lockSuccess": true,
-    "unlockSuccess": true,
-    "deleteSuccess": true,
-    "updateSuccess": true,
-    "migrateSuccess": true,
-    "primeSuccess": true,
-    "deprimeSuccess": true,
-    "deployTimerMs": 1000,
-    "undeployTimerMs": 1000,
-    "migrateTimerMs": 100,
-    "lockTimerMs": 100,
-    "unlockTimerMs": 100,
-    "updateTimerMs": 100,
-    "deleteTimerMs": 100,
-    "primeTimerMs": 100,
-    "deprimeTimerMs": 100
-  }
+.. literalinclude:: files/simparticipant-parameters.json
+   :language: json
 
 Update and send composition outProperites
 -----------------------------------------
@@ -504,6 +549,7 @@ Default value of 'element.handler' is the most recent version.
 ==================== ====================
 AcElementHandlerV1   AcElementListenerV1
 AcElementHandlerV2   AcElementListenerV2
+AcElementHandlerV3   AcElementListenerV3
 ==================== ====================
 
 Example:
@@ -511,4 +557,4 @@ Example:
 .. code-block:: yaml
 
   element:
-    handler: AcElementHandlerV1
+    handler: AcElementHandlerV3
diff --git a/docs/clamp/acm/allowed-operations.rst b/docs/clamp/acm/allowed-operations.rst
index 62de7ffc..12fca00e 100755
--- a/docs/clamp/acm/allowed-operations.rst
+++ b/docs/clamp/acm/allowed-operations.rst
@@ -129,3 +129,16 @@ Change status of Automation Composition Instance
 +            +-----------------+---------------+----------------+---------------------------------------------------------------------------------------------+

 |            | DEPLOYED        | LOCKING       |  TIMEOUT       | Start Unlocking transition and send unlock to participants after LOCKING got timeout        |

 +------------+-----------------+---------------+----------------+---------------------------------------------------------------------------------------------+

+

+Sub status of Automation Composition Instance

+---------------------------------------------

+

++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+

+| **Action**          | **deployState** | **lockState** | **Description**                                                                                     |

++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+

+|  Prepare            | UNDEPLOYED      |               | Start Preparing transition and send prepare to participants                                         |

++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+

+|  Review             | DEPLOYED        | LOCKED        | Start Reviewing transition and send review to participants                                          |

++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+

+|  Migration-Precheck | DEPLOYED        | LOCKED        | Start Migration-Prechecking transition and send Migration-Precheck to participants                  |

++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+

diff --git a/docs/clamp/acm/defining-acms.rst b/docs/clamp/acm/defining-acms.rst
index a9f2fbef..f2fb82e2 100644
--- a/docs/clamp/acm/defining-acms.rst
+++ b/docs/clamp/acm/defining-acms.rst
@@ -100,7 +100,7 @@ The Kubernetes Participant runs Kubernetes Automation Composition Elements. Each
 Element manages a Kubernetes microservice using Helm. The user defines the Helm chart for the
 Kubernetes microservice as well as other properties that the microservice requires in order to
 execute. The Yaml file that holds the
-`Kubernetes Automation Composition Element Type defintion is available in Github
+`Kubernetes Automation Composition Element Type definition is available in Github
 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/KubernetesAutomationCompositionElementType.yaml>`_
 and is the canonical definition of the Kubernetes Automation Composition Element type. For a description
 of the Kubernetes Automation Composition Element and Kubernetes Participant,please see
diff --git a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
index 493022d1..909ad263 100644
--- a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
+++ b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
@@ -24,10 +24,11 @@ Inbound messages to participants
 - 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
+- AUTOMATION_COMPOSITION_PREPARE: a message received from clamp-acm runtime server for a clamp-acm prepare/review 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
+- AUTOMATION_COMPOSITION_MIGRATION: a message received from clamp-acm runtime server for migrating/migration-precheck 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
@@ -62,12 +63,20 @@ Prime of an Automation Composition Definition Type
 - 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
+- Each participant performs its designated job of prime
 
 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
+- Each participant performs its designated job of deprime
+
+Design of "issues automation composition commands to automation compositions" - case PREPARE
+--------------------------------------------------------------------------------------------
+- AUTOMATION_COMPOSITION_PREPARE message with instantiation details and PREPARE order state is sent to participants
+- Participant-intermediary will receive AUTOMATION_COMPOSITION_PREPARE message and sends the details of AutomationCompositionElements to participants
+- Each participant performs its designated job of prepare
 
 Design of "issues automation composition commands to automation compositions" - case UNDEPLOYED to DEPLOYED
 -----------------------------------------------------------------------------------------------------------
@@ -76,6 +85,12 @@ Design of "issues automation composition commands to automation compositions" -
 - 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 REVIEW
+-------------------------------------------------------------------------------------------
+- AUTOMATION_COMPOSITION_PREPARE message with instantiation details and REVIEW order state is sent to participants
+- Participant-intermediary will receive AUTOMATION_COMPOSITION_PREPARE message and sends the details of AutomationCompositionElements to participants
+- Each participant performs its designated job of review
+
 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
@@ -89,24 +104,35 @@ Update of an Automation Composition Instance
 - 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
+- Each participant performs its designated job of update by interacting with respective frameworks
+
+Migrate-precheck of an Automation Composition Instance
+------------------------------------------------------
+- it triggers the execution to send a broadcast AUTOMATION_COMPOSITION_MIGRATION message with precheck set to true
+- 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 use a copy of the instance from CacheProvider to merge with data from the message
+- Each participant performs its designated job of migrate-precheck
 
 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
+- it triggers the execution to send a broadcast AUTOMATION_COMPOSITION_MIGRATION message with precheck set to false
 - 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
+- Each participant performs its designated job of migrate by interacting with respective frameworks
 
 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
+- Each participant performs its designated job of unlock
 
 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
+- Each participant performs its designated job of lock
 
 Design of Delete - case UNDEPLOYED to DELETED
 ---------------------------------------------
@@ -115,6 +141,7 @@ Design of Delete - case UNDEPLOYED to DELETED
 - 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
+- Each participant performs its designated job of delete
 
 Design of a PARTICIPANT_STATUS_REQ message
 ------------------------------------------
diff --git a/docs/clamp/acm/files/AC-migrate-precheck.json b/docs/clamp/acm/files/AC-migrate-precheck.json
new file mode 100644
index 00000000..66ab17df
--- /dev/null
+++ b/docs/clamp/acm/files/AC-migrate-precheck.json
@@ -0,0 +1,17 @@
+{
+  "name": "DemoInstance0",
+  "version": "1.0.1",
+  "compositionId": "COMPOSITIONIDPLACEHOLDER",
+  "instanceId": "INSTANCEIDPLACEHOLDER",
+  "compositionTargetId": "COMPOSITIONIDTARGET",
+  "description": "Demo automation composition instance 0",
+  "precheck": true,
+  "elements": {
+    "709c62b3-8918-41b9-a747-d21eb79c6c21": {
+      "id": "709c62b3-8918-41b9-a747-d21eb79c6c21",
+      "properties": {
+        "baseUrl": "http://acm-starter-ac-element-impl_updated:8084"
+      }
+    }
+  }
+}
diff --git a/docs/clamp/acm/files/AC-prepare.json b/docs/clamp/acm/files/AC-prepare.json
new file mode 100644
index 00000000..bc3a3c0a
--- /dev/null
+++ b/docs/clamp/acm/files/AC-prepare.json
@@ -0,0 +1,3 @@
+{
+  "subOrder": "PREPARE"
+}
diff --git a/docs/clamp/acm/files/AC-review.json b/docs/clamp/acm/files/AC-review.json
new file mode 100644
index 00000000..e4d74348
--- /dev/null
+++ b/docs/clamp/acm/files/AC-review.json
@@ -0,0 +1,3 @@
+{
+  "subOrder": "REVIEW"
+}
diff --git a/docs/clamp/acm/files/simparticipant-parameters.json b/docs/clamp/acm/files/simparticipant-parameters.json
new file mode 100644
index 00000000..14fbe01a
--- /dev/null
+++ b/docs/clamp/acm/files/simparticipant-parameters.json
@@ -0,0 +1,26 @@
+{
+  "deploySuccess": true,
+  "undeploySuccess": true,
+  "lockSuccess": true,
+  "unlockSuccess": true,
+  "deleteSuccess": true,
+  "updateSuccess": true,
+  "migrateSuccess": true,
+  "migratePrecheck": true,
+  "prepare": true,
+  "review": true,
+  "primeSuccess": true,
+  "deprimeSuccess": true,
+  "deployTimerMs": 100,
+  "undeployTimerMs": 100,
+  "lockTimerMs": 100,
+  "unlockTimerMs": 100,
+  "updateTimerMs": 100,
+  "migrateTimerMs": 100,
+  "migratePrecheckTimerMs": 100,
+  "prepareTimerMs": 100,
+  "reviewTimerMs": 100,
+  "deleteTimerMs": 100,
+  "primeTimerMs": 100,
+  "deprimeTimerMs": 100
+}