Lesson 1 - The Basic Workflow Tutorial

This tutorial helps you to learn how to create workflows using the workflow markup. If you are evaluating the plugin, use the Workflow templates provided with plugin.

This tutorial focuses on a central need of many Content Management Scenarios: that content should be visible to only those people involved in the workflow until that content has been seen and approved by relevant parties.

The example below is based on the Editor and staff approval workflow already provided as a workflow template.

Specification

We start by defining four "states" that any given page can be in: Draft, Ready, Reviewed and Published.

When the Author creates a document, it is considered Draft.
Once the Author is ready, he/she submits the page for Review
After a Reviewer approves, the document is considered Reviewed and is ready to publish. The final step is the Editor in Chief's approval.
On Editor in Chief's approval the document considered Published.

These are all "transitions"; they define how the work flows between those states. In addition to the forward flows, there are some that lead backwards:

If the Reviewer rejects the document, then the state has to change to Draft.
If the Editor in Chief rejects the document, then the state changes to Ready.
If a page is edited after it has been published, then we want the state to change to Ready.

Creating the workflow

You have to options to create the new workflow:

Using the workflow macro

Like most things in Confluence, a workflow is defined using Confluence Macros.

A workflow is defined in a definition page using the {workflow} macro. It contains a collection of states and approvals. Later, we will add triggers .

Using the states macro

The {state} macro defines the states.

Each state defines:

a name
what approvals need to be completed to transition from this state
the next state after the current user approves or rejects

The initial ad hoc workflow created already contains our initial states:

{workflow:name=Basic Workflow}
    {state:Draft|taskable=true}
    {state}
    {state:Ready|taskable=true}
    {state}
    {state:Reviewed|taskable=true}
    {state}
    {state:Published|taskable=true}
    {state}
{workflow}

The states include the taskable=true parameters because we created the workflow as an ad hoc workflow; however, we are going to override the entire workflow.

Defining the transitions

We need to define the following transitions:

Submitting the page from Draft to Ready
Changing the state from Ready to Reviewed when a Review approval is given, or back to Draft if rejected
Changing the state from Reviewed to Published when an Editor in Chief approval is given, or back to Ready if rejected
Changing the state from Published to Ready when the page is updated

{workflow:name=Basic Workflow}
    {state:Draft|submit=Ready}
    {state}
    {state:Ready|approved=Reviewed|rejected=Draft}
        {approval:Review}
    {state}
    {state:Reviewed|approved=Published|rejected=Ready}
        {approval:Editor in Chief}
    {state}
    {state:Published|final=true|updated=Ready}
    {state}
{workflow}

When the system reaches the Published state, we apply the Final Marker to the version of the page. Usually non-contributors only see final versions. See [What does Final mean?]

Save the workflow

You can save the workflow now, and if you have Graphviz Plugin installed, you will be able to see the workflow's chart:

When you save the workflow, the {workflow} macro line adds a couple of parameters such as name and space.

Trying our State Changes

Let's try out the workflow.

The page is shown in its initial Draft state:

From there you can submit the page by clicking in the Draft link:

You can now transition the page towards the Published state with each approval. You can view the current state by hovering over the Page Activity link:

Now continue to: Lesson 2 - Specifying who can action the approvals

Versions

Support