Add new endpoints for ACM state handling

This commit introduces the Swagger changes required for the updates to
the State Handling in ACM.

The Update handling on the endpoints has changed and will be completed
in future reviews. In the meantime, some stubs and unit tests have been
temporarily disabled.

Issue-ID: POLICY-4487
Change-Id: I40b8cbb188d809b43c3e385aea35f88e9ea7da2b
Signed-off-by: liamfallon <liam.fallon@est.tech>

5 files changed, 468 insertions, 68 deletions

diff --git a/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/CommissioningController.java b/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/CommissioningController.java
index 653bb9daf..a6b1ab38d 100644
--- a/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/CommissioningController.java
+++ b/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/CommissioningController.java
@@ -21,10 +21,12 @@
 package org.onap.policy.clamp.acm.runtime.main.rest;
 
 import java.util.UUID;
+import javax.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.onap.policy.clamp.acm.runtime.commissioning.CommissioningProvider;
 import org.onap.policy.clamp.acm.runtime.main.rest.gen.AutomationCompositionDefinitionApi;
 import org.onap.policy.clamp.acm.runtime.main.web.AbstractRestController;
+import org.onap.policy.clamp.models.acm.messages.rest.commissioning.AcTypeStateUpdate;
 import org.onap.policy.clamp.models.acm.messages.rest.commissioning.CommissioningResponse;
 import org.onap.policy.models.base.PfModelException;
 import org.onap.policy.models.tosca.authorative.concepts.ToscaServiceTemplate;
@@ -90,9 +92,15 @@ public class CommissioningController extends AbstractRestController implements A
         return ResponseEntity.ok().body(provider.getAutomationCompositionDefinitions(compositionId));
     }
 
-    @Override
     public ResponseEntity<CommissioningResponse> updateCompositionDefinition(UUID compositionId,
         ToscaServiceTemplate body, UUID requestId) {
         return ResponseEntity.ok().body(provider.updateCompositionDefinition(compositionId, body));
     }
+
+    @Override
+    public ResponseEntity<Void> compositionDefinitionPriming(UUID compositionId, UUID requestId,
+        @Valid AcTypeStateUpdate body) {
+        // TODO Auto-generated method stub
+        return null;
+    }
 }
diff --git a/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/InstantiationController.java b/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/InstantiationController.java
index 92651bc91..e9f1eaac0 100644
--- a/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/InstantiationController.java
+++ b/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/InstantiationController.java
@@ -22,12 +22,14 @@
 package org.onap.policy.clamp.acm.runtime.main.rest;
 
 import java.util.UUID;
+import javax.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.onap.policy.clamp.acm.runtime.instantiation.AutomationCompositionInstantiationProvider;
 import org.onap.policy.clamp.acm.runtime.main.rest.gen.AutomationCompositionInstanceApi;
 import org.onap.policy.clamp.acm.runtime.main.web.AbstractRestController;
 import org.onap.policy.clamp.models.acm.concepts.AutomationComposition;
 import org.onap.policy.clamp.models.acm.concepts.AutomationCompositions;
+import org.onap.policy.clamp.models.acm.messages.rest.instantiation.AcInstanceStateUpdate;
 import org.onap.policy.clamp.models.acm.messages.rest.instantiation.InstantiationResponse;
 import org.onap.policy.clamp.models.acm.messages.rest.instantiation.InstantiationUpdate;
 import org.springframework.context.annotation.Profile;
@@ -102,7 +104,6 @@ public class InstantiationController extends AbstractRestController implements A
      * @param requestId request ID used in ONAP logging
      * @return a response
      */
-    @Override
     public ResponseEntity<InstantiationResponse> updateCompositionInstance(UUID compositionId, UUID instanceId,
             InstantiationUpdate instanceUpdate, UUID requestId) {
 
@@ -124,4 +125,11 @@ public class InstantiationController extends AbstractRestController implements A
 
         return ResponseEntity.ok().body(provider.deleteAutomationComposition(compositionId, instanceId));
     }
+
+    @Override
+    public ResponseEntity<Void> ompositionInstanceState(UUID compositionId, UUID instanceId,
+        @Valid AcInstanceStateUpdate body, UUID requestId) {
+        // TODO Auto-generated method stub
+        return null;
+    }
 }
