Administration Guide

Author E-mail Notifications

On this page

An e-mail notification is a message you define once: its sender, its recipients, its subject, its body, and the parameters it expects. An E-mail Notification step in a workflow program sends it. The step names the notification, binds values to its parameters, and adds attachments. A step can use a notification of its own workflow object or one of Global Workflow, and no other.

The step does not send the message at once. The message is prepared after the record changes of the run are saved, once per changed record, in program order. A problem while the message is prepared does not undo changes already saved, and a run that stops before that point sends no e-mail.

A notification has no enabled state of its own: turning a notification on or off means turning on or off the steps that send it.

The Settings App is the only application that creates, deletes, and fully edits e-mail notifications. The Admin Center manages the HTML templates that notifications can be wrapped in, and shows the Outgoing Notifications log. For how notifications, the queue, and the logs fit together, see Notifications Overview. For workflow programs in general, see Workflow Overview and Operations Reference.

In the Settings App

Open the e-mail notifications of a class

A class node under Workflow and Business Logic has a Workflow child that opens the class's workflow tree. In that tree, Components holds E-mail Notifications. The notifications of Global Workflow are under Global Components > E-mail Notifications.

The list's toolbar has New, Edit, Delete, and Copy Item, and no enable or disable command. New opens the window of a new notification. Edit, a double-click, or Enter opens the selected notification. Copy Item copies the selected notification and opens the copy. OK saves a changed window and closes it.

Create or edit a notification

  1. In the list, click New, or select a notification and click Edit. The E-mail Notification window opens. Its header shows the class and the notification number, and it has General, Parameters, and Usage tabs.
  2. Enter the notification's required Name.
  3. In the Notification group, specify recipients in To, CC, or BCC, and enter the Subject. Leave From at the system default unless the notification needs a different sender. See Choose the recipients and Write the subject and the body.
  4. Choose the body format: Plain text, HTML text, or HTML template. A new notification starts with HTML text. Write the body, or, for HTML template, pick the template and fill in its sections (see Wrap a notification in an HTML template).
  5. On the Parameters tab, declare the parameters the steps must supply (see Declare parameters).
  6. Click OK.

Saving is refused when To, CC, and BCC are all empty.

A new notification's name combines the workflow object's name, "Email", and the notification number padded to five digits, with spaces removed, for example ProblemEmail00001. Object Class and ID show the class and the notification number.

Plain text and HTML text keep the body in the notification itself. When a notification uses an HTML template, it keeps no body of its own: a body written earlier is removed when the notification is saved, and the message is always sent as HTML. Switching from HTML text to Plain text first asks "All HTML formatting will be lost. Do you want to continue?"; No keeps HTML. Switching from HTML template to Plain text asks nothing.

The HTML editor is the same for the body, a section value, and an HTML template. It opens in Design mode; its first toolbar button switches between Design and HTML Code, and a Format command appears only in HTML Code mode. The toolbar carries the Style, Font, and Font Size boxes; bold, italic, underline, strikethrough, font color, and background color; numbered and bulleted lists and indentation; table commands (Insert Table, Insert Row, Insert Column, Delete Row, Delete Column, Merge Cells); left, center, and right alignment; and Insert Horizontal Line, Insert Link, and Insert Image. The Style list holds Formatted, Heading 1 to Heading 5, and Paragraph. The editor shows the content with the notification style sheet (see Wrap a notification in an HTML template).

Declare parameters

The Parameters tab lists the notification's parameters with their Name, Type, and Default Value. Its toolbar has New, Edit, Delete, Move Up, and Move Down.

  1. Click New, or select a parameter and click Edit. The Parameter dialog opens.
  2. Enter a Name. A name already in use is refused with "This Name is already in use. Please use a different one."
  3. Choose the Type. A new parameter is of type String. For the Reference type, pick in Reference to the lookup the value is drawn from; the box is enabled only for that type.
  4. Optionally, enter a value in the Default value group. Its expression button opens Build Expression; a default built there is evaluated as an expression when the message is prepared.

Each step that sends the notification binds values to its parameters. A step cannot be saved as enabled while a parameter without a default has no value. Changing a parameter's type, lookup, or table removes the step values that no longer fit. Parameter values are taken as they were at the step's position in the program, so a message prepared after the changes are saved still reports the values that step saw.

When tab counters are on, the Parameters and Usage tab captions show a count.

See where a notification is used

The Usage tab lists the callers of the notification. Its Open command opens the calling item or function, or a scheduled task's properties. The Settings App does not delete a notification while it is in use.

Choose the recipients

From shows "System defaults (sender)", with "Empty" in place of the sender when none is set. Leave it unchanged to send from the installation's default sender.

