You can create a custom Item review workflow for your Item Bank using the Data API SET workflows endpoint. If you need to have more than one workflow enabled for your Item Bank, we recommended that you automatically attach Tags to Items created in different workflows and filter out the Items based on the the attached Tags between each instance of the workflow in use. These Tags can also be hidden from the UI to be transparent to your Authors.

Every workflow has an initial and a final state. By default, Items are created with the unpublished status in the initial workflow state. The status is automatically set to published once the Item is transitioned to the final workflow state. The Item status is not visible in the list view when workflow is enabled, and instead Authors will see the workflow state of the Items. Items can be archived from whatever workflow state they are in, and when unarchived, they would set to the workflow state and status they were in before they were archived.

Creating a custom Item review workflow

You can customize the workflow to be set for your Item Bank using the Data API SET workflows endpoint. Every workflow and states in the workflow need to have a reference against which they are identified. The workflow reference is required during configuration for the Author API, and the workflows individual state references are used for filtering Items with specific workflow states in the Author API. They are also used to define the possible transitions while being set through the Data API.

The organisation_id parameter is optional and the workflow will be created in the default Item bank for your consumer. This can be used when setting up workflow for your additional Item banks with write access enabled.

Example workflow

Payload used for the example workflow :

{
  "reference": "Default workflow",
  "initial_state_reference": "DRAFT",
  "final_state_reference": "APPROVED",
  "description": "Default workflow description",
  "workflow_states": [
   {
    "reference": "DRAFT",
    "description": "DRAFT STATE",
    "label": "DRAFT",
    "workflow_transitions": [
     {
    "to_state_reference": "REVIEW",
    "display_order": 1
     },
     {
    "to_state_reference": "BLOCKED",
    "display_order": 2
     }
    ]
   },
   {
    "reference": "BLOCKED",
    "description": "BLOCKED STATE",
    "label": "BLOCKED",
    "workflow_transitions": [
     {
    "to_state_reference": "REVIEW",
    "display_order": 1
     },
     {
    "to_state_reference": "REWORK",
    "display_order": 2
     },
     {
    "to_state_reference": "DRAFT",
    "display_order": 3
     }
    ]
   },
   {
    "reference": "REWORK",
    "description": "REWORK STATE",
    "label": "REWORK",
    "workflow_transitions": [
     {
    "to_state_reference": "REVIEW",
    "display_order": 1
     },
     {
    "to_state_reference": "BLOCKED",
    "display_order": 2
     }
    ]
   },
   {
    "reference": "REVIEW",
    "description": "REVIEW STATE",
    "label": "REVIEW",
    "workflow_transitions": [
     {
    "to_state_reference": "APPROVED",
    "display_order": 1
     },
     {
    "to_state_reference": "REWORK",
    "display_order": 2
     }
    ]
   },
   {
    "reference": "APPROVED",
    "description": "APPROVED STATE",
    "label": "APPROVED",
    "workflow_transitions": [
     {
    "to_state_reference": "REVIEW",
    "display_order": 1
     }
    ]
   }
  ]
}

Workflow states are defined in the workflow_states array, and will contain the reference, description, label and the possible workflow_transitions for each of the workflow states. The label is used to display the workflow state in Author API's Item list mode and in Item edit mode when the workflow is configured. Only the states to which an Item can transition to from the current workflow state can be defined in the workflow_transitions object along with the display order to be shown in Author API. The description parameter is to be used for documentation purposes only and can be helpful to understand your custom workflow.

Modifying the Item review workflow

You can modify your existing workflow to add in additional workflow states and to remove or modify existing states using the Data API SET workflows endpoint passing it the reference of the workflow to be modified. However you will not be able to modify the workflow if there are Items in any of the workflow's states.

Fetching the Item review workflow

The workflow configuration saved against your Item bank be fetched using the Data API GET workflows endpoint.