Add documentation for AC instance update support

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

11 files changed, 85 insertions, 13 deletions

diff --git a/docs/clamp/acm/acm-architecture.rst b/docs/clamp/acm/acm-architecture.rst
index 2e8f5186..e1272419 100644
--- a/docs/clamp/acm/acm-architecture.rst
+++ b/docs/clamp/acm/acm-architecture.rst
@@ -206,9 +206,9 @@ At Run Time, the following Automation Composition Life Cycle management capabili
       capability is that the Automation Composition instance is created in the Instance Automation Composition Inventory but
       has not been deployed on Participants.
 
-   #. **Automation Composition Instance Update on Participants:** Once the user is happy with the property
-      values, the Automation Composition Instance is updated on participants and the Automation Composition Elements
-      for this Automation Composition Instance are deployed or updated by participants using the acm metadata.
+   #. **Automation Composition Instance Update on Participants:** The AC instance property values can be updated before/after
+      the instance deployment. Before the deployment, the new property values are only updated on the runtime database whereas
+      the updated property values are also sent to the participants when the instance is in DEPLOYED state.
       The post condition for an execution of this capability is that the Automation Composition instance is updated
       on Participants.
 
diff --git a/docs/clamp/acm/acm-participant-guide.rst b/docs/clamp/acm/acm-participant-guide.rst
index 0b576d6f..dfd81778 100644
--- a/docs/clamp/acm/acm-participant-guide.rst
+++ b/docs/clamp/acm/acm-participant-guide.rst
@@ -75,7 +75,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 , getting UseState, getting OperationalState requests that are coming from the ACM-runtime.
+  undeploying, locking, unlocking , updating, getting UseState, getting OperationalState requests that are coming from the ACM-runtime.
   The methods are as follows.
 
 .. code-block:: bash
