Skip to content

Listen for Case Lifecycle Events

Goal

Start small, event-specific workflows when a case opens, changes, or closes.

What You Will Learn

  • configure Event Listener Modules for case lifecycle events
  • read the current case through $Case and the event snapshot through $Input
  • keep event handlers separate and avoid recursive Case.Update behavior

Difficulty and Estimated Time

  • Difficulty: Advanced
  • Estimated time: 25 minutes

Assumed Knowledge

You should be familiar with module tasks, workflow starting points, case properties, XML, actions, and routes.

Required Reading

Prerequisites

  • a case-enabled test channel
  • permission to create and commit a process containing module tasks
  • a test group that can receive event-generated work items

Steps

Listen for Case Updates

  1. Add an Event Listener Module and configure it as a starting point.
  2. Set Event Name to Case.Update.
  3. Connect the first action to a task named Review Case Change.
  4. Assign the task to a test group.

Add a handle script only when routing depends on event data. $Input contains the case snapshot, including fields such as Id, Subject, Priority, DeadlineAt, and Profile. $Case exposes the current runtime case.

For example, the handler can continue only for high-priority cases:

1
2
3
4
5
var priority = $Input.Evaluate('/*[local-name()="Case"]/*[local-name()="Priority"]');

if (priority === 'High') {
    $WorkItem.SelectedAction = 'Review';
}

Name the outgoing action Review. When no script is needed, leave it empty so the first available action is selected.

Add Open and Close Listeners

Create separate starting Event Listener Modules for Case.Open and Case.Close. Route each listener to a task that states its purpose, such as Review Reopened Case or Record Case Closure.

Do not combine all lifecycle events into one opaque handler. Separate listener tasks make the triggering event explicit and allow each path to have its own authorization and retry behavior.

How It Works

Case operations publish domain-level events after their corresponding operation. The event listener receives the case snapshot in $Input, while $Case points to the affected case. Starting listeners create a new workflow instance for each matching event.

Verify the Result

Update, close, and reopen a test case one operation at a time. Confirm that only the matching workflow path starts and that the created task references the expected case. Set the priority to a non-high value and confirm that the scripted update path does not select Review.

Failure and Edge Cases

  • Case events are synchronous; an exception in the listener rolls back the originating case operation.
  • Updating the case from a Case.Update listener can trigger another update and create a loop.
  • Delete events require special care because the case may no longer be available for follow-up work.
  • Case.Assign, Case.Deadline, and Case.Reply should use dedicated listeners when their behavior differs.

Security and Portability Notes

  • Keep synchronous handlers short and move slow integration work to a controlled follow-up task.
  • Do not copy personal data from the event snapshot into logs or unrestricted activity entries.
  • Apply the same channel and case authorization expectations to event-generated work.

What to Learn Next