diff --git a/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/stub/CommissioningControllerStub.java b/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/stub/CommissioningControllerStub.java
index f03cc4ecd..6c06d3c65 100644
--- a/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/stub/CommissioningControllerStub.java
+++ b/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/stub/CommissioningControllerStub.java
@@ -25,6 +25,7 @@ import javax.servlet.http.HttpServletRequest;
 import javax.validation.Valid;
 import org.onap.policy.clamp.acm.runtime.main.rest.gen.AutomationCompositionDefinitionApi;
 import org.onap.policy.clamp.acm.runtime.main.web.AbstractRestController;
+import org.onap.policy.clamp.models.acm.messages.rest.commissioning.AcTypeStateUpdate;
 import org.onap.policy.clamp.models.acm.messages.rest.commissioning.CommissioningResponse;
 import org.onap.policy.models.tosca.authorative.concepts.ToscaServiceTemplate;
 import org.onap.policy.models.tosca.authorative.concepts.ToscaServiceTemplates;
@@ -97,11 +98,17 @@ public class CommissioningControllerStub extends AbstractRestController
         return stubUtils.getResponse(pathToAllDefinitions, ToscaServiceTemplates.class, request, log);
     }
 
-    @Override
     public ResponseEntity<CommissioningResponse> updateCompositionDefinition(
             @PathVariable("compositionId") UUID compositionId,
             @Valid @RequestBody ToscaServiceTemplate body,
             @RequestHeader(value = "X-onap-RequestId", required = false) UUID xonaprequestid) {
         return stubUtils.getResponse(pathToPutUpdate, CommissioningResponse.class, request, log);
     }
+
+    @Override
+    public ResponseEntity<Void> compositionDefinitionPriming(UUID compositionId, UUID requestId,
+        AcTypeStateUpdate body) {
+        // TODO Auto-generated method stub
+        return null;
+    }
 }
diff --git a/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/stub/InstantiationControllerStub.java b/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/stub/InstantiationControllerStub.java
index 40152683d..c947f5a05 100644
--- a/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/stub/InstantiationControllerStub.java
+++ b/runtime-acm/src/main/java/org/onap/policy/clamp/acm/runtime/main/rest/stub/InstantiationControllerStub.java
@@ -27,6 +27,7 @@ import org.onap.policy.clamp.acm.runtime.main.rest.gen.AutomationCompositionInst
 import org.onap.policy.clamp.acm.runtime.main.web.AbstractRestController;
 import org.onap.policy.clamp.models.acm.concepts.AutomationComposition;
 import org.onap.policy.clamp.models.acm.concepts.AutomationCompositions;
+import org.onap.policy.clamp.models.acm.messages.rest.instantiation.AcInstanceStateUpdate;
 import org.onap.policy.clamp.models.acm.messages.rest.instantiation.InstantiationResponse;
 import org.onap.policy.clamp.models.acm.messages.rest.instantiation.InstantiationUpdate;
 import org.slf4j.Logger;
@@ -101,7 +102,6 @@ public class InstantiationControllerStub extends AbstractRestController implemen
         return stubUtils.getResponse(pathToAllIntances, AutomationCompositions.class, request, log);
     }
 
-    @Override
     public ResponseEntity<InstantiationResponse> updateCompositionInstance(
             UUID compositionId,
             UUID instanceId,
@@ -109,4 +109,11 @@ public class InstantiationControllerStub extends AbstractRestController implemen
             UUID xonaprequestid) {
         return stubUtils.getResponse(pathToResponseFile, InstantiationResponse.class, request, log);
     }
+
+    @Override
+    public ResponseEntity<Void> ompositionInstanceState(UUID compositionId, UUID instanceId,
+        @Valid AcInstanceStateUpdate body, UUID requestId) {
+        // TODO Auto-generated method stub
+        return null;
+    }
 }
\ No newline at end of file
diff --git a/runtime-acm/src/main/resources/openapi/openapi.yaml b/runtime-acm/src/main/resources/openapi/openapi.yaml
index 65d2c6b08..170e233c9 100644
--- a/runtime-acm/src/main/resources/openapi/openapi.yaml
+++ b/runtime-acm/src/main/resources/openapi/openapi.yaml
@@ -32,10 +32,396 @@ servers:
         default: onap/acm/v3
         description: This value is assigned by the service provider
 tags:
