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

12 files changed, 954 insertions, 1 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>`_.
+
+
+
+
+
+
diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst
new file mode 100644
index 00000000..56dc66b7
--- /dev/null
+++ b/docs/clamp/acm/acm-user-guide.rst
@@ -0,0 +1,296 @@
+.. 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-user-guide-label:
+
+ACM user guide
+##############
+
+.. contents::
+    :depth: 4
+
+This guide helps the user to define their own composition definitions and explains the procedure to execute them via the
+Clamp Automation Composition Management Framework. This guide briefly talks about the commissioning, instantiation and
+deployment steps once the composition definitions are created.
+
+Defining a composition
+======================
+
+A composition can be created in yaml/json format as per the TOSCA standard. Please refer to the below section to understand
+the Tosca fundamental concepts and how an Automation Composition definition can be realised in the TOSCA.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   defining-acms
+
+HowTo: My First Automation Composition
+======================================
+
+An example scenario is considered where we have a microservice that can be installed with a helm chart in kubernetes and
+configured via REST api to perform some operation.This functionality can be realised as a composition in Tosca standard.
+The various sections of the composition definition includes:
+
+Data Types:
+-----------
+The user can define their own data types to be used in the composition definition. In this use case, we are defining three data types as follows.
+
+onap.datatypes.ToscaConceptIdentifier:
+  This is a composite data type that holds two key value pairs in it. This type is used as an identifier for automation
+  element types and participant types.This holds two string properties "name" and "version" and hence this data type can
+  be used for creating the other composition element ids.
+
+onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest:
+  The rest api request for configuring the microservice can use the RestRequest datatype for defining the request in TOSCA.
+  This holds the string properties "httpMethod", "path", "body" and an integer property "expectedResponse" for defining
+  the rest request.
+
+  Note that the "restRequestId" property which is of type "onap.datatypes.ToscaConceptIdentifier" that was defined in the
+  previous step.
+
+onap.datatypes.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity:
+  This data type holds a list of rest requests in case a microservice requires more than one rest request for configuration.
+  This holds the "configurationEntityId" which is of type "onap.datatypes.ToscaConceptIdentifier" and "restSequence" property
+  to hold the list of "onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest"
+
+
+.. literalinclude:: files/acm-datatypes.yaml
+   :language: yaml
+
+
+Node Types:
+-----------
+A Node Type is a reusable entity that defines the type of one or more Node Templates.
+An Interface Type is a reusable entity that describes a set of operations that can be used to interact with or manage a
+node or relationship in a TOSCA topology. The actual acm elements will be created under the Node templates deriving from
+these node types. We are going to define the following element types for ACM:
+
+org.onap.policy.clamp.acm.Participant:
+  This is a participant element type to define various participants in ACM. It holds the string property "provider".
+
+org.onap.policy.clamp.acm.AutomationCompositionElement:
+  This node type defines the primitive Automation composition element type that includes various common properties for all
+  the ACM elements.
+  Here we are defining various timeout properties and startPhase parameter that are common for all the AC elements.
+
+  Note: This node type value should not be changed as the ACM framework identifies the AC elements based on this type.
+
+org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
+  This node type is used to define AC elements that are associated with kubernetes operations. It is further derived from the
+  "org.onap.policy.clamp.acm.AutomationCompositionElement" type and hence supports its common properties and also includes
+  additional properties related to helm charts.
+  We are going to create kubernetes AC elements of this type, under the Node templates.
+
+org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
+  Node type for AC elements associated with REST operations. It is derived from the "org.onap.policy.clamp.acm.AutomationCompositionElement"
+  type and hence supports its common properties and also supports additional properties for REST operation.
+  We are going to create a REST AC element of this type, under the Node templates.
+
+org.onap.policy.clamp.acm.AutomationComposition:
+  Primitive node type for defining Automation composition definitions that comprises one or more AC elements in it.
+  The AC definition of this type will be created under the Node templates.
+
+  Note: This node type value should not be changed as the ACM framework identifies the AC definitions based on this type.
+
+.. literalinclude:: files/acm-nodetypes.yaml
+   :language: yaml
+
+Node Templates:
+---------------
+A Node Template specifies the occurrence of a manageable software component as part of an application's topology model
+which is defined in a TOSCA Service Template. We create the actual participants and AC elements involved in this use case
+under the node templates.
+There are no element properties supplied at this point since it will be provided by the user during the instantiation.
+
+org.onap.k8s.acm.K8SAutomationCompositionParticipant:
+  A kubernetes participant element that processes the kubernetes AC elements in the composition.
+  This element is of node type "org.onap.policy.clamp.acm.Participant"
+
+onap.policy.clamp.ac.element.K8S_AutomationCompositionElement:
+  An AC element for kubernetes helm chart installation of the microservice derived from the node type
+  "org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement".
+  The common element properties are provided with values as part of commissioning the definition.
+
+org.onap.policy.clamp.acm.HttpParticipant:
+  A http participant element that processes the REST AC elements in the composition.
+  This element is of type "org.onap.policy.clamp.acm.Participant"
+
+onap.policy.clamp.ac.element.Http_AutomationCompositionElement:
+ An AC element for REST operation in the microservice derived from the node type
+ "org.onap.policy.clamp.acm.HttpAutomationCompositionElement".
+ The common element properties startPhase and timeout are provided with values as part of commissioning the definition.
+
+onap.policy.clamp.ac.element.AutomationCompositionDefinition:
+ The actual Automation Composition definition that comprises the list of AC elements mapped to it.
+ This element is of node type "org.onap.policy.clamp.acm.AutomationComposition"
+
+.. literalinclude:: files/acm-nodetemplates.yaml
+   :language: yaml
+
+Completed tosca template :download:`click here <files/acm-tosca.yaml>`
+
+Once the Tosca template definition is created, the ACM workflow can be executed to create and deploy the compositions.
+Please refer the following section for running ACM workflow.
+
+ACM workflow
+============
+
+ACM framework exposes REST interfaces for creating and deploying the user defined compositions. In this section, the
+TOSCA template created in the previous step can be commissioned, and then AC instances can be created and deployed for
+the same.
+
+This section assumes that the user has read about the ACM APIs and Protocols documentation and understands the ACM
+operations on a high level before proceeding with the workflow.
+
+
+Prerequisites:
+  - ACM components including acm-runtime, required participants (http and kubernetes in this case) and Dmaap/kafka clients are deployed in docker or kubernetes environment.
+  - Kubernetes and Helm are installed.
+  - Chartmuseum server is installed to host the acelement microservice helm chart. (`Procedure to install chartmuseum <https://wiki.onap.org/display/DW/Microk8s+and+helm+setup+in+Ubuntu>`_.)
+  - The helm chart for ACM test microservice is available in the policy/clamp repository that can be cloned locally and uploaded to the chartmuseum using helm push.(`AC element helm chart <https://github.com/onap/policy-clamp/tree/master/examples/src/main/resources/clamp/acm/acelement-helm>`_.)
+
+Please refer the `ACM swagger document <https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/openapi.yaml>`_. for REST API information for all the ACM operations.
+This section guides through the various steps involved in executing the ACM workflow for deploying the test microservice element.
+
+Commissioning the AC definition
+-------------------------------
+Commissioning refers to storing the composition definition on the ACM database. The created tosca template is posted as a request payload.
+
+.. code-block:: bash
+
+  Invoke a POST request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions'
+
+This returns a 202 response on the successful creation of the composition definition.
+
+Note:
+  The rest response returns the compositionId on a successful creation that requires to be used in the subsequent requests.
+
+Prime AC definitions
+--------------------
+Priming associates the AC elements with suitable participants and sends the corresponding AC element information to the participants.
+
+.. code-block:: bash
+
+  Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
+
+Request payload
+
+.. literalinclude:: files/AC-priming.json
+   :language: json
+
+This returns a 202 response on a successful priming.
+
+Instantiate AutomationComposition
+---------------------------------
+Instantiation refers to creating an AC instance on the database by initialising the element properties for each element in the composition.
+These values requires to be provided by the user as per their use case requirement. In this case, we are passing the helm chart information
+of the test microservice for the Ac element "onap.policy.clamp.ac.element.K8S_AutomationCompositionElement" which will be processed and installed
+by the kubernetes participant on a deployment request.
+
+Similarly the REST request data that are to be executed on the microservice will be passed on for the http AC element "onap.policy.clamp.ac.element.Http_AutomationCompositionElement"
+which will be executed by the http participant. Please refer to the properties of the elements in the json payload.
+
+Note:
+  In this scenario, the kubernetes element requires to be invoked first to install the helm chart and then the http element needs to be invoked to configure the microservice.
+  This is achieved by using the "startPhase" property on the AC element properties. The elements with the startPhase value defined are executed on a sequence starting from the least value to the higher value.
+  Each element in the request payload is assigned with a uniques UUID which will be automatically generated by the GUI in the upcoming releases.
+
+.. code-block:: bash
+
+  Invoke a POST request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
+
+The compositionId retrieved from the previous step should be updated in the request body. This returns a 201 response on a successful instantiation.
+This also returns the instanceId in the response that can be used in the subsequent requests.
+
+Request payload
+
+.. literalinclude:: files/AC-instantiation.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.
+In this case, the kubernetes participant will be installing the test microservice helm chart on the kubernetes cluster and the http participant will be
+executing the REST requests on the microservice endpoints.
+
+.. 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 deploy order request. The elements will be in "DEPLOYING" state until the completion and then the state of
+the elements are updated to "DEPLOYED"
+The current status of the deployment 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-deploy.json
+   :language: json
+
+Note:
+  The user can further implement the admin states 'LOCK' and 'UNLOCK' on the participants to further cascade the deployment operations.
+  If these states are implemented, then a subsequent request to LOCK and UNLOCK requires to be triggered following the deployment.
+
+Once all the AC elements are deployed, there should be a test microservice pod running on the kubernetes cluster which is
+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.
+
+UnDeploy AutomationComposition
+------------------------------
+The AC instances can be undeployed from the system by the participants.
+
+.. 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 successful deploy order request.
+
+Request payload
+
+.. literalinclude:: files/AC-undeploy.json
+   :language: json
+
+Uninstantiate AC instance
+-------------------------
+This deletes the AC instance from the database including all the element properties that are initialised.
+
+.. code-block:: bash
+
+  Invoke a DELETE request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
+
+This returns 200 on successful deletion of the instance.
+
+Deprime Ac defintions
+---------------------
+Once the AC instance is deleted, it can be deprimed from the participants to be safely deleted from the database.
+
+.. code-block:: bash
+
+  Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
+
+This returns a 202 response on a successful operation.
+
+Request payload
+
+.. literalinclude:: files/AC-depriming.json
+   :language: json
+
+Delete AC defintion
+-------------------
+The AC definitions can be deleted if there are no instances are running and it is not primed to the participants.
+
+.. code-block:: bash
+
+  Invoke a DELETE request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
+
+This return a 200 response on a successful deletion operation.
\ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-deploy.json b/docs/clamp/acm/files/AC-deploy.json
new file mode 100644
index 00000000..cf65ba65
--- /dev/null
+++ b/docs/clamp/acm/files/AC-deploy.json
@@ -0,0 +1,3 @@
+{
+  "deployOrder": "DEPLOY"
+}
\ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-depriming.json b/docs/clamp/acm/files/AC-depriming.json
new file mode 100644
index 00000000..d2311b97
--- /dev/null
+++ b/docs/clamp/acm/files/AC-depriming.json
@@ -0,0 +1,3 @@
+{
+  "primeOrder": "DEPRIME"
+}
\ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-instantiation.json b/docs/clamp/acm/files/AC-instantiation.json
new file mode 100644
index 00000000..ebe1e8bb
--- /dev/null
+++ b/docs/clamp/acm/files/AC-instantiation.json
@@ -0,0 +1,71 @@
+{
+  "name": "DemoInstance0",
+  "version": "1.0.1",
+  "compositionId": "COMPOSITIONIDPLACEHOLDER",
+  "description": "Demo automation composition instance 0",
+  "elements": {
+    "709c62b3-8918-41b9-a747-d21eb79c6c21": {
+      "id": "709c62b3-8918-41b9-a747-d21eb79c6c21",
+      "definition": {
+        "name": "onap.policy.clamp.ac.element.K8S_AutomationCompositionElement",
+        "version": "1.2.3"
+      },
+      "description": "Starter Automation Composition Element for the Demo",
+      "properties": {
+        "chart": {
+          "chartId": {
+            "name": "acelement",
+            "version": "0.1.0"
+          },
+          "namespace": "default",
+          "releaseName": "acm-starter",
+          "podName": "acm-starter",
+          "repository": {
+            "repoName": "policy-chartmuseum",
+            "address": "http://policy-chartmuseum:8080"
+          },
+          "overrideParams": {
+            "acelement.elementId.name": "onap.policy.clamp.ac.starter",
+            "service.nodeport": 30800
+          }
+        }
+      }
+    }
+    "709c62b3-8918-41b9-a747-d21eb79c6c24": {
+      "id": "709c62b3-8918-41b9-a747-d21eb79c6c24",
+      "definition": {
+        "name": "onap.policy.clamp.ac.element.Http_AutomationCompositionElement",
+        "version": "1.2.3"
+      },
+      "description": "Starter Automation Composition Element for the Demo",
+      "properties": {
+        "baseUrl": "http://acm-starter-ac-element-impl:8084",
+        "httpHeaders": {
+          "Content-Type": "application/json",
+          "Authorization": "Basic YWNtVXNlcjp6YiFYenRHMzQ="
+        },
+        "configurationEntities": [
+          {
+            "configurationEntityId": {
+              "name": "onap.policy.clamp.ac.starter",
+              "version": "1.0.0"
+            },
+            "restSequence": [
+              {
+                "restRequestId": {
+                  "name": "request1",
+                  "version": "1.0.1"
+                },
+                "httpMethod": "POST",
+                "path": "/onap/policy/clamp/acelement/v2/activate",
+                "body": "{ \"receiverId\": { \"name\": \"onap.policy.clamp.ac.startertobridge\", \"version\": \"1.0.0\" }, \"timerMs\": 20000, \"elementType\": \"STARTER\", \"topicParameterGroup\": { \"server\": \"message-router:3904\", \"listenerTopic\": \"POLICY_UPDATE_MSG\", \"publisherTopic\": \"AC_ELEMENT_MSG\", \"fetchTimeout\": 15000, \"topicCommInfrastructure\": \"dmaap\" } }",
+                "expectedResponse": 201
+              }
+            ]
+          }
+        ]
+      }
+    }
+
+  }
+}
\ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-priming.json b/docs/clamp/acm/files/AC-priming.json
new file mode 100644
index 00000000..76fafeca
--- /dev/null
+++ b/docs/clamp/acm/files/AC-priming.json
@@ -0,0 +1,3 @@
+{
+  "primeOrder": "PRIME"
+}
\ No newline at end of file
diff --git a/docs/clamp/acm/files/AC-undeploy.json b/docs/clamp/acm/files/AC-undeploy.json
new file mode 100644
index 00000000..148bca11
--- /dev/null
+++ b/docs/clamp/acm/files/AC-undeploy.json
@@ -0,0 +1,3 @@
+{
+  "deployOrder": "UNDEPLOY"
+}
\ No newline at end of file
diff --git a/docs/clamp/acm/files/acm-datatypes.yaml b/docs/clamp/acm/files/acm-datatypes.yaml
new file mode 100644
index 00000000..ff23fbf2
--- /dev/null
+++ b/docs/clamp/acm/files/acm-datatypes.yaml
@@ -0,0 +1,58 @@
+data_types:
+  onap.datatypes.ToscaConceptIdentifier:
+    derived_from: tosca.datatypes.Root
+    properties:
+      name:
+        type: string
+        required: true
+      version:
+        type: string
+        required: true
+
+  onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest:
+    version: 1.0.0
+    derived_from: tosca.datatypes.Root
+    properties:
+      restRequestId:
+        type: onap.datatypes.ToscaConceptIdentifier
+        required: true
+        description: The name and version of a REST request to be sent to a REST endpoint
+      httpMethod:
+        type: string
+        required: true
+        constraints:
+          - valid_values:
+              - POST
+              - PUT
+              - GET
+              - DELETE
+        description: The REST method to use
+      path:
+        type: string
+        required: true
+        description: The path of the REST request relative to the base URL
+      body:
+        type: string
+        required: false
+        description: The body of the REST request for PUT and POST requests
+      expectedResponse:
+        type: integer
+        required: true
+        constraints: []
+        description: THe expected HTTP status code for the REST request
+  onap.datatypes.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity:
+    version: 1.0.0
+    derived_from: tosca.datatypes.Root
+    properties:
+      configurationEntityId:
+        type: onap.datatypes.ToscaConceptIdentifier
+        required: true
+        description:
+          The name and version of a Configuration Entity to be handled
+          by the HTTP Automation Composition Element
+      restSequence:
+        type: list
+        entry_schema:
+          type: onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest
+          type_version: 1.0.0
+        description: A sequence of REST commands to send to the REST endpoint
\ No newline at end of file
diff --git a/docs/clamp/acm/files/acm-nodetemplates.yaml b/docs/clamp/acm/files/acm-nodetemplates.yaml
new file mode 100644
index 00000000..8e17a1e4
--- /dev/null
+++ b/docs/clamp/acm/files/acm-nodetemplates.yaml
@@ -0,0 +1,50 @@
+topology_template:
+  node_templates:
+    org.onap.k8s.acm.K8SAutomationCompositionParticipant:
+      version: 2.3.4
+      type: org.onap.policy.clamp.acm.Participant
+      type_version: 1.0.1
+      description: Participant for K8S
+      properties:
+        provider: ONAP
+    onap.policy.clamp.ac.element.K8S_AutomationCompositionElement:
+      # Helm chart parameters for the microservice
+      version: 1.2.3
+      type: org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement
+      type_version: 1.0.0
+      description: Automation composition element for the K8S microservice for AC Element Starter
+      properties:
+        provider: ONAP
+        startPhase: 0
+        uninitializedToPassiveTimeout: 300
+        podStatusCheckInterval: 30
+    org.onap.policy.clamp.acm.HttpParticipant:
+      version: 2.3.4
+      type: org.onap.policy.clamp.acm.Participant
+      type_version: 1.0.1
+      description: Participant for Http requests
+      properties:
+        provider: ONAP
+    onap.policy.clamp.ac.element.Http_AutomationCompositionElement:
+      # Http config for AC Element microservice.
+      version: 1.2.3
+      type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
+      type_version: 1.0.0
+      description: Automation composition element for the http requests of AC Element Starter microservice
+      properties:
+        provider: ONAP
+        uninitializedToPassiveTimeout: 300
+        startPhase: 1
+
+    onap.policy.clamp.ac.element.AutomationCompositionDefinition:
+      version: 1.2.3
+      type: org.onap.policy.clamp.acm.AutomationComposition
+      type_version: 1.0.1
+      description: Automation composition for Demo
+      properties:
+        provider: ONAP
+        elements:
+          - name: onap.policy.clamp.ac.element.K8S_AutomationCompositionElement
+            version: 1.2.3
+          - name: onap.policy.clamp.ac.element.Http_AutomationCompositionElement
+            version: 1.2.3
diff --git a/docs/clamp/acm/files/acm-nodetypes.yaml b/docs/clamp/acm/files/acm-nodetypes.yaml
new file mode 100644
index 00000000..0c9ed362
--- /dev/null
+++ b/docs/clamp/acm/files/acm-nodetypes.yaml
@@ -0,0 +1,113 @@
+node_types:
+  org.onap.policy.clamp.acm.Participant:
+    version: 1.0.1
+    derived_from: tosca.nodetypes.Root
+    properties:
+      provider:
+        type: string
+        required: false
+  org.onap.policy.clamp.acm.AutomationCompositionElement:
+    version: 1.0.1
+    derived_from: tosca.nodetypes.Root
+    properties:
+      provider:
+        type: string
+        required: false
+        metadata:
+          common: true
+        description: Specifies the organization that provides the automation composition element
+      startPhase:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        metadata:
+          common: true
+        description:
+          A value indicating the start phase in which this automation composition element will be started, the
+          first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped
+          in reverse start phase order. Automation Composition Elements with the same start phase are started and
+          stopped simultaneously
+      uninitializedToPassiveTimeout:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        default: 60
+        metadata:
+          common: true
+        description: The maximum time in seconds to wait for a state chage from uninitialized to passive
+      passiveToRunningTimeout:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        default: 60
+        metadata:
+          common: true
+        description: The maximum time in seconds to wait for a state chage from passive to running
+      runningToPassiveTimeout:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        default: 60
+        metadata:
+          common: true
+        description: The maximum time in seconds to wait for a state chage from running to passive
+      passiveToUninitializedTimeout:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        default: 60
+        metadata:
+          common: true
+        description: The maximum time in seconds to wait for a state chage from passive to uninitialized
+  org.onap.policy.clamp.acm.AutomationComposition:
+    version: 1.0.1
+    derived_from: tosca.nodetypes.Root
+    properties:
+      provider:
+        type: string
+        required: false
+        metadata:
+          common: true
+        description: Specifies the organization that provides the automation composition element
+      elements:
+        type: list
+        required: true
+        metadata:
+          common: true
+        entry_schema:
+          type: onap.datatypes.ToscaConceptIdentifier
+        description: Specifies a list of automation composition element definitions that make up this automation composition definition
+  org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
+    version: 1.0.0
+    derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
+    properties:
+      chart:
+        type: dictionary
+        required: true
+        description: This consumes the helm chart information in key value pairs.
+  org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
+    version: 1.0.0
+    derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
+    properties:
+      baseUrl:
+        type: string
+        required: true
+        description: The base URL to be prepended to each path, identifies the host for the REST endpoints.
+      httpHeaders:
+        type: map
+        required: false
+        entry_schema:
+          type: string
+        description: HTTP headers to send on REST requests
+      configurationEntities:
+        type: map
+        required: true
+        entry_schema:
+          type: org.onap.datatypes.policy.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity
+          type_version: 1.0.0
+        description: The connfiguration entities the Automation Composition Element is managing and their associated REST requests
\ No newline at end of file
diff --git a/docs/clamp/acm/files/acm-tosca.yaml b/docs/clamp/acm/files/acm-tosca.yaml
new file mode 100644
index 00000000..714760a8
--- /dev/null
+++ b/docs/clamp/acm/files/acm-tosca.yaml
@@ -0,0 +1,225 @@
+tosca_definitions_version: tosca_simple_yaml_1_3
+data_types:
+  onap.datatypes.ToscaConceptIdentifier:
+    derived_from: tosca.datatypes.Root
+    properties:
+      name:
+        type: string
+        required: true
+      version:
+        type: string
+        required: true
+
+  onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest:
+    version: 1.0.0
+    derived_from: tosca.datatypes.Root
+    properties:
+      restRequestId:
+        type: onap.datatypes.ToscaConceptIdentifier
+        required: true
+        description: The name and version of a REST request to be sent to a REST endpoint
+      httpMethod:
+        type: string
+        required: true
+        constraints:
+          - valid_values:
+              - POST
+              - PUT
+              - GET
+              - DELETE
+        description: The REST method to use
+      path:
+        type: string
+        required: true
+        description: The path of the REST request relative to the base URL
+      body:
+        type: string
+        required: false
+        description: The body of the REST request for PUT and POST requests
+      expectedResponse:
+        type: integer
+        required: true
+        constraints: []
+        description: THe expected HTTP status code for the REST request
+  onap.datatypes.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity:
+    version: 1.0.0
+    derived_from: tosca.datatypes.Root
+    properties:
+      configurationEntityId:
+        type: onap.datatypes.ToscaConceptIdentifier
+        required: true
+        description:
+          The name and version of a Configuration Entity to be handled
+          by the HTTP Automation Composition Element
+      restSequence:
+        type: list
+        entry_schema:
+          type: onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest
+          type_version: 1.0.0
+        description: A sequence of REST commands to send to the REST endpoint
+
+
+node_types:
+  org.onap.policy.clamp.acm.Participant:
+    version: 1.0.1
+    derived_from: tosca.nodetypes.Root
+    properties:
+      provider:
+        type: string
+        required: false
+  org.onap.policy.clamp.acm.AutomationCompositionElement:
+    version: 1.0.1
+    derived_from: tosca.nodetypes.Root
+    properties:
+      provider:
+        type: string
+        required: false
+        metadata:
+          common: true
+        description: Specifies the organization that provides the automation composition element
+      startPhase:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        metadata:
+          common: true
+        description:
+          A value indicating the start phase in which this automation composition element will be started, the
+          first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped
+          in reverse start phase order. Automation Composition Elements with the same start phase are started and
+          stopped simultaneously
+      uninitializedToPassiveTimeout:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        default: 60
+        metadata:
+          common: true
+        description: The maximum time in seconds to wait for a state chage from uninitialized to passive
+      passiveToRunningTimeout:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        default: 60
+        metadata:
+          common: true
+        description: The maximum time in seconds to wait for a state chage from passive to running
+      runningToPassiveTimeout:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        default: 60
+        metadata:
+          common: true
+        description: The maximum time in seconds to wait for a state chage from running to passive
+      passiveToUninitializedTimeout:
+        type: integer
+        required: false
+        constraints:
+          - greater_or_equal: 0
+        default: 60
+        metadata:
+          common: true
+        description: The maximum time in seconds to wait for a state chage from passive to uninitialized
+  org.onap.policy.clamp.acm.AutomationComposition:
+    version: 1.0.1
+    derived_from: tosca.nodetypes.Root
+    properties:
+      provider:
+        type: string
+        required: false
+        metadata:
+          common: true
+        description: Specifies the organization that provides the automation composition element
+      elements:
+        type: list
+        required: true
+        metadata:
+          common: true
+        entry_schema:
+          type: onap.datatypes.ToscaConceptIdentifier
+        description: Specifies a list of automation composition element definitions that make up this automation composition definition
+  org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
+    version: 1.0.0
+    derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
+    properties:
+      chart:
+        type: dictionary
+        required: true
+        description: This consumes the helm chart information in key value pairs.
+  org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
+    version: 1.0.0
+    derived_from: org.onap.policy.clamp.acm.AutomationCompositionElement
+    properties:
+      baseUrl:
+        type: string
+        required: true
+        description: The base URL to be prepended to each path, identifies the host for the REST endpoints.
+      httpHeaders:
+        type: map
+        required: false
+        entry_schema:
+          type: string
+        description: HTTP headers to send on REST requests
+      configurationEntities:
+        type: map
+        required: true
+        entry_schema:
+          type: org.onap.datatypes.policy.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity
+          type_version: 1.0.0
+        description: The connfiguration entities the Automation Composition Element is managing and their associated REST requests
+
+topology_template:
+  node_templates:
+    org.onap.k8s.acm.K8SAutomationCompositionParticipant:
+      version: 2.3.4
+      type: org.onap.policy.clamp.acm.Participant
+      type_version: 1.0.1
+      description: Participant for K8S
+      properties:
+        provider: ONAP
+    org.onap.policy.clamp.ac.element.K8S_AutomationCompositionElement:
+      # Helm chart parameters for the microservice
+      version: 1.2.3
+      type: org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement
+      type_version: 1.0.0
+      description: Automation composition element for the K8S microservice for AC Element Starter
+      properties:
+        provider: ONAP
+        startPhase: 0
+        uninitializedToPassiveTimeout: 300
+        podStatusCheckInterval: 30
+    org.onap.policy.clamp.acm.HttpParticipant:
+      version: 2.3.4
+      type: org.onap.policy.clamp.acm.Participant
+      type_version: 1.0.1
+      description: Participant for Http requests
+      properties:
+        provider: ONAP
+    onap.policy.clamp.ac.element.Http_AutomationCompositionElement:
+      # Http config for AC Element microservice.
+      version: 1.2.3
+      type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
+      type_version: 1.0.0
+      description: Automation composition element for the http requests of AC Element Starter microservice
+      properties:
+        provider: ONAP
+        uninitializedToPassiveTimeout: 300
+        startPhase: 1
+
+    onap.policy.clamp.acm.AutomationCompositionElement:
+      version: 1.2.3
+      type: org.onap.policy.clamp.acm.AutomationComposition
+      type_version: 1.0.1
+      description: Automation composition for Demo
+      properties:
+        provider: ONAP
+        elements:
+          - name: onap.policy.clamp.ac.element.K8S_AutomationCompositionElement
+            version: 1.2.3
+          - name: onap.policy.clamp.ac.element.Http_AutomationCompositionElement
+            version: 1.2.3
\ No newline at end of file
diff --git a/docs/clamp/clamp.rst b/docs/clamp/clamp.rst
index 40ab6790..0f051155 100644
--- a/docs/clamp/clamp.rst
+++ b/docs/clamp/clamp.rst
@@ -16,10 +16,12 @@ described in TOSCA.
    acm/defining-acms
    acm/api-protocol/api-protocol-tree
    acm/design-impl/design-impl
+   acm/acm-user-guide
+   acm/acm-participant-guide
 
 .. note::
       Policy/CLAMP was merged into the Policy Framework in the Honolulu release of ONAP. Prior to that release, it was
-      a separate project. The release notes for CLAMP when it existed as a separate proejct are located below.
+      a separate project. The release notes for CLAMP when it existed as a separate project are located below.
 
 .. toctree::
    :maxdepth: 1