Lesson 3 - Transitions

Overview

Transitions are the paths between states.

If you tested the workflow we made in Lesson 2 - States, you will have noticed that every state could transition to every other state. That's the default behavior of states – unless you specify otherwise.

Before you start this lesson, transition to the Editing state of your workflow via the workflow popup.

Submit transition

We'll start with the transition from the Editing state to the Review state.

When we're in the Editing state, we only want a single choice – go to the Review state. For that, we need a submit transition.

Edit your workflow, as shown in the previous lesson, and add submit=Review parameter to the Editing state.

{workflow:name=Simple Content Production Process}
   {state:Editing|taskable=true|submit=Review}
   {state}
   {state:Review|taskable=true}
   {state}
   {state:Published|final=true|taskable=true}
   {state}
{workflow}

We put a | (a pipe character – that vertical, sometimes split, line near the Enter key on your keyboard) between the taskable=true parameter and the submit=Review parameter.

On the page the workflow popup displays the single destination user choice as the destination state.

You can also add this using workflow builder to edit the transitions for the Editing state.

If you wanted to add a condition for the transition from the Editing state to the Review state to be active, for example, you only want the transition to be available if a specific label is present on the page. For this, you can use a select transition with a single destination state and add this as a condition for the transition.

This generates the following markup notation for the Editing state and the transition.

{state:Editing|taskable=true}
  {state-selection:states=Review|haslabel=projecta}
{state}

If the specified label projecta, is not added to the page, the workflow popup does not display any transition option.

What are parameters?

Most Macros can have settings, called parameters.

Usually, parameters look like name=value – for example, taskable=true. However, some macros support a special Unnamed first parameter that only needs the value part. You can see both types in the markup above.

Between the macro name, and the first parameter – regardless of whether it's a named or unnamed parameter – there must always be a colon ":".

And, between each parameter, there must be a pipe "|".

Review transitions

In our Review state, we want two possible transitions:

If the content is approved, we want to go to the Publish state
If the content is rejected, we want to go back to the Editing state

These must be used with an approval added to the state

name the approval Review

Let's make those changes to our workflow:

{workflow:name=Simple Content Production Process}
   {state:Editing|taskable=true|submit=Review}
   {state}
   {state:Review|taskable=true|approved=Published|rejected=Editing}
   {state}
   {state:Published|final=true|taskable=true}
   {state}
{workflow}

Published transition

Once content is Published, we generally leave it in that state. However, what happens if someone edits it?

We can use the updated transition to automatically move to another state – like the Editing state – if someone edits the content. Here's our updated workflow:

In workflow builder, add an Updated transition to the the Published state.

On the page with the added workflow, no transitions are displayed when the page is in the Published state.

Test it

Now, try testing the transitions in your workflow.

Did you notice that there was only one option in the Editing state – to transition to the Review state, but not the Published state?

And when you transitioned to the Review state, did you get stuck?

It's time for the next lesson.

Lesson 4 - Reviews ›

Lesson 4 - Reviews ›