Merge pull request #1112 from akeneo/CEX-721

CEX-721: Workflow Execution start endpoint documentation

Author: artggd

content/img/illustrations/illus--Workflowexecution.svg

@@ -538,6 +538,8 @@ UiExtensionWithoutRequired:
 
 Workflow:
   $ref: ./resources/workflows/definitions/workflow.yaml
+WorkflowExecution:
+  $ref: ./resources/workflows/definitions/workflow_execution.yaml
 WorkflowStepAssignee:
   $ref: ./resources/workflows/definitions/assignee.yaml
 WorkflowTask:

content/swagger/akeneo-web-api.json

@@ -211,6 +211,8 @@
   $ref: ./resources/workflows/routes/workflows.yaml
 /api/rest/v1/workflows/{uuid}:
   $ref: ./resources/workflows/routes/workflows_uuid.yaml
+/api/rest/v1/workflows/executions:
+  $ref: ./resources/workflows/routes/workflows_executions.yaml
 /api/rest/v1/workflows/steps/{uuid}/assignees:
   $ref: ./resources/workflows/routes/workflows_steps_uuid_assignees.yaml
 /api/rest/v1/workflows/tasks:

content/swagger/definitions.yaml

@@ -0,0 +1,51 @@
+type: array
+items:
+  type: object
+  required:
+    - workflow
+  x-validation-constraint: "Either product or product_model must be provided, but not both"
+  properties:
+    workflow:
+      type: object
+      required: [ "uuid" ]
+      properties:
+        uuid:
+          type: string
+          format: uuid
+          description: Workflow UUID
+          example: 6f37476a-04c2-46c0-b6d0-e18316959068
+    product:
+      type: object
+      required: [ "uuid" ]
+      properties:
+        uuid:
+          type: string
+          format: uuid
+          description: Product UUID
+          example: 87654321-4321-4321-4321-210987654321
+    product_model:
+      type: object
+      required: [ "code" ]
+      properties:
+        code:
+          type: string
+          description: Product model code
+          example: model_1234
+example: [
+  {
+    "workflow": {
+      "uuid": "6f37476a-04c2-46c0-b6d0-e18316959068"
+    },
+    "product": {
+      "uuid": "87654321-4321-4321-4321-210987654321"
+    }
+  },
+  {
+    "workflow": {
+      "uuid": "6f37476a-04c2-46c0-b6d0-e18316959068"
+    },
+    "product_model": {
+      "code": "model_1234"
+    }
+  }
+]

content/swagger/paths.yaml

@@ -0,0 +1,58 @@
+post:
+  summary: Execute workflow actions
+  operationId: "post_workflows_executions"
+  tags:
+    - Workflow execution
+  x-versions:
+    - "SaaS"
+  x-ee: true
+  description: This endpoint allows you to start workflow executions for products and/or product models. For each item in the array, you must provide either a product UUID or a product model code, but not both.
+  parameters:
+    - name: body
+      in: body
+      schema:
+        $ref: "#/definitions/WorkflowExecution"
+  responses:
+    201:
+      description: Created
+      x-details: All workflow executions were successfully started
+    207:
+      description: Multi-Status
+      x-details: Workflow executions started with some errors
+      schema:
+        type: object
+        properties:
+          code:
+            type: integer
+            description: HTTP status code
+            example: 207
+          message:
+            type: string
+            description: Status message
+            example: "Workflow executions started with some errors"
+          processed:
+            type: integer
+            description: Number of processed elements
+            example: 2
+          errors:
+            type: array
+            description: List of errors that occurred during processing
+            items:
+              type: object
+              properties:
+                index:
+                  type: integer
+                  description: Index of the element that caused an error
+                  example: 3
+                message:
+                  type: string
+                  description: Error message
+                  example: "Cannot start workflow execution: Workflow not found"
+    400:
+      $ref: "#/responses/400Error"
+    401:
+      $ref: "#/responses/401Error"
+    403:
+      $ref: "#/responses/403Error"
+    406:
+      $ref: "#/responses/406Error"

content/swagger/resources/workflows/definitions/workflow_execution.yaml

@@ -85,6 +85,7 @@ function determineCategory(tag){
         case 'Jobs':
             return 'Jobs';
         case 'Workflow':
+        case 'Workflow execution':
         case 'Workflow task':
             return 'Workflows';
         default: