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 periodic review to ensure it doesn't become outdated.

Upon expiry, you can use the expired parameter to transition to another state, or 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}

Will that workflow ever transition to the Old state?

Yes, as the workflow background processor finds all pages that have expired but not yet triggered an expiry event

The time zone is determined by the Java Runtime Environment in your hosted Confluence instance.

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.

Units	5 * Unit

Units	5 * Unit
Years	5Y
Months	5M
Weeks	5W
Days	5D

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.

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

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 has 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 workflow builder - the final state Published, can be edited to add the duedate as a period of one year.

In workflow builder, the Published state is:

A document 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 can 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 is also 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 need to add another trigger to the workflow. This can be on a pageapproved event when the stale content has been reviewed.

{trigger:pageapproved|approval=Review}
    {set-message}{set-message}
{trigger}

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 workflow is stored at a global level and used in many spaces, we obviously need a way to allow space admins to define a due date that applies 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}

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

This adds the workflowparameter markup to the workflow.

{workflowparameter:Stale Content Duration|type=duration|description=Duration for periodical review of published content}
      P1Y
{workflowparameter}

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 of P1Y (1 year).
The resulting value reference, @Stale Content Duration@, has been used for the duedate value in the Published state.

The space administrator 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 using the workflow state dialog box (see State expiry date for more information).

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

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

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

If they change the due date, it overrides 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 happens.

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:

`duedate`	`changeduedate`	Description

`duedate`	`changeduedate`	Description
not set	`false`	The state will not have an expiry date, nor can users add an expiry date.
set	`false`	The state will have an expiry date based on the due date parameter that the user cannot change.
not set	`true`	The state will not initially have an expiry date, but the user can add an expiry date.
set	`true`	The state's expiry date will initially be based on the due date parameter, but the user can change it.

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 are contacted automatically.