+- name: Participant Monitoring
+  description: Pariticipant Monitoring Controller, for monitoring of and requesting information from participants
 - name: Automation Composition Definition
-  description: Automation Composition Controller
+  description: Automation Composition Definition Controller, for definition and management of Automation Composition Types
+- name: Automation Composition Instance
+  description: Automation Composition Instance Controller, for definition and management of Automation Composition Instances
 
 paths:
+  /participants:
+    get:
+      tags:
+      - Participant Monitoring
+      summary: Query Particicpants
+      description: Query the participants that are registered on the ACM runtime
+      operationId: queryParticipants
+      parameters:
+      - name: name
+        in: query
+        required: false
+        description: Automation composition definition name. Regular expressions are supported for filtering. If
+          this parameter is not specified, all automation composition definitions are returned.
+        schema:
+          type: string
+      - name: version
+        in: query
+        required: false
+        description: Automation composition definition version. Regular expressions are supported for filtering. If this
+          parameter is not specified, all automation composition definitions that match the "name" filter are are returned.
+        schema:
+          type: string
+      - name: X-onap-RequestId
+        in: header
+        description: RequestID for http transaction
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        200:
+          description: OK, serialised array of instances of
+            [ParticipantInformation](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/ParticipantInformation.java)
+            that contains information on participants with their information and status. Each participant entry contains
+            a list of AC Element types on the participant. Each AC Element type entry contains a list of AC Element
+            instances on the Participant.
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ParticipantInformation'
+              example:
+                externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/getParticipantInformation.json'
+            application/yaml:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ParticipantInformation'
+              example:
+                externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/getParticipantInformation.yaml'
+        401:
+          description: Authentication Error, returns an instance of
+            [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleResponse'
+      security:
+      - basicAuth: []
+      x-interface info:
+        api-version: 1.0.0
+        last-mod-release: London
+    put:
+      tags:
+      - Participant Monitoring
+      summary: Order an immendiate Participant Report from all participants
+      description: Requests all participants to immediately generate a heartbeat report with their information and status
+        and the information and status of all their AC Element Types and Instances. The results are published on subsequent
+        GET REST requests on the "participants" endpoint.
+      operationId: orderAllParticiantsReport
+      parameters:
+      - name: X-onap-RequestId
+        in: header
+        description: RequestID for http transaction
+        schema:
+          type: string
+          format: uuid
+      responses:
+        202:
+          description: Accepted, the request has been accepted and forwarded to participants
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+        400:
+          description: Bad Request, returns an instance of
+            [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleResponse'
+        401:
+          description: Authentication Error, returns an instance of
+            [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleResponse'
+      security:
+      - basicAuth: []
+      x-interface info:
+        api-version: 1.0.0
+        last-mod-release: London
+      x-codegen-request-body-name: body
+  /participants/{participantId}:
+    get:
+      tags:
+      - Participant Monitoring
+      summary: Get details of the requested participant
+        definitions
+      description: Get details of the requested commissioned participant, returning all pariticipant details
+      operationId: getParticipant
+      parameters:
+      - name : participantId
+        in: path
+        description: The UUID of the participant to get
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - name: X-onap-RequestId
+        in: header
+        description: RequestID for http transaction
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        200:
+          description: Serialised instance of
+            [ParticipantInformation](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/ParticipantInformation.java)
+            that information on the participant with its information and status. The participant entry contains
+            a list of AC Element types on the participant. Each AC Element type entry contains a list of AC Element
+            instances on the Participant.
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ParticipantInformation'
+              example:
+                externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/getSingleParticipantInformation.json'
+            application/yaml:
+              schema:
+                $ref: '#/components/schemas/ToscaServiceTemplate'
+              example:
+                externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/getParticipantInformation.yaml'
+        401:
+          description: Authentication Error, returns an instance of
+            [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleResponse'
+        404:
+          description: Specified participant not found, returns an instance of
+            [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleResponse'
+      security:
+      - basicAuth: []
+      x-interface info:
+        api-version: 1.0.0
+        last-mod-release: London
+    put:
+      tags:
+      - Participant Monitoring
+      summary: Order an immendiate Participant Report from a participant
+      description: Requests the participants to immediately generate a heartbeat report with its information and status
+        and the information and status of all its AC Element Types and Instances. The results are published on subsequent
+        GET REST requests on the "participants" endpoint.
+      operationId: orderParticipantReport
+      parameters:
+      - name : participantId
+        in: path
+        description: The UUID of the participant to get
+        required: true
+        schema:
+          type: string
+          format: uuid
+      - name: X-onap-RequestId
+        in: header
+        required: true
+        description: RequestID for http transaction
+        schema:
+          type: string
+          format: uuid
+      responses:
+        202:
+          description: Accepted, the request has been accepted and forwarded to participants
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+        400:
+          description: Bad Request, returns an instance of
+            [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleResponse'
+        401:
+          description: Authentication Error, returns an instance of
+            [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleResponse'
+        404:
+          description: Specified participant not found, returns an instance of
+            [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
+          headers:
+            X-LatestVersion:
+              schema:
+                type: string
+            X-PatchVersion:
+              schema:
+                type: string
+            X-MinorVersion:
+              schema:
+                type: string
+            X-onap-RequestId:
+              schema:
+                type: string
+                format: uuid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleResponse'
+      security:
+      - basicAuth: []
+      x-interface info:
+        api-version: 1.0.0
+        last-mod-release: London
+      x-codegen-request-body-name: body
   /compositions:
     get:
       tags:
@@ -48,12 +434,14 @@ paths:
       parameters:
       - name: name
         in: query
+        required: false
         description: Automation composition definition name. Regular expressions are supported for filtering. If
           this parameter is not specified, all automation composition definitions are returned.
         schema:
           type: string
       - name: version
         in: query
+        required: false
         description: Automation composition definition version. Regular expressions are supported for filtering. If this
           parameter is not specified, all automation composition definitions that match the "name" filter are are returned.
         schema:
@@ -332,9 +720,10 @@ paths:
     put:
       tags:
       - Automation Composition Definition
-      summary: Update an automation composition definition
-      description: Updates an automation composition definition as described in the supplied automation composition defintion, returning the UUID of the automation composition definition updated by this request
-      operationId: updateCompositionDefinition
+      summary: Primes or deprimes an automation composition definition
+      description: Primes or deprimes an automation composition definition by sending the AC Element Types to participants and
+        getting participants to take responsibility for AC Element Types in this AC Type.
+      operationId: compositionDefinitionPriming
       parameters:
       - name : compositionId
         in: path
@@ -351,25 +740,22 @@ paths:
           format: uuid
       requestBody:
         description: Serialised instance of
-            [ToscaServiceTemplate](https://github.com/onap/policy-models/blob/master/models-tosca/src/main/java/org/onap/policy/models/tosca/authorative/concepts/ToscaServiceTemplate.java)
-          containing the changes to be made to the automation composition definition.
+            [AcTypeStateUpdate](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/commissioning/AcTypeStateUpdate.java)
+            which specifies the requested state change on the automation concept instance
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ToscaServiceTemplate'
+              $ref: '#/components/schemas/AcTypeStateUpdate'
             example:
-              externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putCompositionDefinitionUpdate.json'
+              externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putAcTypeStateUpdate.json'
           application/yaml:
             schema:
-              $ref: '#/components/schemas/ToscaServiceTemplate'
+              $ref: '#/components/schemas/AcTypeStateUpdate'
             example:
-              externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putCompositionDefinitionUpdate.yaml'
-        required: true
+              externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putAcTypeStateUpdate.yaml'
       responses:
-        200:
-          description: Serialised instance of
-            [CommissioningResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/commissioning/CommissioningResponse.java)
-            containing the UUID of the automation composition updated by this request
+        202:
+          description: Accepted, the request has been accepted and forwarded to participants
           headers:
             X-LatestVersion:
               schema:
@@ -384,19 +770,8 @@ paths:
               schema:
                 type: string
                 format: uuid
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CommissioningResponse'
-              example:
-                externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putCompositionDefinitionUpdateResponse.json'
-            application/yaml:
-              schema:
-                $ref: '#/components/schemas/CommissioningResponse'
-              example:
-                externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putCompositionDefinitionUpdateResponse.yaml'
-        401:
-          description: Authentication Error, returns an instance of
+        400:
+          description: Bad Request, returns an instance of
             [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
           headers:
             X-LatestVersion:
@@ -416,8 +791,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SimpleResponse'
-        404:
-          description: Specified automation composition definition not found, returns an instance of
+        401:
+          description: Authentication Error, returns an instance of
             [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
           headers:
             X-LatestVersion:
@@ -437,8 +812,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SimpleResponse'
-        400:
-          description: Bad Request, returns an instance of
+        404:
+          description: Specified automation composition definition not found, returns an instance of
             [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
           headers:
             X-LatestVersion:
@@ -937,9 +1312,11 @@ paths:
     put:
       tags:
       - Automation Composition Instance
-      summary: Update an automation composition instance
-      description: This request updates an automation composition instance. It may update instance properties or change the state of the automation composition instance
-      operationId: updateCompositionInstance
+      summary: Manage deployment and locking of an automation composition instance
+      description: This request manages deployment and locking of an automation composition instance. This endpoint can
+        order deployment and undeployment of an AC Instance to participants and order unlocking and locking of AC instances
+        on participants
+      operationId: ompositionInstanceState
       parameters:
       - name : compositionId
         in: path
@@ -963,25 +1340,23 @@ paths:
           format: uuid
       requestBody:
         description: Serialised instance of
-            [InstantiationUpdate](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/instantiation/InstantiationUpdate.java)
-            which specifies the update operation to be carried out on the automation concept instance
+            [AcInstanceStateUpdate](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/instantiation/AcInstanceStateUpdate.java)
+            which specifies the requested state change on the automation concept instance
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/InstantiationUpdate'
+              $ref: '#/components/schemas/AcInstanceStateUpdate'
             example:
-              externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putCompositionInstanceUpdate.json'
+              externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putAcInstanceStateUpdate.json'
           application/yaml:
             schema:
-              $ref: '#/components/schemas/InstantiationUpdate'
+              $ref: '#/components/schemas/AcInstanceStateUpdate'
             example:
-              externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putCompositionInstanceUpdate.yaml'
+              externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putAcInstanceStateUpdate.yaml'
         required: true
       responses:
-        200:
-          description: Serialised instance of
-            [InstantiationResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/instantiation/InstantiationResponse.java)
-            containing the UUID of the updated automation composition instance
+        202:
+          description: Accepted, the request has been accepted and forwarded to participants
           headers:
             X-LatestVersion:
               schema:
@@ -996,19 +1371,8 @@ paths:
               schema:
                 type: string
                 format: uuid
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/InstantiationResponse'
-              example:
-                externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putCompositionInstanceUpdateResponse.json'
-            application/yaml:
-              schema:
-                $ref: '#/components/schemas/InstantiationResponse'
-              example:
-                externalValue: 'https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/examples/putCompositionInstanceUpdateResponse.yaml'
-        401:
-          description: Authentication Error, returns an instance of
+        400:
+          description: Bad Request, returns an instance of
             [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
           headers:
             X-LatestVersion:
@@ -1028,8 +1392,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SimpleResponse'
-        404:
-          description: The specified automation composition instance was not found, returns an instance of
+        401:
+          description: Authentication Error, returns an instance of
             [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
           headers:
             X-LatestVersion:
@@ -1049,8 +1413,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SimpleResponse'
-        400:
-          description: Bad Request, returns an instance of
+        404:
+          description: The specified automation composition instance was not found, returns an instance of
             [SimpleResponse](https://github.com/onap/policy-clamp/blob/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/rest/SimpleResponse.java)
           headers:
             X-LatestVersion:
@@ -1208,6 +1572,9 @@ components:
       type: http
       scheme: basic
   schemas:
+    ParticipantInformation:
+      title: ParticipantInformation
+      type: object
     ToscaServiceTemplates:
       title: ToscaServiceTemplates
       type: object
@@ -1226,8 +1593,11 @@ components:
     CommissioningResponse:
       title: CommissioningResponse
       type: object
-    InstantiationUpdate:
-      title: InstantiationUpdate
+    AcTypeStateUpdate:
+      title: AcTypeStateUpdate
+      type: object
+    AcInstanceStateUpdate:
+      title: AcInstanceStateUpdate
       type: object
     InstantiationResponse:
       title: InstantiationResponse