Troubleshooting: Expiration triggers or taskexpired macro not triggering

Summary

In Comala Document Management, workflow expiration events—such as the taskexpired macro or state duedate transitions—may fail to trigger as expected. This behavior is often linked to the configuration of internal Confluence scheduled jobs or the use of extremely short expiration intervals (for example, 1 minute) that the system cannot reliably process. This article covers identifying these causes and verifying the configuration.

`taskexpired` trigger or state expiration not executing

Problem

A user has configured a workflow to notify users when an assigned task expires or to transition a state when a duedate is reached. However, even after the expiration time has passed, no email is sent, no state transition occurs, and no page activity is recorded in the workflow history.

Cause

Scheduled job intervals: Comala Document Management relies on Confluence's scheduled jobs to process expirations. If these jobs are disabled or set to a very long interval, there will be a delay or failure in triggering the events.
Short intervals: Setting a duedate or expiration to a very short period (for example, PT1M for 1 minute) is often unreliable in production environments because the scheduled jobs may not run frequently enough to catch the exact moment of expiration.

1. Check Confluence scheduled jobs

Verify that the following jobs are enabled and configured with an appropriate interval:

Workflow Expiration Trigger: Responsible for checking if a state or task has reached its expiration/due date.
Workflow Queue Flush Scheduled: Ensures that pending workflow actions are processed.

To check these:

Navigate to Confluence Administration > Scheduled Jobs.
Locate the jobs mentioned above.
Ensure they are Enabled.
Review the Schedule (Cron expression or interval). If the interval is too long (for example, every hour), the expiration triggers will only fire when the job runs.

2. Use a practical expiration interval

Avoid using 1-minute (PT1M) intervals for testing or production. Use at least 5 minutes (PT5M) or longer to ensure the scheduled jobs have a window to capture the event.

Unreliable configuration:

{state:Published|colour=#14892C|duedate=PT1M|expired=Update review|updated=Draft}

Recommended configuration for testing:

{state:Published|colour=#14892C|duedate=PT5M|expired=Update review|updated=Draft}

3. Verify taskexpired macro syntax

Ensure the taskexpired trigger is correctly defined in your workflow JSON/markup.

{trigger:taskexpired}
    {send-email:user=@page-author@|subject=A task assigned to you has expired}
    A task on the page @page@ has expired. Please review it to keep the content up to date.
    Thank you
    {send-email}
{trigger}

4. Check task duedate formatting

If you are setting a due date on a specific task within a state, ensure the syntax for the duration is correct (for example, P5M for 5 months vs PT5M for 5 minutes).

Example:

{task:name=Review article's validity|assignee=@page-author@|duedate=PT5M}

Frequently asked questions (FAQ)

Q: Why isn't my 1-minute expiry working immediately?
A: Comala Document Management relies on Confluence's scheduled jobs to process expirations. These jobs typically run at intervals. A 1-minute duration (PT1M) is often too short for reliable execution in production or complex test environments.

Q: Which scheduled jobs control these triggers?
A: The two critical jobs are the Workflow Expiration Trigger and the Workflow Queue Flush Scheduled job.

Q: Does the task expiry email depend on the page state?
A: The {trigger:taskexpired} is independent of the state-level {trigger:statechanged}, but both rely on the background scheduler to identify that the duedate has passed.