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.
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).
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.
{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 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}
A workflow parameter can be easily added to the workflow using 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 toP1Y
(1 year). - The resulting value reference,
@Stale Content Duration@
, has been used for theduedate
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}
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:
duedate | changeduedate | Description |
---|---|---|
not set | false | State will not have an expiry date nor can users add an expiry date. |
set | false | State will have an expiry date based on the duedate parameter that the user cannot change. |
not set | true | State will not initially have an expiry date, but the user can add an expiry date. |
set | true | State will initially have an expiry date based on the duedate parameter, but the user can change the expiry date. |
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 .