Workflow notifications

Workflows · Notifications

Tell people when a step waits for them, and keep the initiator informed until the request is done.

While a case runs, NIM raises workflow-step events. Like any other NIM event, an event sends mail only when an event action couples a notification template to it. Without an event action, nothing is sent and the case continues as usual.

Set up a notificationDirect link to Set up a notification

Create the mail under Events → Templates. See Create notification templates.
Go to Events → Actions and select Add.
Set Event Type to workflow-step.
Choose or enter the Event Name, such as Access request.approve. NIM offers the steps of every configuration: for a published configuration, the steps of its published version; otherwise, the steps of its current drawing.
Select Add.
In the new row, choose the Template. Optionally, select a Filter.
Keep Success ticked. Workflow events are raised as successful events; with only Failure ticked, nothing is sent.
Select Save.

In the template, address the mail to the recipient with the recipientEmail property.

Hints on the configuration screen

Select a user task, service task, or start event on the configuration's Steps tab. Under Notifications, the side bar shows the exact event names for that step.

Workflow eventsDirect link to Workflow events

All workflow events have the event type workflow-step. The event name starts with the configuration name. <step> is the label of the step in the drawing, not its display name.

Event name	Raised when	Sent to
`<configuration>.<step>` (user task)	The step is handed out and waits for a performer.	Every user the participant stands for, every member of its groups, and every active delegate for the step. Each person gets their own mail.
`<configuration>.<step>` (send task)	The NIM service runs the send task.	Every user the participant stands for, and every member of its groups. Not to delegates.
`<configuration>.<step>.done`	A user task or service task is completed.	The initiator.
`<configuration>.completed`	The case finishes normally.	The initiator.
`<configuration>.cancelled`	The case is cancelled.	The initiator.

For example, with a configuration named Access request and a user task labeled approve:

Access request.approve tells the approver that a request waits for them.
Access request.approve.done tells the initiator that the approval step is done.
Access request.completed tells the initiator that the request is finished.

A participant bound to Anyone signed in is never mailed. A user without an e-mail address is skipped. NIM records every mail it sent, skipped, or failed to send in the case history as notified.

NIM raises no events for timer events, message events, failed steps, or reminders. To remind a performer, draw a non-interrupting boundary timer on the task, followed by a send task. See Workflow definitions.

Properties available in templatesDirect link to Properties available in templates

Workflow events offer these properties to the notification template, in addition to every case variable (including the built-in variables) with its current value.

Show notification template properties

Property	Contents
`caseId`	The ID of the case.
`workItemId`	The ID of the step's work item.
`configName`, `configDisplayName`	The configuration's name and display name.
`workflowName`	The name of the definition.
`step`, `stepDisplayName`	The step's label and display name.
`participant`	The participant of the step.
`subject`, `result`	The case subject and case result.
`outcome`	The outcome the step was completed with.
`performerName`	Who completed the step.
`status`	The status of the case.
`taskUrl`	For a waiting user task: a link that opens the step's App for this step. Otherwise, the NIM address.
`dateTimeCreatedUtc`, `dateTimeCreatedLocal`	When the event was raised, in UTC and in the service's local time and date format.
`recipientUserId`, `recipientName`, `recipientEmail`	The person this mail is for.
`delegatedFromName`	For a delegate: whose step it is. Empty otherwise.
`initiatorName`, `initiatorEmail`	Who started the case.

taskUrl uses the External host URL of NIM. Set it under Preferences so links in mail work outside the server.

Send tasksDirect link to Send tasks

A send task in the drawing sends its message as part of the process: the message is the template coupled to its <configuration>.<step> event. Use it for messages that belong to the process itself, such as informing a fulfiller or confirming a decision to the subject.

Without a coupled template, a send task sends nothing. The configuration shows the advisory warning No mail template is coupled to event 'workflow-step: …', so this send task sends nothing. It does not block publishing.
When a send task cannot deliver its mail, the step fails, and a supervisor can run it again.

When mail is sentDirect link to When mail is sent

NIM sends mail after the case is saved. A mail that fails never undoes a step. Cases that are loaded again when the NIM service starts are not announced again.

Notification templates — create the email used by a workflow event.
Workflow definitions — add a reminder using a boundary timer and send task.