Update Documentation for migration

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

13 files changed, 189 insertions, 18 deletions

diff --git a/docs/clamp/acm/acm-participant-guide.rst b/docs/clamp/acm/acm-participant-guide.rst
index b2ee244a..6102fc72 100755
--- a/docs/clamp/acm/acm-participant-guide.rst
+++ b/docs/clamp/acm/acm-participant-guide.rst
@@ -92,6 +92,7 @@ AutomationCompositionElementListener:
   8. void deprime(UUID compositionId) throws PfModelException;
   9. void handleRestartComposition(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList, AcTypeState state) throws PfModelException;
   10. void handleRestartInstance(UUID automationCompositionId, AcElementDeploy element, Map<String, Object> properties, DeployState deployState, LockState lockState) throws PfModelException;
+  11. void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) 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.
@@ -133,13 +134,39 @@ This following method is invoked to update the AC element state after each opera
 
 In/Out composition Properties
 -----------------------------
-  The 'Common Properties' could be created or updated by ACM-runtime. Participants will receive that Properties during priming events.
+The 'Common Properties' could be created or updated by ACM-runtime.
+Participants will receive that Properties during priming events.
 
-  The 'Out Properties' could be created or updated by participants. ACM-runtime will receive that Properties during ParticipantStatus event.
-  The participant can trigger this event using the method sendAcDefinitionInfo.
+.. code-block:: java
 
-  Is allowed to the participant to read all In/Out Properties of all compositions handled by the participant using the method getAcElementsDefinitions.
-  The following code is an example how to update the property 'myProperty' and send to ACM-runtime:
+  @Override
+  public void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList) throws PfModelException {
+      for (var acElementDefinition : elementDefinitionList) {
+          var inProperties = acElementDefinition.getAutomationCompositionElementToscaNodeTemplate().getProperties();
+          .......
+      }
+      .......
+  }
+
+The 'Common Properties' could be fetched during depriming events.
+
+.. code-block:: java
+
+  @Override
+  public void deprime(UUID compositionId) throws PfModelException {
+      var elementDefinitionList = intermediaryApi.getAcElementsDefinitions(compositionId);
+      for (var acElementDefinition : elementDefinitionList.values()) {
+          var inProperties = acElementDefinition.getAutomationCompositionElementToscaNodeTemplate().getProperties();
+          .......
+      }
+      .......
+  }
+ 
+The 'Out Properties' could be created or updated by participants. ACM-runtime will receive that Properties during ParticipantStatus event.
+The participant can trigger this event using the method sendAcDefinitionInfo.
+
+Is allowed to the participant to read all In/Out Properties of all compositions handled by the participant using the method getAcElementsDefinitions.
+The following code is an example how to update the property 'myProperty' and send to ACM-runtime:
 
 .. code-block:: java
 
@@ -354,6 +381,21 @@ The following example shows the Handler implementation and how could be the impl
     }
 
     @Override
