--- title: "Expiry Dates" canonical: "https://support.appfire.com/space/CDML/649890606/Expiry%20Dates" format: markdown --- > Macro (aura-html) ## Overview > Macro (excerpt) > > States, tasks, and messages can be set to expire on a certain date or after a certain amount of time Expiry dates (due dates and durations) can be set for [States](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649595551), [Tasks](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694408) and [set-message](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650153597) macro [notifications](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649957056). You can see how expiry dates are visualized in the user interface: - [State expiry date](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649693610) - [Task expiry date](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649661544) - 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 **Y**ears, **M**onths, **W**eeks and **D**ays, or any combination of those. For example, a **P**eriod of **2 W**eeks and **1 D**ay (a *total* of 15 days) would look like: **P****2W****1D** An example is shown below for the following workflow. ![cdm_sampleexpirywf_visual.png](media://9d21e6b8-dae8-4066-9220-a5679245302d) ```plaintext {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 ![cdm_onpage_stalestate_onscreenmessage.png](media://77f03581-5dd7-4b61-b5d3-d45b9146e6f0) 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. ![cdm_onpage_stalestate_onscreenmessage_prompttaskexpired.png](media://80d40f65-47a1-446b-ac99-3ec414bfd022) 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](https://www.wikiwand.com/en/ISO_8601#/Durations) ### 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) - The time is in 24-hour format. - The time zone is based on that set in the [Java Runtime Environment](https://confluence.atlassian.com/kb/setting-the-timezone-for-the-java-environment-841187402.html) in which Confluence runs. An example is shown below: ```plaintext {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 the macro can be set by [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302). This now allows you to get the date from some other source, such as a workflow parameter, page properties or other metadata. ## Metadata Using metadata, you can obtain expiry dates from other sources or make them editable. ```plaintext {workflow:name=Custom dates} {workflowparameter:Task Duration|type=duration|edit=true} P1M {workflowparameter} {state:Will expire|duedate=@Task Duration@} {state} {workflow} ``` In the example above, a "Task Duration" parameter is defined with a default duration of `P1M` (one month). This can be edited by anyone with **Edit** permission on the content, via the [workflow popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846) (due to the `edit=true` parameter). For example, if we wanted a 2 month (P2M) duration: ![image](media://443f7ac4-4500-4d9b-8899-a691ada1e66f) ![image](media://e417333d-a775-4190-9416-3ed1947c7519) ![image](media://01e1fd95-10f9-4694-801c-3b69a0aa604e) As mentioned above, expiry dates can also be set using [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302), including [Supplier References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649532510) and [Metadata references](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649925583). ## Macros The following macros have parameters or settings which support expiry dates: > Macro (contentbylabel) For a summary of how expiry dates interact with these macros, see: [Expiry dates use in macros](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649925358). ## Notifications By default, page watchers and task assignees will receive notifications when states or tasks expire. For more information, see the **App configuration** section below. ## Events When a state or task expiry date is reached, only if the state or task is active at the time it is reached, one of the following [Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) will be sent: - `stateexpired `– a `{state}` expired - `taskexpired `– a `{task}` expired You can use these events to [Trigger](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563178) one or more [Actions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858941). Examples: > Macro (contentbylabel) ## User interface Depending on workflow configuration, expiry dates can be edited by users and/or admins in the following places: > Macro (contentbylabel) ## Pseudo-users When a state or task expires, it's not a direct result of human interaction. As such, events and actions arising from the expiry are not associated with a user account. To handle this situation, the Document Management app uses two pseudo-users. For example, the Comala Document Management pseudo-user is shown in the page document activity report below for the expiry event transition to the **Stale** state and the workflow created task added to this state. ![cdm_expirysamplewf_da_report.png](media://ab12dcea-ae0a-453a-86f8-4be67fa6bd16) ## App configuration ## Examples > Macro (contentbylabel) ## See also [Workflow Authoring Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648611901): - [States](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649595551) - [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425) - [Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) - [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) – [Parameter References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649760641), [Event references](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649925434) [User Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648907144): - [State expiry date](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649693610) - [Task expiry date](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649661544) [Reporting Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649070833): - [Report on states](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650216427) - [Report on tasks](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649661358) [Integration Guides](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649396230): - [Workflow Supplier](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726882) – [State objects](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649957742), [Task objects](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649793989)