Add documentation for ACM

ACM user guide
 HowTo: My first composition
 Executing ACM workflow
 ACM participant guide

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

1 files changed, 126 insertions, 0 deletions

diff --git a/docs/clamp/acm/acm-participant-guide.rst b/docs/clamp/acm/acm-participant-guide.rst
new file mode 100644
index 00000000..0b576d6f
--- /dev/null
+++ b/docs/clamp/acm/acm-participant-guide.rst
@@ -0,0 +1,126 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (c) Nordix Foundation.  All rights reserved.
+
+.. _acm-participant-guide-label:
+
+Participant developer guide
+###########################
+
+.. contents::
+    :depth: 4
+
+The ACM runtime delegates the user requests to the participants for performing the actual operations.
+Hence the participant module in ACM is implemented adhering to a list of ACM protocols along with their own functional logic.
+It works in a contract with the Participant Intermediary module for communicating with ACM-R.
+This guide explains the design considerations for a new participant implementation in ACM.
+
+Please refer the following section for a detailed understanding of Inbound and outbound messages a participant interacts with.
+
+.. toctree::
+   :maxdepth: 2
+
+   design-impl/participants/participants
+
+Design considerations for a participant
+---------------------------------------
+
+In ONAP, the ACM-runtime and participant modules are implemented in Java spring boot. The participant Intermediary module
+which is added as a maven dependency to the participants has the default implementations available for listening the kafka
+events coming in from the ACM-runtime, process them and delegate them to the appropriate handler class. Similarly the
+Intermediary module also has the publisher class implementations for publishing events back from the participants to the ACM-runtime.
+
+Hence the new participants has to have this Participant Intermediary module as a dependency and should implement the following
+interfaces from the Participant Intermediary. It should also be provided with the following mandatory properties in order to make the participant
+work in synchronisation with ACM-runtime.
+
+The participant application should be provided with the following Intermediary parameter values in the application properties
+and the same is configured for the 'ParticipantIntermediaryParameters' object in the code.
+
+1. participantId - A unique participant UUID that is used by the runtime to identify the participant.
+2. ReportingTimeIntervalMs - Time inertval the participant should report the status/heartbeat to the runtime.
+3. clampAutomationCompositionTopics - This property takes in the kafka topic names and servers for the intermediary module to use.
+   These values should be provided for both source and sink configs. The following example shows the topic parameters set for using DMaap.
+
+.. code-block:: bash
+
+    clampAutomationCompositionTopics:
+          topicSources:
+            -
+              topic: POLICY-ACRUNTIME-PARTICIPANT
+              servers:
+                - ${topicServer:localhost}
+              topicCommInfrastructure: dmaap
+              fetchTimeout: 15000
+          topicSinks:
+            -
+              topic: POLICY-ACRUNTIME-PARTICIPANT
+              servers:
+                - ${topicServer:localhost}
+              topicCommInfrastructure: dmaap
+
+4. participantSupportedElementTypes - This property takes a list of typeName and typeVersion fields to define the types of AC elements the participant deals with.
+   These are user defined name and version and the same should be defined for the AC elements that are included in the TOSCA based AC definitions.
+
+.. code-block:: bash
+
+    participantSupportedElementTypes:
+      -
+        typeName: org.onap.policy.clamp.acm.PolicyAutomationCompositionElement
+        typeVersion: 1.0.0
+
+Interfaces to Implement
+-----------------------
+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.
+  The methods are as follows.
+
+.. code-block:: bash
+
+  1. void undeploy(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
+  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;
+
+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.
+
+APIs to invoke
+--------------
+ParticipantIntermediaryApi:
+  The participant intermediary api has the following methods that can be invoked from the participant for the following purposes.
+  1. The requested operations are completed in the handler class and the ACM-runtime needs to be notified.
+  2. To register the participant with the ACM-runtime during the startup.
+
+  The methods are as follows:
+
+  This following method is invoked to register the handler class that is implemented specific to the participant.
+
+.. code-block:: bash
+
+  void registerAutomationCompositionElementListener(AutomationCompositionElementListener automationCompositionElementListener);
+
+This following method is invoked to update the AC element state after each operation is completed in the participant.
+
+.. code-block:: bash
+
+  void updateAutomationCompositionElementState(UUID automationCompositionId, UUID id, DeployState newState,LockState lockState);
+
+
+In ONAP, the following participants are already implemented in java spring boot for various requirements. The maven modules
+can be referred here
+
+  `HTTP participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-http>`_.
+  `Kubernetes participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-kubernetes>`_.
+  `Policy participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-policy>`_.
+  `A1PMS participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-a1pms>`_.
+  `Kserve participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-kserve>`_.
+
+
+
+
+
+