+    public void migrate(UUID automationCompositionId, AcElementDeploy element, UUID compositionTargetId,
+            Map<String, Object> properties) throws PfModelException {
+
+        // TODO migrate process
+
+        if (isMigrateSuccess()) {
+            intermediaryApi.updateAutomationCompositionElementState(automationCompositionId, element.getId(),
+                    DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated");
+        } else {
+            intermediaryApi.updateAutomationCompositionElementState(automationCompositionId, element.getId(),
+                    DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Migrate failed!");
+        }
+    }
+
+    @Override
     public void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList)
             throws PfModelException {
 
diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst
index 0a033b50..6e247f7c 100755
--- a/docs/clamp/acm/acm-user-guide.rst
+++ b/docs/clamp/acm/acm-user-guide.rst
@@ -275,6 +275,24 @@ required operation.
 Note:
   Please refer the request payload section for updating the instance properties before deployment.
 
+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 user can update 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 and update the base url of the http request
+
+.. literalinclude:: files/AC-migrate.json
+   :language: json
+
 UnDeploy AutomationComposition
 ------------------------------
 The AC instances can be undeployed from the system by the participants.
@@ -378,10 +396,12 @@ The Json below is an example of configuration:
     "unlockSuccess": true,
     "deleteSuccess": true,
     "updateSuccess": true,
+    "migrateSuccess": true,
     "primeSuccess": true,
     "deprimeSuccess": true,
     "deployTimerMs": 1000,
     "undeployTimerMs": 1000,
+    "migrateTimerMs": 100,
     "lockTimerMs": 100,
     "unlockTimerMs": 100,
     "updateTimerMs": 100,
diff --git a/docs/clamp/acm/api-protocol/system-level-dialogues.rst b/docs/clamp/acm/api-protocol/system-level-dialogues.rst
index 49521882..a2efdc36 100755
--- a/docs/clamp/acm/api-protocol/system-level-dialogues.rst
+++ b/docs/clamp/acm/api-protocol/system-level-dialogues.rst
@@ -154,7 +154,21 @@ The ACM Runtime receives and stores the responses.
 
 .. image:: ../images/system-dialogues/UpdateAcElementsResponse.png
 
-3.5 Undeploy Automation Composition Instance
+3.5 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.
+
+.. image:: ../images/system-dialogues/MigrateAcInstance.png
+
+Each participant migrated its AC Element from the AC Instance
+
+.. image:: ../images/system-dialogues/MigrateAcElements.png
+
+The ACM Runtime receives and stores the responses.
+
+.. image:: ../images/system-dialogues/MigrateAcElementsResponse.png
+
+3.6 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.
 
@@ -168,12 +182,12 @@ The ACM Runtime receives and stores the responses.
 
 .. image:: ../images/system-dialogues/UndeployResponseStored.png
 
-3.6 Read Automation Composition Instances
+3.7 Read Automation Composition Instances
 -----------------------------------------
 
 .. image:: ../images/system-dialogues/ReadAcInstances.png
 
-3.7 Unlock Automation Composition Instance
+3.8 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.
 
@@ -187,7 +201,7 @@ The ACM Runtime receives and stores the responses.
 
 .. image:: ../images/system-dialogues/UnlockResponseStored.png
 
-3.8 Lock Automation Composition Instance
+3.9 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.
 
@@ -201,17 +215,17 @@ The ACM Runtime receives and stores the responses.
 
 .. image:: ../images/system-dialogues/LockResponseStored.png
 
-3.9 Update Operational State on Automation Composition Instance
----------------------------------------------------------------
+3.10 Update Operational State on Automation Composition Instance
+----------------------------------------------------------------
 
 .. image:: ../images/system-dialogues/UpdateOperationalState.png
 
-3.10 Update Usage State on Automation Composition Instance
+3.11 Update Usage State on Automation Composition Instance
 ----------------------------------------------------------
 
 .. image:: ../images/system-dialogues/UpdateUsageState.png
 
-3.11 Failure handling in ACM
+3.12 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.
diff --git a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
index 0c54ecc1..215ddc59 100644..100755
--- a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
+++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
@@ -78,7 +78,18 @@ Update of a Automation Composition Instance
 - It checks that AC Instance is in UNDEPLOYED/DEPLOYED deployState
 - It updates the Automation Composition to DB
 - the Rest-Api call returns the instanceId and the list of AC Element Instance
-- the runtime sends an update event to the participants which inturn performs the update operation on the deployed instances.
+- the runtime sends an update event to the participants which performs the update operation on the deployed instances.
+
+Migrate 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
+- runtime-ACM 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 updates the Automation Composition to DB
+- the Rest-Api call returns the instanceId and the list of AC Element Instance
+- the runtime sends a migrate event to the participants which performs the migrate operation on the deployed instances.
 
 Issues AC instance to change status
 +++++++++++++++++++++++++++++++++++
diff --git a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
index 36b13197..891f5771 100755
--- a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
+++ b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
@@ -27,6 +27,7 @@ Inbound messages to participants
 - PARTICIPANT_PRIME: a message received from clamp-acm runtime server for a participant update with tosca definitions of clamp-acm
 - PARTICIPANT_STATUS_REQ: A status request received from clamp-acm runtime server to send an immediate ParticipantStatus from all participants
 - PROPERTIES_UPDATE: a message received from clamp-acm runtime server for updating the Ac instance property values
+- AUTOMATION_COMPOSITION_MIGRATION: a message received from clamp-acm runtime server for migrating the Ac instance from a composition definition to a composition definition target
 - PARTICIPANT_RESTART: a message received from clamp-acm runtime server with tosca definitions and the Ac instances to handle restarting
 
 Outbound messages
@@ -60,13 +61,13 @@ Prime of an Automation Composition Definition Type
 - AC-runtime assigns the AC Definition to the participants based of Supported Element Definition Type by participant
 - it triggers the execution to send a broadcast PARTICIPANT_PRIME message
 - the message is built by ParticipantPrimePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition)
-- Participant-intermediary will receive a PARTICIPANT_PRIME message and stores the Tosca Service Template data on ParticipantHandler
+- Participant-intermediary will receive a PARTICIPANT_PRIME message and stores the Tosca Service Template data on CacheProvider
 
 DePrime of an Automation Composition Definition Type
 ----------------------------------------------------
 - AC-runtime triggers the execution to send a broadcast PARTICIPANT_PRIME message
 - the message is built by ParticipantPrimePublisher with an empty list of ParticipantDefinition
-- Participant-intermediary will receive a PARTICIPANT_PRIME message and deletes the Tosca Service Template data on ParticipantHandler
+- Participant-intermediary will receive a PARTICIPANT_PRIME message and deletes the Tosca Service Template data on CacheProvider
 
 Design of "issues automation composition commands to automation compositions" - case UNDEPLOYED to DEPLOYED
 -----------------------------------------------------------------------------------------------------------
@@ -82,13 +83,19 @@ Design of "issues automation composition commands to automation compositions" -
 - Participant-intermediary will receive AUTOMATION_COMPOSITION_STATE_CHANGE message and sends AC-element details to participants
 - Each participant performs its designated job of undeployment by interacting with respective frameworks
 
-
 Update of an Automation Composition Instance
 --------------------------------------------
 - AC-runtime updates the instance properties of the deployed Ac instances
 - it triggers the execution to send a broadcast PROPERTIES_UPDATE message
 - the message is built by AcElementPropertiesPublisher using the REST request payload (to fill the list of elements with the updated property values)
-- Participant-intermediary will receive a PROPERTIES_UPDATE message and stores the updated values of the elements on ParticipantHandler
+- Participant-intermediary will receive a PROPERTIES_UPDATE message and stores the updated values of the elements on CacheProvider
+
+Migrate of an Automation Composition Instance
+---------------------------------------------
+- AC-runtime saves the compositionTargetId and updates the instance properties of the deployed Ac instances
+- it triggers the execution to send a broadcast AUTOMATION_COMPOSITION_MIGRATION message
+- the message is built by AutomationCompositionMigrationPublisher using the REST request payload (to fill the compositionTargetId and list of elements with the updated property values)
+- Participant-intermediary will receive a AUTOMATION_COMPOSITION_MIGRATION message and stores the compositionTargetId and the updated values of the elements on CacheProvider
 
 Design of "issues automation composition commands to automation compositions" - case LOCKED to UNLOCKED
 -------------------------------------------------------------------------------------------------------
diff --git a/docs/clamp/acm/files/AC-migrate.json b/docs/clamp/acm/files/AC-migrate.json
new file mode 100755
index 00000000..32b56fd4
--- /dev/null
+++ b/docs/clamp/acm/files/AC-migrate.json
@@ -0,0 +1,16 @@
+{
+  "name": "DemoInstance0",
+  "version": "1.0.1",
+  "compositionId": "COMPOSITIONIDPLACEHOLDER",
+  "instanceId": "INSTANCEIDPLACEHOLDER",
+  "compositionTargetId": "COMPOSITIONIDTARGET",
+  "description": "Demo automation composition instance 0",
+  "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/ACM-Message-Table.csv b/docs/clamp/acm/files/ACM-Message-Table.csv
index 647c2f01..b706fe60 100755
--- a/docs/clamp/acm/files/ACM-Message-Table.csv
+++ b/docs/clamp/acm/files/ACM-Message-Table.csv
@@ -53,3 +53,9 @@ ParticipantRestart,ACM Runtime,Participant,Message to request update,participant
 ,,,,compositionId,The id of the AC Definition related to this message
 ,,,,participantDefinitionUpdates,Contains AC element definition values for a particular participant
 ,,,,messageType,Enum indicating the type of message PARTICIPANT_RESTART
+AutomationCompositionMigration,ACM Runtime,Participant,Message to request update,participantUpdatesList,A list of ParticipantUpdates instances which carries details of an updated participant.
+,,,,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
diff --git a/docs/clamp/acm/images/system-dialogues/MigrateAcElements.png b/docs/clamp/acm/images/system-dialogues/MigrateAcElements.png
new file mode 100755
index 00000000..478b3b35
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/MigrateAcElements.png
diff --git a/docs/clamp/acm/images/system-dialogues/MigrateAcElementsResponse.png b/docs/clamp/acm/images/system-dialogues/MigrateAcElementsResponse.png
new file mode 100755
index 00000000..4c96b2c3
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/MigrateAcElementsResponse.png
diff --git a/docs/clamp/acm/images/system-dialogues/MigrateAcInstance.png b/docs/clamp/acm/images/system-dialogues/MigrateAcInstance.png
new file mode 100755
index 00000000..ccd2c53b
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/MigrateAcInstance.png
diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrateAcElements.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrateAcElements.puml
new file mode 100755
index 00000000..2f9523fc
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/MigrateAcElements.puml
@@ -0,0 +1,15 @@
+@startuml

+participant "ACM Runtime"

+participant Participant

+participant "Participant Api"

+

+alt "instance Id and Composition Ids exist"

+  "ACM Runtime" -> Participant : [ASYNC] Migration message from source to target composition

+  Participant -> "Participant Api" : Migrate AC Element

+  "Participant Api" -> Participant : AC Element Migrated

+  Participant -> "ACM Runtime" : [ASYNC] Migration completed

+  note right

+  Returns AUTOMATION_COMPOSITION_STATE_CHANGE message.

+  end note

+end

+@enduml

diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrateAcElementsResponse.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrateAcElementsResponse.puml
new file mode 100755
index 00000000..3ba0410f
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/MigrateAcElementsResponse.puml
@@ -0,0 +1,10 @@
+@startuml

+participant "ACM Runtime"

+participant "ACM Database"

+participant Participant

+

+alt "instance Id and Composition Ids exist"

+  Participant -> "ACM Runtime" : [ASYNC] Migration completed

+  "ACM Runtime" -> "ACM Database" : instance and AC Element will be set in a final state (DEPLOYED)\n and Comp Def IDs change for instance and AC Element

+end

+@enduml

diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrateAcInstance.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrateAcInstance.puml
new file mode 100755
index 00000000..184e872a
--- /dev/null
+++ b/docs/clamp/acm/plantuml/system-dialogues/MigrateAcInstance.puml
@@ -0,0 +1,30 @@
+@startuml
+participant Rest
+participant "ACM Runtime"
+participant "ACM Database"
+participant Participants
+
+group Create New Composition type for Migration
+Rest -> "ACM Runtime" : Composition Definitions
+"ACM Runtime" -> "ACM Database" : Saved Definition
+Rest -> "ACM Runtime" : Prime Definition
+"ACM Runtime" -> Participants:  [ASYNC] Prime Definition
+end group
+
+group Migration per Instance
+/'Instance migration from source to target composition type. '/
+Rest -> "ACM Runtime" : Migrate Instance\n(InstanceId, sourceCompId, targetCompId, instance properties)
+note top
+Instance migration from source to target
+composition type.
+end note
+alt "instance Id and Composition Ids exist"
+  "ACM Runtime" -> "ACM Database" : Definition Validation
+  "ACM Runtime" -> "ACM Database" : instance and AC Element will be set\nin a transitional state (MIGRATING),\n new instance properties will be saved
+  "ACM Runtime" -> Participants : [ASYNC] Migration message from source to target composition
+  "ACM Runtime" -> Rest : Instance migration has been requested
+ else
+  "ACM Runtime" -> Rest : 400 Bad Reqest
+end
+end group
+@enduml