To, CC, and BCC are lists of entries separated by semicolons or commas. Each entry is calculated on its own, and one entry can yield several addresses: the result is split again on semicolons and commas, each piece is trimmed, empty pieces are dropped, and text inside double quotes is not split. Entries that come out empty are skipped. Repeated addresses are not reliably removed within a list, and never across To, CC, and BCC.

Each of the five boxes (From, To, CC, BCC, Subject) keeps its own list of recently used values and has an ellipsis button that opens Select Placeholder, with the box's selected text as the search. While a box has focus, its context menu also offers Insert Placeholder..., which opens the same window.

For To, CC, and BCC, Select Placeholder has an E-mail Fields category. It lists the class's own non-lookup fields whose name contains "email", then, under each lookup field, that lookup's non-lookup fields whose name contains "email", and last Current User with its primary e-mail address. They are inserted as %[DBF <field>]%, %[DBF <lookup field>.<field>]% (for example %[DBF Assignee_ID.Primary_Email]%), and %[SYS Current User.Primary_Email]%. The category is not offered for a service workflow object, or when no field matches.

An entry that uses the calculated field Group_Email_List is replaced with the addresses of the group's members: every member Person that has a primary e-mail address and is not inactive. Groups contain Persons only, so the expansion is one level deep.

To compute a recipient list with SQL, put a placeholder in the address box: either a String parameter, %[PAR <name>]%, that the step binds to a SQL script, or a SQL script user macro. The placeholder is replaced with the first column of the script's last result set, and that text is then split into addresses as described above, so a closing select that returns a@x.com, b@x.com addresses both. Inside the script, a placeholder is replaced with a finished SQL value, so write %[DBF ID]% without quotes.

Self-notification is on for an installation by default. When it is turned off, every To address that contains the acting user's e-mail address is dropped; CC and BCC are computed without that filter and still reach that user. If that leaves To empty and no CC or BCC address remains, the run marks the notification as ignored to prevent self-notification, and the message is not queued at all. If CC or BCC addresses remain, the message is queued with an empty To. For the setting, see Outgoing E-mail Settings.

Write the subject and the body

The address boxes, the subject, and the body are templates: placeholders in them are replaced when the message is prepared. What Select Placeholder offers depends on the box:

Box What Select Placeholder offers
From, To, CC, BCC the class's fields and Current User; To, CC, and BCC also get E-mail Fields
Subject the class's fields, Current User, the common event macros, and Notification ID
Body the class's fields, Current User, the common event macros, and the e-mail macros; for an Incident also Object Changes EndUser

