Workflows
This documentation is based on the FoodCrunch use case. Please follow the link and open it side by side to this page to understand the examples.
A workflow defines the different 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 the contributors have different roles, such as Writer, Reviewer and Publisher. They 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
Go to your App.
Go to the app settings.
Go to the workflow settings of your App.
Enter a new name for your workflow. This name is only used in this screen and can be changed later.
Just press the button to create a new workflow with a default setup.
Typically your list of workflows is empty, which means that the default workflow is applied to all your schemas. The default workflow has the same structure as the new workflow that you just created. If a schemas has no matching workflow, this default workflow is also applied.
If you go to the Visualize (1) tab you see a graphical representation of your workflow:
(2) Draft is the initial status for each content item. The initial status is visualized by an arrow. From Draft you can either move a content item to "Published" or to "Archived".
(3) Archived 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. From "Archived" you cannot go to "Published" immediately, you always have to go to "Draft" first.
(4) Published is a special status that cannot be removed. Only content items where the 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.
Hopefully the user interface is good enough that you do not need detailed instructions. But there are some special cases that needs explanation.
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.
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:
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:
Editors write content. When they are done, they move content item to the Ready status. They cannot review or publish content items.
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.
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.
Workflows can be combined with Permissions to restrict who can create content items.
You can write an Javascript expression. This expressions is evaluated each time a content is updated to evaluate whether a transitions to another status is possible.
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.
{"data": {// More fields"type": {"iv": "News"}}}
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
or when multiple workflows have the same schema assigned.
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.
