Workflows define the various statuses of a content item, from the initial status to the Published status when the content item is available in the public API.
This documentation is based on the FoodCrunch use case. Please open the below link side by side to this page to understand the examples.
A workflow defines the various statuses of a content item from the initial status to the Published status. Workflows are typically used when contributors work together to create and publish content items and when they have different roles, such as Writer, Reviewer and Publisher. Workflows are very flexible and you can have an unlimited number of workflows per App.
A content workflow is represented as a graph of statuses (nodes) that are connected with transitions (edges). The status of a content item is defined by the workflow that is configured for the content schema.
- A status is a unique name that represents the status of your content item and has a color to identify them in the user interface.
- A transition defines the next possible statuses of your content item. A transition defines the next status and can have an optional expression and roles.
Workflows do not exist in older Squidex installations, but you can implement them with scripting.
Do the following steps to create a new workflow
- 1.Go to your App (1).
- 2.Click Settings (2) and then select Workflows (3).
- 3.Enter a name (4) for the workflow and click Add Workflow (5). This name is only used in this screen and can be changed later.
Adding a Workflow
Typically the list of workflows is empty, which means that the default workflow is applied to all the schemas. The default workflow has the same structure as the new workflow just created. If a schemas has no matching workflow, this default workflow is also applied.
To visualize the default workflow click on the gear icon (1)
next to the workflow name, then click the Visualize (2) tab. You should see the graphical representation of your workflow here.
Visualizing the default workflow
The default workflow has three statuses.
- Draft (3) is the initial status for each content item. The initial status is visualized by an arrow. From Draft, you can either change content item to "Published" or to "Archived".
- Archived (4) is a status that is used to mark deleted content items without actually deleting them. It is a soft delete. Archived content items cannot be updated. You cannot change from "Archived" to "Published" directly, you must change to "Draft" first.
- Published (5) is a special status that cannot be removed. Only content items whose status is set to "Published" are available in the normal API. If you do not need a workflow at all you can delete all other statuses.
The user interface is intuitive enough that it does not detailed instructions. But there are some special cases that need explaining.
The initial status is indicated with a small arrow icon (1). You can change this when you move the mouse over a status. Then the same arrow icon will pop up, which can be clicked to set the status.
The steps of colors can be changed. Just click to the colored circle next to each step to change the color.
Change the color of a status
You can assign one or more roles to a transition. When a role is assigned only contributors that have the correct role can move a content item to the target status that is defined by this transition. When no role is assigned all contributors can do that. This is restricted by permissions, so when a user has cannot update content items at all, the workflow does not change that.
Lets have a look to the following example:
A Use Case with a review status
Please note that the screenshot has been modified and some UI elements have been removed to make it more compact.
In our use case we have described three user groups:
- 1.Editors write content. When they are done, they move content item to the Ready status. They cannot review or publish content items.
- 2.Reviewers review content items, when they are ready. They either move the content item to Reviewed, when the review process is successful or back to "Draft" otherwise.
- 3.Publisher publish reviewed content items by moving these content items to "Published".
This workflow can be extended even more and multiple review steps can be implemented.
For example you have a schema for different kind of editorial content items such as articles, blog posts an news. This type of the item is defined a by a string field.
In this case we extend the example from the previous section where we use Roles.
A content item where the type field is set to News does not need a review and can be published directly. Articles need the review process and the previous rules will be applied.
When you design the Expression you have only access to the content data which is directly part of the content. For example when you have a relationship, only the IDs of the referenced items are stored in the content and not the content of the references itself.
The data has the same structure as it is also used for queries and for the API.
// More fields
The structure has been explained in detail the use case:
Workflows can be assigned to schemas. If no schema is assigned, this workflow handles all schemas where no other workflow is assigned for. Other schemas, that have no assigned workflow have an implicit default workflow with.
You have to pay attention that you do not assign the same schema to multiple workflows. This can happen when you have multiple workflows that have no assigned schemas
Multiple workflows with no schemas assigned
or when multiple workflows have the same schema assigned.
Multiple workflows for the same schema
In both cases you get a warning which should be resolved. You can save workflows and create and update content items as normal but it is not defined which workflow is used when a content item is updated. It can even change over time and the behavior is unpredictable.
You can prevent updates when a content item has a certain status. You can also define an optional Expression or Roles to restrict the updates only in some cases or for a subset of your contributors.
In the default workflow this is used to make "Archived" content items read-only, but you can also use this feature to prevent updates in the review process.