Add documentation for Add/remove elements in Migration

Issue-ID: POLICY-5117
Signed-off-by: zrrmmua <ramesh.murugan.iyer@est.tech>
Change-Id: Ia946cbd1fbae27fa8c9fb9a08e4e0acadd1fc26f

5 files changed, 36 insertions, 5 deletions

diff --git a/docs/apex/APEX-MyFirstPolicyExample.rst b/docs/apex/APEX-MyFirstPolicyExample.rst
index 55dd2b87..d58eeb1d 100644
--- a/docs/apex/APEX-MyFirstPolicyExample.rst
+++ b/docs/apex/APEX-MyFirstPolicyExample.rst
@@ -367,8 +367,7 @@ Events
 
               .. container:: paragraph
 
-                  ``Avro`` schema definitions can be any valid `Avro <https://avro.apac
-                  he.org/docs/current/spec.html>`__ schema. For events using fields defined with
+                  ``Avro`` schema definitions can be any valid `Avro <https://avro.apache.org/docs/1.12.0/specification/>`__ schema. For events using fields defined with
                   Avro schemas, any incoming event containing that field must contain a value that conforms to the Avro schema.
 
             .. container:: paragraph
diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst
index 8a4996b1..81e5cd1f 100644
--- a/docs/apex/APEX-User-Manual.rst
+++ b/docs/apex/APEX-User-Manual.rst
@@ -2099,7 +2099,7 @@ Configure Context Schema Handler
                are supported. Characters commonly used in field names,
                such as ``.`` and ``-``, are not supported by AVRO. for
                more information see `Avro Spec:
-               Names <https://avro.apache.org/docs/1.8.1/spec.html#names>`__.
+               Names <https://avro.apache.org/docs/1.12.0/specification/>`__.
 
             .. container:: paragraph
 
diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst
index 0f814b4b..8cc4c40f 100644
--- a/docs/clamp/acm/acm-user-guide.rst
+++ b/docs/clamp/acm/acm-user-guide.rst
@@ -347,8 +347,12 @@ Example payload to migrate-precheck
 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.
-The user can update the instance property values if needed.
+The target composition have to be primed and there can be an addition/removal of elements at this stage.
+The user can update the instance property values for the existing elements if needed.
+A new element can be added and any elements that are no longer needed can be removed from the target composition and
+the migration payload.
+The migration payload should contain the updated element list for the instance.
+
 
 .. code-block:: bash
 
@@ -358,6 +362,8 @@ The user can update the instance property values if needed.
 Request Payload
 
 Example payload to migrate and update the base url of the http request
+A new element with id "709c62b3-8918-41b9-a747-d21eb79c6c22" has been added during migration which will be deployed
+by the participant.
 
 .. literalinclude:: files/AC-migrate.json
    :language: json
diff --git a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
index 81b7376f..46d4a85f 100644
--- a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
+++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
@@ -294,6 +294,26 @@ Example of MIGRATE order with Http_PMSHMicroserviceAutomationCompositionElement
 In that scenario the message AUTOMATION_COMPOSITION_MIGRATION has been sent three times,
 Http_PMSHMicroserviceAutomationCompositionElement and PMSH_K8SMicroserviceAutomationCompositionElement will be executed two times.
 
+Add and remove elements during Migration
+****************************************
+When an AC instance is migrated to a new AC definition, the user has the flexibility to add a new element or remove an existing element from the instance.
+The target AC composition definition should contain the new element definition added and also the respective elements removed while commissioning to ACM-R.
+The new elements are further instantiated in the migration request with the instance properties, and the elements required to be undeployed are removed accordingly.
+ACM-R sends the updated element list in the migration request to the participants where the participant is expected to handle the add/remove scenario.
+The migration method on the participant receives the details of previously existed composition/instance as well as the updated composition/instance and hence the difference in the new and old properties for an
+element can be identified by the participant.
+Participants can also identify the newly added elements and the removed elements with the ElementState enum that is set for each element.
+
+Example:
+ For a newly added element in the migration, the element information about the previously existed element will contain the ElementState enum set to the value "NOT_PRESENT" by the intermediary, and the updated element object will contain the
+ ElementState value "NEW". Based on these enum values on both the objects, the participant can identify a new element added in the migration. The participant can choose to trigger a deployment of this new element and update the element state once the
+ deploy operation is complete.
+
+ For the elements that are removed in the migration, the element information about the previously existed element will contain the ElementState enum set to the value "PRESENT" by the intermediary, and the object for the updated element info will contain the
+ ElementState value "REMOVED". Based on this, the participant can identify a removed element in the migration and choose to trigger an undeployment of this element. The element state after the undeploy operation need not be updated to ACM-R as the element is already removed in the ACM-R.
+ The participant is also expected to trigger a "DELETE" operation for the removed element if required in order to delete any element OutProperties if stored in the memory. Similarly, The element state after the delete operation need not be updated to ACM-R for the removed element.
+
+
 Configure custom namings for TOSCA node types
 *********************************************
 
diff --git a/docs/clamp/acm/files/AC-migrate.json b/docs/clamp/acm/files/AC-migrate.json
index 32b56fd4..27932fca 100755
--- a/docs/clamp/acm/files/AC-migrate.json
+++ b/docs/clamp/acm/files/AC-migrate.json
@@ -11,6 +11,12 @@
       "properties": {
         "baseUrl": "http://acm-starter-ac-element-impl_updated:8084"
       }
+    },
+    "709c62b3-8918-41b9-a747-d21eb79c6c22": {
+      "id": "709c62b3-8918-41b9-a747-d21eb79c6c22",
+      "properties": {
+        "baseUrl": "http://acm-sink-ac-element-impl_updated:8085"
+      }
     }
   }
 }