Expiry Dates

Overview

Expiry dates (due dates and durations) can be set for States, Tasks and set-message macro notifications.

You can see how expiry dates are visualized in the user interface:

State expiry date
Task expiry date
Messages – they just disappear after expiring

Date formats

Expiry dates can be set using either a duration code or by specifying a specific date and time.

Duration codes (ISO 8601)

The duration code says "From the current time, wait for this amount of time before expiring".

When the state is entered, or a task or message is created, the duration code is internally converted to a date and time (based on the current time plus the duration). You don't need to know the exact date and time in advance; the workflow will work it out for you.

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

An example is shown below for the following workflow.

{workflow:name=Example Expiry|key=18841643}
    {state:Initialize|submit=Current}
    {state}
    {state:Current|expired=Stale|duedate=P3M|changeduedate=true}
    {state}
    {state:Stale|expired=Expired|completed=Updated|duedate=P1D|changeduedate=true}
        {task:name=Update state about to expire|duedate=PT18H}
    {state}
    {state:Expired|completed=Updated}
        {state-selection:states=Current|permission=ADMINISTER}
    {state}
    {state:Updated}
        {state-selection:states=Current}
    {state}
    {trigger:taskexpired}
        {set-message:duration=PT6H}Task expired "@taskname@"{set-message}
    {trigger}
    {trigger:stateexpired|state=Current}
        {set-message:duration=P2W1D}
        "@state@" state expired with @duedate@
        Please update content and set all tasks as completed.
        {set-message}
    {trigger}
    {trigger:statechanged|state=Current}
        {set-message}{set-message}
    {trigger}
    {trigger:statechanged|state=Updated}
        {set-state:Current}
    {trigger}
{workflow}

The Current state content is set to expire after 3 months.

On expiry, the Current state transitions to the Stale state for triage.

The Stale state has

a duedate of 1 day
a task added by the workflow with a due date of 18 hours
a message stating the Current state has expired and needs updating

A workflow trigger listens for the expiry of the due date for the task and on expiry displays a further on-screen message prompt for the task.

This message is displayed for 6 hours.

It is also possible to specify hours and minutes; for more information, see: Full ISO 8601 Duration Specification

Date and time

To set a specific date and time, use the following format: YYYY-MM-DD HH:mm

For example, 1:05PM on the 20th November 2020 would be: 2020-11-20 13:05

Notes:

Can only be used on duedate parameters or Value References
The time is in 24-hour format.
The time zone is based on that set in the Java Runtime Environment in which Confluence runs.

An example is shown below:

{workflow:name=Example}
   {state:Already expired|duedate=2020-11-20 13:05|expired=Expired}
     {task:Already expired|duedate=2020-11-20 13:05}
   {state}
   {state:Expired}
   {state}
   {trigger:stateexpired|state=Already Expired}
      {set-message}State expired: @state@{set-message}
   {trigger}
   {trigger:taskexpired}
      {set-message}Task expired: @taskname@{set-message}
   {trigger}
{workflow}

In the example above, the dates are all in the past, so, for example, the "Already expired" state will already be expired when the workflow enters that state; it won't cause any events, and it won't transition to the "Expired" state, so no messages will be shown. The same is true for the tasks.

This may not seem like it would have much value on its own, it would be pretty unlikely that you know the exact date you want a state to expire when setting up a workflow. But the value in t