@@ -84,6 +84,7 @@ AutomationCompositionElementListener:
   2. void deploy(UUID automationCompositionId, AcElementDeploy element, Map<String, Object> properties) throws PfModelException;
   3. default void lock(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
   4. default void unlock(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
+  5. default void update(UUID automationCompositionId, AcElementDeploy element, 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.
diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst
index c2485ecf..8e22a639 100644
--- a/docs/clamp/acm/acm-user-guide.rst
+++ b/docs/clamp/acm/acm-user-guide.rst
@@ -210,6 +210,24 @@ Request payload
 .. literalinclude:: files/AC-instantiation.json
    :language: json
 
+Update AC instance properties (Optional)
+----------------------------------------
+Before the AC instance is deployed, the user is allowed to update the instance property values if needed. The runtime updates these new values
+in the database.
+
+.. 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 update the base url of the http request
+
+.. literalinclude:: files/AC-update.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.
@@ -243,6 +261,20 @@ 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.
 
+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
+in the database and also sends an update event to the participants. The participants has to implement the update method to perform the
+required operation.
+
+.. code-block:: bash
+
+  Invoke a POST request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
+
+Note:
+  Please refer the request payload section for updating the instance properties before deployment.
+
 UnDeploy AutomationComposition
 ------------------------------
 The AC instances can be undeployed from the system by the participants.
diff --git a/docs/clamp/acm/api-protocol/system-level-dialogues.rst b/docs/clamp/acm/api-protocol/system-level-dialogues.rst
index c5105313..e3ee09ab 100644
--- a/docs/clamp/acm/api-protocol/system-level-dialogues.rst
+++ b/docs/clamp/acm/api-protocol/system-level-dialogues.rst
@@ -140,7 +140,21 @@ The ACM Runtime receives and stores the responses.
 
 .. image:: ../images/system-dialogues/DeployResponseStored.png
 
-3.4 Undeploy Automation Composition Instance
+3.4 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.
+
+.. image:: ../images/system-dialogues/UpdateAcInstance.png
+
+Each participant updates its AC Element from the AC Instance
+
+.. image:: ../images/system-dialogues/UpdateAcElements.png
+
+The ACM Runtime receives and stores the responses.
+
+.. image:: ../images/system-dialogues/UpdateAcElementsResponse.png
+
+3.5 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.
 
@@ -154,12 +168,12 @@ The ACM Runtime receives and stores the responses.
 
 .. image:: ../images/system-dialogues/UndeployResponseStored.png
 
-3.5 Read Automation Composition Instances
+3.6 Read Automation Composition Instances
 -----------------------------------------
 
 .. image:: ../images/system-dialogues/ReadAcInstances.png
 
-3.6 Unlock Automation Composition Instance
+3.7 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.
 
@@ -173,7 +187,7 @@ The ACM Runtime receives and stores the responses.
 
 .. image:: ../images/system-dialogues/UnlockResponseStored.png
 
-3.7 Lock Automation Composition Instance
+3.8 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.
 
@@ -187,13 +201,13 @@ The ACM Runtime receives and stores the responses.
 
 .. image:: ../images/system-dialogues/LockResponseStored.png
 
-3.8 Update Operational State on Automation Composition Instance
+3.9 Update Operational State on Automation Composition Instance
 ---------------------------------------------------------------
 
 .. image:: ../images/system-dialogues/UpdateOperationalState.png
 
-3.9 Update Usage State on Automation Composition Instance
----------------------------------------------------------
+3.10 Update Usage State on Automation Composition Instance
+----------------------------------------------------------
 
 .. image:: ../images/system-dialogues/UpdateUsageState.png
 
diff --git a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
index dd6348c8..0c54ecc1 100644
--- a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
+++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
@@ -75,9 +75,10 @@ Update of a Automation Composition Instance
 +++++++++++++++++++++++++++++++++++++++++++
 - 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 and the instanceId
 - runtime-ACM receives the call by Rest-Api (InstantiationController)
-- It checks that AC Instance is in UNDEPLOYED deployState
+- 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.
 
 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 53215389..42ae2d5f 100644
--- a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
+++ b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst
@@ -26,6 +26,7 @@ Inbound messages to participants
 - AUTOMATION_COMPOSITION_DEPLOY: a message received from clamp-acm runtime server for a clamp-acm deploy 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
 
 Outbound messages
 -----------------
@@ -78,6 +79,14 @@ 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
+
 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
diff --git a/docs/clamp/acm/files/AC-instantiation.json b/docs/clamp/acm/files/AC-instantiation.json
index ebe1e8bb..8cffff61 100644
--- a/docs/clamp/acm/files/AC-instantiation.json
+++ b/docs/clamp/acm/files/AC-instantiation.json
@@ -30,7 +30,7 @@
           }
         }
       }
-    }
+    },
     "709c62b3-8918-41b9-a747-d21eb79c6c24": {
       "id": "709c62b3-8918-41b9-a747-d21eb79c6c24",
       "definition": {
diff --git a/docs/clamp/acm/files/AC-update.json b/docs/clamp/acm/files/AC-update.json
new file mode 100644
index 00000000..79ee1335
--- /dev/null
+++ b/docs/clamp/acm/files/AC-update.json
@@ -0,0 +1,15 @@
+{
+  "name": "DemoInstance0",
+  "version": "1.0.1",
+  "compositionId": "COMPOSITIONIDPLACEHOLDER",
+  "instanceId": "INSTANCEIDPLACEHOLDER",
+  "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"
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/docs/clamp/acm/images/system-dialogues/UpdateAcElements.png b/docs/clamp/acm/images/system-dialogues/UpdateAcElements.png
new file mode 100644
index 00000000..e39f53b1
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/UpdateAcElements.png
diff --git a/docs/clamp/acm/images/system-dialogues/UpdateAcElementsResponse.png b/docs/clamp/acm/images/system-dialogues/UpdateAcElementsResponse.png
new file mode 100644
index 00000000..8eef8f40
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/UpdateAcElementsResponse.png
diff --git a/docs/clamp/acm/images/system-dialogues/UpdateAcInstance.png b/docs/clamp/acm/images/system-dialogues/UpdateAcInstance.png
new file mode 100644
index 00000000..bcacd588
--- /dev/null
+++ b/docs/clamp/acm/images/system-dialogues/UpdateAcInstance.png