State expiry dates

Overview

The {state} macro can have a duedate specified to set its expiry date.

This is useful in a number of circumstances – for example, published content might need a periodical review to make sure it doesn't become outdated.

Upon expiry, you can use the expired parameter to transition to another state, or use the stateexpired and stateexpiryupdated events to trigger some actions.

In this example, we'll look at how to set the expiry date, how to transition on expiry, and how to make the expiry date editable.

Specific date

In this example we'll set a specific date, which must be in the format: YYYY-MM-DD HH:mm

{workflow:name=Specific date}
   {state:Already expired|duedate=2020-01-20 12:00|expired=Old}
   {state}
   {state:Old}
   {state}
{workflow}

Note: The time zone is determined by the Java Runtime Environment in which your Confluence server or datacenter is running.

(Will that workflow ever transition to the Old state? Yes, as the workflows background processor will find all pages that have expired but not yet triggered an expiry event.)

Durations (ISO 8601)

Another way to set the duedate is to specify a duration, rather than a date.

When a duration is set, the actual expiry date is automatically calculated at the moment when the workflow enters the state:

Actual expiry date = Date when state was entered + Duration

The duration is specified by a code starting with "P" (for Period) followed by codes for the number of Years, Months, Weeks and Days, or any combination of those.

For example, a Period of 2 Weeks and 1 Day (a total of 15 days) would look like: P2W1D.

The result looks like this:

If the 15 days state remains active for 15 days (P2W1D), it will expire causing an expired transition to the Old state.

A Time period can also be added using Hours, Minutes and Seconds, for example P1DT1H30M (a total of 25 hours and 30 minutes).

Note:

• P is the period designator (for the period) that precedes the  start of the duration representation.
• T is the time designator that precedes any time component of the duration representation

For example, P1M is a period of one month and PT1M is a period of one minute.

Stale content reviews

As we mentioned earlier, state expiry is useful for performing periodical checks on published or approved content to ensure that it's not become outdated.

{workflow:Stale content}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|assignable=true}
   {state}
   {state:Published|duedate=P1Y|expired=Review|final=true|updated=Editing}
   {state}
   {trigger:stateexpired|state=Published}
      {set-message}
         This content is more than one year old and has been submitted for review.
      {set-message}
   {trigger}
{workflow}

This can also be done in workflow builder - the final state Published would be edited to add the duedate as a period of 1 year.

In workflow builder the Published state would be:

Content in the Published state will expire after one year (P1Y). 

This is a one year period from the date of the transition into the Published state.

The expiry of the content causes an expired transition to the Review state.

View-only users will still see the published version of the content (see Publishing for details).

The message about the fact that it's more than one year old will also be displayed on-screen when edit permission users view the published content.

The {set-message} is triggered by the stateexpired event when it occurs in the Published state.

To remove the on-screen message you will need to add another trigger to the workflow. This can be on a pageapproved event when the stale content has been reviewed.

The triggers can be added to the workflow by copying and pasting the trigger markup using workflow builder.

Metadata use for the duedate

The stateexpiryupdated event could be used to always use the same due date in different states. So whenever the duedate is updated in one state, this will be reflected in the other states

{workflow:name=Shared Due Date}
    {state:First state|submit=Second state|duedate=P1M|changeduedate=true}
    {state}
    {state:Second state|final=true|updated=First state|duedate=@MyDueDate@}
    {state}
    {trigger:stateexpiryupdated|state=First state}
        {set-metadata:MyDueDate}@duedate@{set-metadata}
    {trigger}
{workflow}

In this example, a trigger is used to update the MyDuedate metadata value when the stateexpiryupdated event occurs in First State.

• the MyDueDate metadata value is set as the duedate value in First State. 
• the MyDueDate value is then used as the duedate for Second State.

See: Value references.

Using a workflow parameter value for the duedate

In some cases, we might want a shorter or longer expiry date.

If the workfow is stored at global level and used in many spaces, we obviously need a way to allow space admins to define a duedate which is applicable to the content in their space.

We can do that using the {workflowparameter} macro, as shown below:

A workflow parameter can be easily added to the workflow using workflow builder.

This adds the workflowparameter markup to the workflow.

The state can be edited in workflow builder to add the duedate and use the value of the workflow parameter for the duedate.

Editing the state in workflow builder adds the @State Content Duration@ as the value for the Published state duedate in the workflow markup.

{state:Published|duedate=@Stale Content Duration@|expired=Review|final=true|updated=Editing}
   {state}

We've made two changes to the previous example:

• A workflow parameter called Stale Content Duration has been added, with a default value to P1Y (1 year).
• The resulting value reference, @Stale Content Duration@, has been used for the duedate value in the Published state.

The space admin can now view and edit the default value in Parameters - Space Tools, assuming this workflow is applied in space mode:

This allows each space to have a different value, without needing to edit the workflow itself – they just set the parameter value instead.

Another example of this approach can be seen in the examples associated with our Communardo Metadata for Confluence app integration.

User editable dates

You can allow users to edit the duedate by using the changeduedate parameter.

By adding changeduedate=true to the Published state, users who can edit content will be able to change the due date via the workflow popup (see State expiry date for more information).

The changeduedate=true can be set by editing the state using workflow builder.

In the workflow popup a user can simply click the existing expiry date to edit it, showing a screen like this:

If they change the due date, it will override the value defined by the  @Stale Content Duration@ workflow parameter but only on that individual page or blog post.

This is extremely useful in cases where authors might be aware of planned changes to a product, service or process because they can ensure a review occurs around the time when that will happen.

changeduedate vs. duedate

The duedate and changeduedate parameters can be used on their own or together.  The following table describes what will happen with each possible combination:

Remember assignees

Wouldn't it be nice if subsequent reviews called back the original reviewers? You can do that by adding the rememberassignees parameter to the {approval} macro:

{approval:Review|rememberassignees=true|assignable=true}

The rememberassignees parameter can be set to true by editing the approval in workflow builder to check the Remember reviewers option.

Now when the published content expires and it gets sent back for review, the original reviewers will be contacted automatically .