Dafne: Documentation import

2026-08-06T13:36:47Z

Documentation import

New page

An '''operator''' is a notification target. Creating one does not by itself send anything: operators must be assigned to the tasks, groups or scenarios they should be notified about.

== When notification is sent ==
When a task fails, notification is sent to the operators assigned to the failed [[Task]] '''and''' to the operators assigned to the [[Group]] it belongs to.

Notification is sent only after the '''last automatic attempt''' has been exhausted. A task configured with retries therefore does not generate a notification on its first failure — only once all its attempts have failed. This is deliberate: it keeps transient failures that recover on retry from producing noise.

Operators can also be assigned to a [[Scenario]] to be notified when it starts and when it finishes.

== Attributes ==
{| class="wikitable"
! Attribute !! Description
|-
| '''Name''' || Shown when assigning the operator to a task, group or scenario.
|-
| '''Description''' || Free text.
|-
| '''Enabled''' || Whether notification through this operator is sent at all.
|-
| '''Type''' || How the notification is delivered — see below.
|-
| '''Silent period''' || A period in minutes during which no further notification is sent through this operator.
|}

== Notification types ==
{| class="wikitable"
! Type !! Delivery
|-
| '''Email''' || Sent by email. Uses the sender, recipient and subject fields.
|-
| '''Database call''' || Executed against a configured connection.
|-
| '''Command''' || An operating system command is executed.
|}

For '''Email''', the sender address, recipient address and subject are configured on the operator. For '''Database call''', a connection is required.

For '''Command''', the command runs '''in the same environment as the executor''', under the account the executor runs as. Anything the command needs — an available binary, a path, a credential — must be present there. When shell features such as redirection are required, invoke the shell explicitly:

<code>cmd /c echo abc > file.txt</code> on Windows

<code>sh -c "echo abc > file.txt"</code> on Unix and Linux

== The silent period ==
The silent period is tracked '''per operator''', not per task. If two tasks fail within a short interval, only the first produces a notification.

This is worth understanding before setting it. A long silent period on an operator covering many tasks will suppress notifications for unrelated failures, not just repeats of the same one. Where different areas should be able to alert independently, define separate operators rather than raising the silent period on a shared one.

== Placeholders ==
The notification command may use placeholders identifying the failure. These are replaced before the command runs:

{| class="wikitable"
! Placeholder !! Value
|-
| <code>%message%</code> || The error message
|-
| <code>%taskid%</code> || ID of the failed task
|-
| <code>%taskname%</code> || Name of the failed task
|-
| <code>%groupid%</code> || Group ID of the failed task
|-
| <code>%groupname%</code> || Group name of the failed task
|-
| <code>%scenarioid%</code> || Scenario ID
|-
| <code>%scenarioname%</code> || Scenario name
|-
| <code>%processingid%</code> || ID of the processing the failure occurred in
|-
| <code>%processingname%</code> || Name of that processing
|-
| <code>%iteration%</code> || Iteration code of the processing
|-
| <code>%date%</code> || Processing date
|-
| <code>%date_n%</code> || Processing date, numeric format ''YYYYMMDD''
|-
| <code>%date_dt%</code> || Processing date, timestamp format ''YYYY-MM-DD 00:00:00.000''
|-
| <code>%processingstart_n%</code> || Processing start time, format ''yyyyMMddHHmmss''
|-
| <code>%execid%</code> || Scheduled task ID
|-
| <code>%period%</code> || Task period type (D=Daily, W=Weekly, M=Monthly)
|-
| <code>%trynumber%</code> || Attempt number within the processing
|-
| <code>%env%</code> || Environment code (P=Prod, T=Test, D=Dev, U=UAT, S=SIT, O=Other1, Q=Other2)
|}

Include <code>%message%</code> — it is what makes an alert actionable, since the recipient can see what failed without opening the GUI. Include <code>%env%</code> wherever the same definitions are deployed to several environments.

Example:

<code>
Task %taskname% failed on environment %env%: %message%
</code>

== Practical notes ==
* Test the notification when the operator is created rather than discovering at the first real failure that the command cannot run in the executor's environment.
* Disabling an operator is the clean way to stop notifications during planned maintenance; it avoids unassigning and reassigning it afterwards.
* Assign operators at group level for broad coverage and at task level only where a specific task warrants its own recipient.

== See also ==
* [[Task]]
* [[Group]]
* [[Handling failed tasks]]
* [[Placeholders]]

Operator - Revision history

Dafne: Documentation import