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 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=2017-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 data center 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 triggered yet 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

{workflow:name=Duration}
   {state:15 days|duedate=P2W1D|expired=Old}
   {state}
   {state:Old}
   {state}
{workflow}

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.

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}

In this example, the Published state will expire after one year (P1Y), causing an expired transition to the Review state.

View-only users will still see the published version of the content (see Publishing for details), and everyone will see a message about the fact that it's more than one year old.

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

The stateexpiryupdated event could be use to always use the same due date in different states, so whenever a 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}

Metadata

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:

{workflow:Stale content - editable duedate}
   {workflowparameter:Stale Content Duration|type=duration|description=Duration for periodical review of published content}
      P1Y
   {workflowparameter}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review|assignable=true}
   {state}
   {state:Published|duedate=@Stale Content Duration@|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}

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).

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

They can simply click the existing expiry date to edit it, showing a screen like this:

If they change it, it will override the value defined by @Stale Content Duration@ workflow parameter but only on that indivudual 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}

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