The five boxes also offer Parameters (the notification's parameters as the Parameters tab holds them at that moment, without attachment-type parameters), User Macros (those bound to no class, to this class, or to its general class), and, when any global parameter exists, Workflow Parameters. The body also offers the notification's parameters, user macros, and workflow parameters. For Subject and for a plain-text body, the context menu also offers Create New Macro.... The window has Category, Item, SubItem, Description, Placeholder, Insert, OK, and Cancel.

Macro set Members
Common event macros Now, Today, Initiator, License Information, Action ID, Action Name, WF Item ID, WF Item Name, MessageID Tag, Web Portal Link, Self Service Portal Link, API Link, Job Settings, AI Features Enabled, Default Currency Code
E-mail macros Object Changes All, Notification ID, MessageID Tag, System Information

Job Settings appears as a field group rather than a macro, and Default Currency Code appears only under a multi-currency license. For what each macro returns, see Macros Reference.

SQL and PowerShell reach a notification in two ways:

  • Through parameters. A parameter value built as an expression (the step's value, or the default when the step gives none) is a SQL expression, a SQL script when its first line is <SQL>, or a PowerShell script when its first line is <PS>. An expression for an attachment-type parameter yields attachment ids. A text value that is not an expression but contains a placeholder is calculated as a template, in HTML mode for an HTML parameter. All parameters are computed before the body, the sender, and the subject.
  • Through user macros. Each template calculation first expands user macros, SQL and PowerShell ones included. A SQL script user macro, with plain-text or HTML output, runs as a SQL script, and a PowerShell script user macro with plain-text output runs as a PowerShell script; a PowerShell script user macro with HTML output is substituted as literal text. See Macros Reference.

A one-click action link in the body is written by hand; see One-click action links.

Wrap a notification in an HTML template

An HTML template is HTML with section placeholders. The template decides which sections a notification is asked to fill.

  1. On the notification's General tab, choose HTML template and pick the template in Template. The section grid adds a row for each section the template contains.
  2. Edit a section row. A dialog named after the section opens, for example Section1 Value.
  3. Choose plain text or HTML, write the value, and click OK. OK checks the text against the notification's fields and parameters, and the dialog stays open when the check fails.
  4. Click OK in the notification window.

A value stored for a section the template does not contain stays in the grid in gray. A cleared value is removed, and an empty one is dropped when you change the template.

When the message is prepared, each section placeholder in the template is replaced with the notification's value for that section: a plain-text value is encoded as HTML text, and an HTML value is inserted as it is. Placeholders written inside a section value are then replaced like any other placeholder of the body.

The look of every HTML notification comes from one notification style sheet for the whole installation, not from its template.

Manage HTML templates

HTML templates are under Notifications > E-mail Notifications > HTML Templates. The list's toolbar has New, Edit, and Delete; opening a row from the grid runs Edit.

  1. Click New, or select a template and click Edit. The HTML Template window opens.
  2. Enter a Name. It is mandatory: saving an empty name is refused with "The "Name" field is mandatory, it can't be left blank."
  3. Write the template in the HTML editor.
  4. To add a section, click Insert Section and choose one. It is inserted as %[SEC <section>]%. The list offers only sections the template does not contain yet.
  5. To add another placeholder, click Insert Placeholder.... Here Select Placeholder offers Current User, the e-mail macros, a Sections category, user macros, and workflow parameters, but no object fields and no notification parameters.

There are exactly ten sections: Header, Greeting, Sidebar, Body, Footer, and Section1 to Section5. You can use any of them and cannot add others. The SEC token is recognized in any letter case. The Settings App does not check for a section placeholder you type twice by hand.

Delete removes the selected template. A template that a notification uses cannot be deleted; the message names the template ("You cannot delete the template "name" because it is in use by one or more E-mail Notifications. Associate these E-mail Notifications with a different template and try again."), with at most the first 50 characters of the name. Move those notifications to another template first.

Add the notification to a workflow step

  1. Open the workflow item that should send the message, for example a step action under Actions > Step Actions in the class's workflow tree, and go to its Programming tab.
  2. In the operations tree, choose New > E-mail Notification. The step is added after the selected row, or as the first row inside a selected IF, ELSE IF, or ELSE group. The E-mail Notification window opens, showing the class the step works on in Object Class, and the Select E-mail Notification list opens at once. Inside a Create Object or Act on Related Object block, the header shows that block's class and a warning line naming how that object is created from or related to the workflow object.
  3. Choose a notification. The list shows the notifications of the item's own workflow object and of Global Workflow. To create one in place, click New in the list. E-mail Notification shows the chosen notification's name. Once a notification is chosen, that label is a link that opens the notification's editor, and Select opens the list again.
  4. Under Attach, select the files to attach. Each check box enables its own control:
    • Files attached to this object (selected for a new step) attaches the files an earlier step of the same run attached to the record.
    • Files attached using this control: attaches the files the user supplied in an attachment area of the action form, or passed in a stream-typed parameter of the program. It reads Files passed with this parameter: when the program's parameter list has its default name, and it is disabled when that list has no name.
    • Other files: attaches what an expression returns: attachment ids, or record or activity ids whose attachments are then attached. The expression can also be a SQL script whose first line is <SQL>; every non-empty value in the first column of every result set counts. An expression that returns %[DBF ID]% attaches the files the record already has.
  5. In the Parameters grid, give each parameter a value (see Give parameters their values).
  6. Click OK. Enable operation is selected by default.

OK stays disabled until the step's required values are set. While Enable operation is selected, OK refuses a step whose check fails and shows the reason; for a parameter without a value it is "This operation can not be executed, because not all parameters of the notification are assigned." Selecting Enable operation shows the same reason. A step saved with Enable operation cleared is skipped when the program runs. Cancel on a new step removes the row again. In the operations tree, Enable Operation and Disable Operation turn an existing step on or off without deleting it.

For a service workflow object, the first two Attach check boxes are disabled, so a service action's notification can attach files only through Other files:.

The combined size of the attachments is checked against the installation's notification attachment limit. The limit is off by default, and its default size is 1 MB. A step whose attachments exceed the limit is aborted, and the step's operation log is cleared. For the limit settings, see Outgoing E-mail Settings. In Alloy Navigator Cloud, the two notification attachment limit controls are read-only; see Administering Alloy Navigator Cloud.

Give parameters their values

The Parameters grid lists the notification's parameters in declared order, with Name and Value. A row the step has not bound shows <Default> when the parameter has a default, and <Double-click to assign value> in red when it has none. A row bound to nothing shows <Empty>, and an expression value is shown underlined.

  • Double-click a row or press Enter to open Assign Parameter. It shows the Parameter name, a Value editor fitted to the type (a lookup list for a reference parameter, a list of attachment areas for an attachment one), and an expression button that opens Build Expression.
  • Right-click a row for quick values of the same type: <Empty>, False and True for a Boolean parameter, then the program's parameters (%[PAR <name>]%), action-form fields (%[VIR <name>]%), attachment areas, and variables (%[VAR <name>]%), each only when its type and lookup match the row's. A picked value other than an attachment or object value is checked like a typed value before it is stored.
  • Press Delete or Backspace to remove a value, or Ctrl+Alt+Q to bind every unbound row to empty.

In Build Expression, the Expression Type group offers Text (named HTML for an HTML parameter, and otherwise shown only for text parameters that are neither lookups nor multi-valued), SQL expression, SQL script, and PowerShell script; an object-typed parameter gets only the two script types. The dialog starts in Text for a text parameter whose value is not already an expression; otherwise it starts in SQL script for an array-typed parameter, PowerShell script for an object-typed one, and SQL expression for any other. OK checks the expression by its type. With Text chosen, a value that begins with SELECT, in any letter case, asks "Is this text a SQL-expression?". Yes checks it as a SQL value and switches the type to SQL expression only when that check passes; No checks it as a text template. Choosing SQL expression, SQL script, or PowerShell script stores the value as an expression. By default, a SQL script is stored with the first line <SQL> and a PowerShell script with <PS>; a SQL expression carries no such line. Closing Build Expression with unsaved changes asks "Do you want to save the changes?": Yes keeps the value and closes, and a SQL expression or SQL script must pass its check first; No closes without saving; Cancel keeps the window open.

When the program runs, an unbound parameter takes its default. A SQL script gives the parameter the first column of the first row of its last result set, as a closing SELECT returns it; for an array-typed parameter, the first column of every row, joined with semicolons. The expression of an attachment-type parameter is read like the Other files: text of the step.

In the Admin Center

Manage HTML templates in the Admin Center

The Notifications > HTML Templates page lists the templates by Name. The menu entry requires a permission for notifications; see Permissions Reference.

  1. Click New, or select one template and click Edit. A drawer opens, titled New HTML Template for a new template.
  2. Enter a Name. It is required.
  3. Write the template in the HTML editor, which has a placeholder picker. The editor shows the template with the notification style sheet.
  4. Save the template.

The Admin Center refuses a template that contains the same section placeholder twice: "Each section placeholder can be used only once per template".

To delete templates, select one or more and click Delete. If any selected template is in use, none of that request's templates are deleted, and the in-use message names the template (at most its first 50 characters).

Notification logs in the Admin Center

The Admin Center's workflow log does not show the notifications a run sent. Its Log Entry Details drawer shows Run Date, Item Name, Object ID, Event, Triggered by Action, Initiator Name, Initiator Type, Host, Status, and Error Message, but not the content or the recipients of the messages.

The Outgoing Notifications log records send passes of the notification queue, not individual notifications. It is reached from two places, the Logs page under Notifications and the Outgoing Notifications tile of the Logs section; both show the same log and edit the same retention value. Its columns are Type (E-mail or Push, a link to the entry), Run Date, Comments, Duration, Total, Succeeded, and Errors, newest first. The search covers the type, comments, duration, the three counts, and the content. At most the newest 1000 entries are returned. Deleting entries requires a separate log permission; see Permissions Reference.

What the logs keep

The workflow log keeps one record for each notification a run fully prepared, with its name, its message number, the four address fields, the subject, and the content, all with their placeholders resolved. In the workflow log these records appear as Sent Notifications; the Admin Center's workflow log does not show them. This is the only place the sent content is kept, because a queued message is deleted once it is sent. If a message cannot be prepared, the run's log entry is marked failed and carries the error message.

By default, workflow log entries are kept for 7 days and Outgoing Notifications entries for 30 days. Both logs can be read in the Settings App and in the Admin Center. For log retention, see Logs.

A one-click link that runs a workflow action from the message is written into the body by hand; Alloy Navigator has no ready-made action-link component, and the notification editor does not check that such a link is well formed. The database function dbo.GenerateActionURLParams builds the link from the API link, the action, the Person, the record, an expiration date, optional field values as field=value&... pairs, and an optional success message, and returns the link with its parameters encrypted. An empty API link argument falls back to the API Link value.

When the link is opened, the action runs as an update of that record, with that Person as the acting person, and a page reports success unless the action raises an error, in which case the error page shows the error's message. A link that lacks the record, the action, or the Person shows "Invalid Link", and an expired link shows an error page. A link cannot run a create action.