Home

Workflow FAQ

Getting started

Once you have downloaded the module, unpack it into the (sitedir)/advancedworkflow directory (it will complain if it isn't!).

Add the WorkflowApplicable extension to the classes you want managed by workflow. This is likely to be SiteTree objects, so add in

DataObject::add_extension('SiteTree', 'WorkflowApplicable');

For SilverStripe 3, you won't need do do any configuration as the module contains the modifications to the _config.php file. Check the (sitedir)/advancedworkflow/_config.php file for the "WorkflowApplicable" line before editing your main _config.php file. If the "WorkflowApplicable" line is in both _config.php files SilverStripe will throw an error.

Run dev/build by opening http://(yoursite)/dev/build in your browser to get everything initialised. You may need to run dev/build more than once to get everything working (keep running it until there are no more green lines in the output of the page).

Once you log into the backend of the CMS, you'll see a "Workflows" section menu at the top of the screen. If you navigate to a page object, you should now see a "Workflow" tab along the top list of page tabs next to Content, Behaviour etc; if you look at the tab, you'll see an "Applied Workflow" and an "Effective Workflow" field. For now this will just be set to "Inherit from Parent", with no other options in the list.

Before creating a workflow, it's worth reviewing the terminology being used

• Workflow Definition This is the description of all the steps and transitions of a single workflow, and is what gets applied to pages within the CMS. These are managed in the "Workflows" section of the CMS.
• Workflow Instance When a user wants to publish a page, instead of clicking the 'publish' button, they instead start a workflow, or more specifically, an instance of the workflow definition that is applied to the page. This "instance" contains all the relevant data (eg user choices, comments, etc) for the running workflow.
• Workflow Action These describe a single action that occurs in each step of the workflow. Each bit of logic of a workflow is encapsulated in an action, such as
  • Assigning users
  • Publishing a page
  • Sending notifications
• Workflow Transition A transition is a pathway between two actions, and define how a workflow proceeds.
  • Sometimes, an action will have a single transition from it to the next action; when the workflow executes, these actions will be 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 down after a certain action occurs, there should be multiple transitions created going out from that workflow action. Continuing the above flow, after Notifying users, you want them to make a decision as to whether to Approve or Reject the item; therefore, from the Notify action, there are TWO transitions; the Approve transition that leads to the approval and publication actions, and the Reject transition that leads to the cancel action.
  • The name given to a transition is what appears on the Workflow Actions tab of a content item when the content author needs to make a decision
  • You can have an arbitrary number of outbound transitions, and transitions can loop around back to earlier parts of the workflow too!

Creating a workflow

We're going to create a simple two step workflow that

• Assigns to the editors group for initial approval
• Notifies the editors of the new workflow task
• On approval, assigns to the web manager group for final approval
• Notifies the web managers of a new workflow task
• On approval, publishes the item
• On rejection, cancels the workflow

Before starting, make sure that the "Editors" and "Managers" groups exist in the system

Along the top section menus, click the "Workflows" option. We'll now create our workflow definition; first, we'll define all the actions, then join them up with transitions.

• On the left side of the screen, there will be a "Create" button next to "Workflow Definition". Click this now, and give the title "2 step workflow", clicking "Save" afterwards.
• Click "2 step workflow" in the left tree. A dropdown appears above the tree - select "Assign Users To Workflow Action" and click Create
• Change the title to "Apply for approval" - the first workflow action's title is used for the apply button in the UI
• In the "Groups" dropdown, select the "Managers" group, then click "Save"
• Create another action, this time selecting "Notify Users Workflow Action". Name it something like "Notify Editors". Enter in a subject, from address and template. To link to the item in the CMS, use $Context.CMSLink (note: advanced email templates will be discussed further on). Click Save
• Create the "Simple Approval Workflow Action", and give it the title "Editor Approval". Note: in a simple workflow such as this, the approval action doesn't actually do anything! However, it's good practice to have it as it provides a clear point of reference of where approval happens. In a more complex workflow, you might use a Counting Approval action to do things like count the number of people who have approved
• Now, for the second step; create another "Assign Users To Workflow Action", and name this one "Assign Managers". Select the managers group from the "Groups" dropdown.
• Create a new "Notify Users Workflow Action", and name it "Notify Managers". Fill in the details and click save
• Create a new "Simple Approval Workflow Action" and name it "Manager Approval", clicking save again
• Create a "Publish Item Workflow Action" and call it "Publish item", clicking save
• Create a "Cancel Workflow Action", call it "Cancel" and click save

Okay, now we need to join these all up so that users can make appropriate choices!

• Click the "Apply for approval" action in the tree. You should now have "Workflow Transition" appear above the tree, along with a "Create" button. Create the transition, give it the title of "Send Notification", and select "Notify Editors" as the "Next Action". Click the "Add" button to create the transition
• Click the "Notify Editors" action in the tree, and create a new transition. Call this one "Wait for approval" and select "Editor Approval" as the "Next Action".
• Select the "Editor Approval" action and create a new Transition. Call this one "Approve" and select "Assign Managers" as the "Next Action".
• WAAAIITTTT. Create ANOTHER transition for the "Editor Approval" action. Call this one "Reject" and select "Cancel" as the "Next Action". You've just created your first decision point
• Repeat the above steps to create the appropriate transitions between the remaining actions.

Applying the workflow

• Navigate back to a page. Click the "Workflow" tab, and select your newly created workflow.
• You should now have an "Apply for approval" button down the bottom (if you can still see the publish buttons, that's probably because you're logged in as an admin!)
• Click the "Apply for approval" button; you should see that the 'Apply' button disappears, and an "Update workflow" button appears, as well as a "Workflow Actions" tab.
• On the Workflow Actions tab, you should see that it's currently on the "Editor Approval". Select your choice of transition from the dropdown, and click "Update workflow"
• Update the workflow until it's finished (you'll see the "Apply" button reappear, and the "Workflow Actions" tab will disappear).
• If you look now on the Workflow tab, you'll see the log of the previously executed workflow