Workflow Definitions

Workflows definitions allow you to configure a pre-defined process for entries. Each workflow definition describes the schema for its workflows by a sequence of workflow steps which the executed workflows undergo.

Limitations

A workflow definition can define up to 20 steps. Defining more than 20 steps will result in a validation error.

The current maximum limit for workflow definitions is 20. If you lose access to the workflow API due to a price and package downgrade we will ensure that you can delete and complete existing workflows. An overview for our pricing and packaging can be found here.

Workflow definition schema

Besides the sequence of workflow steps, there are multiple properties to specify how workflows behave.

Field	Type	Required	Description
name	String	true	Name of the workflow definition
description	String	false	Explaining notes, e.g. a description of the use case
appliesTo	Array[Object] *	false	Target entries for which workflows of this definition can be used.
flowType	String	false	Can be `no_restriction` (default) or `strict_neighbor`. See the following paragraphs for more guidance.
startOnEntityCreation	Boolean	false	Automatically start a workflow on targeted entries when they are created (default: false). See the following paragraphs for more guidance.
steps	Array[Object]	false	Ordered list of steps which a workflow undergoes. The shape of a step is described in a following chapter.
sys	Sys **	true	System resource properties

* The items in the list appliesTo must match the following shape:

{ linkType: "Entry", type: "Link", validations: [{ linkContentType: ["contentTypeA", "contentTypeB"] }] }

It is recommended to have only one item in appliesTo as well as only one item in validations. If you want to address multiple content types, you can do so by mentioning multiple within the list at linkContentType.

** In addition to the common sys properties, a workflow definition has the following extra sys properties

Field	Type	Description
isLocked	Boolean	If the set up of permission rules was incomplete, the definition is marked as locked until it is saved again.
lockReason	string	Provides context about why the last save request wasn’t successful.

The flow type of a workflow definition

The property flowType controls to which step a user can move a workflow. It supports the follow two modes:

no_restriction: Apply no restrictions when moving a workflow to another step.
strict_neighbor: Enforce non-admin users to only move to the previous or the following step. The workflow can only be marked as ‘complete’ upon reaching the last step.

Automatically start workflows

The property startOnEntityCreation will automatically start a workflow for newly created targeted entries. Each time you create an entry of a content type configured for this workflow definition, the workflow will start automatically. However, this does not mean that workflows are started for entries that were already created before setting this property to true.

Assign multiple workflows to the same content type(s)

You can choose to configure multiple workflows for the same content type. This allows different teams working on the same content type to use dedicated workflows for their own review processes and governance.

Workflow step schema

A step within a workflow definition is described by the following properties.

Field	Type	Required	Description
id	String	true *	Internally defined ID
name	String	true	Name of the workflow step
description	String	false	Explaining note
annotations	Array[String]	false	List of meta tags. To render a color in the Contentful UI, add a string with the shape `cf-color-1` (allowed digits: 1-6).
permissions	Array[Object]	false	Allow or deny actions for selected users when a workflow is in this step.
actions	Array[Object]	false	Automated actions that are triggered when a workflow reaches this step.

* When leaving out the id in a POST/ PUT request for a workflow definition, you create a new step at that position in the list. When you define it (in a PUT request), you thereby update the existing step with that id.

Workflow step permission schema

In addition to the permission defined by a users role, a workflow step can restrict or grant permissions for selected users or teams. The permissions can only apply to a single active step in a workflow. The user restrictions in step permissions do not apply to organization or space admins. One permission must provide the following properties:

Field	Type	Required	Description
type	String	true	Can be `entity_permission` or `workflow_permission`. *
configuration.effect	String	true	Can be `allow` or `deny`.
configuration.action	String	true	Can be `edit` or `publish`. Publishing is only available for entity permissions (see `type`).
configuration.actors	String \| Array[Link]	true	Can be `all` or a list of user/ team links. Defines who is targeted by this permission rule.

* There are two supported types for targeted resources:

workflow_permission: Use this together with the action being edit to explicitly allow or deny who can move the workflow to another step.
entity_permission: Grant or restrict permission to edit or publish the entry on which the workflow is being executed.

Workflow step action schema

When a workflow reaches a step, it will automatically trigger the actions defined for this step. Those actions can be one of the following three:

Send an email to a set of users and teams. Additionally, you can also use any valid email address. The email notifies about the workflow being moved to this step. So far, the template is fixed and cannot be changed. There may be only one email action per step.
Create an entry task with a customisable message and assign it one user or team. Optionally, you can define a due date. Please note that you need to have the tasks app installed. You can define up to three task actions per step.
Send a custom message via Slack to a selected (public) channel about the workflow being moved to another step. Please note that you need to have the Slack app installed to use its app action. There may be only one Slack action per step.

Depending on the type, an action is defined by the following properties:

Field	Type	Required	Description
type	String	true	Can be `email`, `task` or `app` (for Slack).
configuration.recipients	Array[Link \| String]	if type is `email`	Recipients of the sent out email.
configuration.assignee	Link	if type is `task`	Assignee (user or team) of the created task.
configuration.body	String	if type is `task`	Text of the created task.
configuration.dueDate	Number	false	Days to add to the current timestamp to calculate the due date.
appId	String	if type is `app`	ID of the installed Slack app.
appActionId	String	if type is `app`	ID of the installed Slack app action.
configuration.body	Object	false	Optional payload for the Slack app action. May be defined when the `type` equals `app`.