Adds configurable workflow support to the CMS, with a GUI for creating custom workflow definitions.
Note: The SilverStripe 2.4 version of the module is available from the ss24 branch of the repository.
A module that provides an action / transition approach to workflow, where a single workflow process is split into multiple configurable states (Actions) with multiple possible transitions between the actions.
The workflow extension is automatically applied to the
SiteTree class (if available). In order to apply workflow to other classes (e.g.
MyObject), you need
to apply it to both the model class and the controller
which is used for editing it. Here's an example for
which is managed through a
:::yml MyObject: extensions: - WorkflowApplicable MyObjectAdmin: extensions: - AdvancedWorkflowExtension
We strongly recommend also setting the
NotifyUsersWorkflowAction configuration parameter
to true on new projects. This configuration will achieve this:
:::yml NotifyUsersWorkflowAction: whitelist_template_variables: true
See the Security section below for more details.
In its most basic sense, workflow means that new content or changes to existing content, need to go through an approval process before they're able to be published to the live site. This works by limiting access to certain parts of the workflow to certain users, using the standard SilverStripe CMS Security admin.
The CMS can have an unlimited number of workflows created and running within it, but only one workflow can be attached to a content-object (e.g a "Page") at any one time.
Each workflow comprises a number of definable "Actions" such as "Publish" and "Reject" and each action may have any number of "Transitions" leading out from it that connect one action to another.
Users and groups can have individual permissions assigned to them on Transitions, which gives workflow administrators fine-grained control over the content-actions allowed to be performed. Each transition the current CMS user has permission to enact, will be available to them as a button on each item of content assigned to them.
Since the actual workflows can vary greatly for each site, there's no default
workflow set up. You'll need to configure it through the
admin/workflows admin interface.
Here, we'll create a simple two step workflow with the following features:
First of all, login to the CMS as an administrator. Ensure you have "Authors", "Editors" and "Managers" groups created with a single user linked to each group (in the standard "Security" admin). Assign the five "Advanced Workflow" permissions to each group.
For more details about permissions, see the "Workflow permissions" section below.
The easiest way to get up and running with workflow is to use a "workflow template" in order to create your definition. To find out the detailed steps of creating and customizing actions and transitions, see to "Customizing Actions and Transitions" instead.
Switch to the "Workflow" section in the CMS menu. Create a new workflow there through the "Add Workflow Definition" button. Choose "Review and Approve" from the template dropown. After saving the item, assign it to the "Editors" group
Now continue to "Assigning Workflow to Content" below.
In the Workflow CMS admin-area, authorised users are able to export a WorkflowDefinition from one SilverStripe installation, and import it into another.
To export a workflow; from the table of workflows in the Workflow CMS admin-area, select the 'download' icon located to the right of the 'edit' and 'delete' icons.
You should be prompted to download a file which you should save to your local computer.
To import, simply login to another SilverStripe installation and navigate to the Workflow Admin of that CMS. You should see an "Import" heading at the bottom of the central CMS pane with a "Browse" button below that.
Select the "Browse" button and locate the downloaded file in the your computer's file-browser that will automatically appear, then select the "Import Definition" button. That's it!
Because users and groups can be related to Workflow Actions and Transitions, these associations are also exported. However, these relations will only be made at the import stage if the same Groups and/or Users also exist in the target CMS, otherwise you will need to manually re-create the users and groups and re-assign them to the imported workflow.
At this point your new workflow isn't much use if your existing CMS content isn't aware of it. Select the "Pages" left-hand menu item, create new page called "Workflow Test", then select the "Settings" tab and then the "Workflow" tab. Note: the default workflow selection is "Inherit from parent" so you can assign a workflow to a parent page and each child page will use that workflow without any further configuration.
However, you might want one specific page to use a different workflow than its parent, so in this case select the "My New Workflow" option from the drop-down menu and select "Save draft" or "Save and Publish" as usual.
Your new workflow has now been associated with your new page. If you select the "Content" tab, you should notice a new button available labeled as per your first workflow action, which should be "Apply for approval" - if you've followed the instructions above.
Logout of the CMS and log back in again as your "Author" user. Navigate to the page you created in the previous step, enter some text into the "Content" area and then select the "Save Draft" button. Once the page had reloaded, ''then'' select the "Apply for approval" button, now depending on users and groups assigned to your transitions and content-permissions, the content may now be locked from further editing until it has progressed through the workflow instance to the final Manager's "Publish item" action.
Notice that if you select the "Workflows" left-hand navigation menu item once again, you should see a list of your "Submitted items". At this point this should be showing a single entry for the "Workflow Test" page. You can refer back to this list and observe the "Current action" column update as your changes progress though the workflow.
Depending on how you configured the email address for the Editor user you created in the "Security" admin before starting, an email should have been received in the Editor's email inbox alerting them that some new content is available for review/approval by them.
Now logout of the CMS and log back in again as a user from the "Editors" group. Select the "Workflows" left-hand navigation menu item, and notice that you have a similar list to before, but this one is entitled "Your pending items". These are the workflow changes automatically assigned to you that are now awaiting your attention.
Click anywhere on the table row and in the "Next Action" drop-down menu, make your choice as Editor, then select "Save". You can also see a log of the actions. Note: You are also able to select the blue content-title text to view the page itself within the CMS and manually review the changes before committing to accepting or rejecting them. If you now go back to the "Workflow" admin, you'll notice that the items that was in the "Your Pending Items" list, is no longer there, as the action is now with the users of the "Managers" group.
Logout of the CMS, and login as your "Manager" user. Select the "Workflows" left-hand navigation menu item, and notice that there is a similar list to before entitled "Your pending items", again with the "Workflow Test" page being the only item. Click on this item and make your selection as manager, and then select the "Save" button.
If you were to go and check the edit screen for this page, you'll notice now that having gone through the full workflow, that the action button at the bottom, now shows "Apply for approval" once again, and logging back-in as an Author, this user is now able to make further changes.
This section describes the different permission that can be assigned to a user, group or role.
A user with this permission can choose which workflow that should be used for an item. E.g. for a page this permission will allow the user to change workflow in a drop down under the "Page > Settings > Workflow" tab.
A user with this permission can create and change workflow definitions.
A user with this permission can delete:
I.e. if a user needs to completely stop and delete an active workflow, they would need this permission.
A user with this permission can reassign active workflows to different users and groups.
A user with this permission can view active workflows via the workflows admin panel.
This add-on functionality allows you to embargo some content changes to only appear as published at some future date. To enable it,
:::yml SiteTree: extensions: - WorkflowEmbargoExpiryExtension
Make sure the QueuedJobs module is installed and configured correctly. You should have a cronjob similar to the following in place, running as the webserver user.
*/1 * * * * cd && sudo -u www php /var/www/framework/cli-script.php dev/tasks/ProcessJobQueueTask
It also allows for an optional subsequent expiry date. Note: Changes to these dates also constitute modifications to the content and as such are subject to the same workflow approval processes, where a particular workflow instance is in effect. The embargo export functionality can also be used independently of any workflow.
The workflow engine can send out email reminders if a workflow has been open for longer than a couple of days (configurable in each "Workflow Definition" through the CMS).
Periodically run the Workflow Reminder Task by adding a task like this one to the crontab:
# Check every minute if someone needs to be reminded about pending workflows */1 * * * * cd /var/www && sudo -u www ./sapphire/sake dev/tasks/WorkflowReminderTask
This is an example only. The key is to run the task as the same user as the web server.
You can run the task manually for testing by visiting the
/dev/tasks/WorkflowReminderTask URL of your site.
Depending on the specific permissions content authors have, authors may only have the ability to create or edit content and to request publication, but not to actually publish content - making it publicly viewable - themselves.
Depending on how your workflow is setup, users and/or groups configured with "approval" permissions will be alerted via email and be able to login to the CMS and see your page as a pending approval request when they view the workflow admin. The publisher will then need to review your request and if happy, will likely publish it.
Depending on the setup of workflow, publishers may receive an e-mail when authors have requested publication. Publishers then select the 'Workflow' navigation item to view a report of pending items and by selecting one form the list, be able to access the approval step. In the following screen, the drop-down menu will display the next approval step based on the workflow for this page. Publishers are also able to enter in comments here, detailing their approval or cancel/deny the approval if necessary.
Sometimes an action will have a single transition from itself to the next action; when the workflow begins execution, these actions are executed immediately one after another. An example of this might be when you want to assign a user to the workflow, then notify them immediately; the "Assign" action will have a single transition to the "Notify" action.
If you want the user to make an explicit choice about which path of the workflow to move to after a certain action, there should be multiple transitions created going out from that action. Continuing the above flow; after Notifying users, you might want them to make a decision as to whether to "Approve" or "Reject" the item; therefore, from the Notify action, there may be two transitions:
1). The Approve transition that leads to the approval and publication actions. 2). The Reject transition that leads to the cancel action.
The name given to a transition appears on the "Workflow Actions" tab of a content item when a content author needs to make a decision.
Each action may have an arbitrary number of outbound transitions, and transitions can loop around back to earlier parts of the workflow too!
Initially we created a two-step workflow from a "workflow template". The workflow system is very powerful, so we'll run you through creating the same setup manually. That's a good way to learn the nuts and bolts of how things fit together, and will enable you to customize your workflow to your needs.
We assume you've got users and groups set up already. Now, wwitch to the "Workflow" section in the CMS menu. Create a new workflow there through the "Add Workflow Definition" button. Call it "Two-step workflow" for now. After saving the item, assign it to the "Editors" group
Okay, now we need to join up these actions using transitions, so that users can make the appropriate choices.
NotifyUsersWorkflowAction workflow action has a configuration parameter,
Currently this variable defaults to false in order to retain backwards compatibility. In a future major release it will
be changed to default to true.
Setting this configuration variable to true will limit template variables available in the email template sent as part of the notify users action to a known-safe whitelist. When it is false, the template may reference any accessible parameter. As this template is editable in the CMS, whitelisting these parameters ensures CMS admins can not bypass data access restrictions.
Translations of the natural language strings are managed through a third party translation interface, transifex.com. Newly added strings will be periodically uploaded there for translation, and any new translations will be merged back to the project source code.
Please use https://www.transifex.com/projects/p/silverstripe-advancedworkflow to contribute translations, rather than sending pull requests with YAML files.