Email Notifier—manage notifier templates

Use this page to set up email notifiers. You must have already set up an email configuration so CloudBees Flow knows which email server to use when sending any notifications. If you have not configured an email server to communicate with CloudBees Flow, click the Administration > Email Configurations tabs to do this configuration now.

For jobs, job steps, and workflow states:

Email notifier templates are stored as property sheets under the /server/ec_notifierTemplates property sheet. You can modify or delete a template or add new templates if you have modify privileges on the server property sheet.

On start notifier—Sends an email when a job or job step starts.
On completion notifier—Sends an email when a job or job step completes.
On workflow enter notifier—Sends an email when the state becomes the workflow’s active state.
On workflow start notifier—Sends an email after the state’s subjob or subworkflow starts. If no subjob or subworkflow is defined for that state, the notifiers will not be sent.
On workflow completion notifier—Sends an email after the state’s subjob or subworkflow completes. If no subjob or subworkflow is defined for that state, the notifiers will not be sent.

For pipelines:

Email notifier templates are stored as property sheets under the /server/ec_pipelineNotifierTemplates property sheet. You can modify or delete a template or add new templates if you have modify privileges on the server property sheet.

On approval gate notifier—Sends email when approval gates are pending action.
On task retry—Sends email when a task is retried.
On manual task notifier—Sends email when manual tasks are pending action.

Using email notifiers:

Attaching an email notifier to a procedure results in a corresponding email notifier associated with the job that is created when the procedure is executed.
Attaching an email notifier to a procedure step results in a corresponding email notifier associated with the job step created when the procedure referencing the procedure step is executed.
Attaching an email notifier to a state definition results in a corresponding email notifier associated with the state that is created when the workflow is executed.

Creating a new email notifier

Enter information into the fields as follows:

Field Name Description

Field Name	Description
Name	This name can be an arbitrary text string.
Description	(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with `<html> … </html>` tags. Allowable HTML tags are `<a>`, `<b>`, `<br>`, `<div>`, `<dl>`, `<font>`, `<i>`, `<li>`, `<ol>`, `<p>`, `<pre>`, `<span>`, `<style>`, `<table>`, `<tc>`, `<td>`, `<th>`, `<tr>`, and `<ul>`. For example, the following HTML: `<p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">\https://www.google.com</a>. </span> </p>` ▼ renders as follows: `_Note:_ For more information about the abc object, see \https://www.google.com.` ▼
Condition	Use the pull-down menu to select the type of condition you need for this email notifier. Edit the auto-supplied condition in the text box or add a completely new script for your purpose. The condition specifies whether the notifier should send a message depending on the result of a property expansion. If the result is empty or non-zero, the message is sent. If the result is "0", the message is not sent
Formatting Template	Use the pull-down menu to select from a list of global, ready-to-use formatting templates. Depending on the type of email notifier you are creating, the available template choices in the drop-down menu will be different. Make sure the content is formatted correctly, i.e., no illegal characters or spacing. To customize your template, edit the auto-supplied text in the Formatting Template text box or you can add a completely new script for your purpose. Any edits made in this text box will not be saved to the global template. See Email notifier templates for a list of available templates and instructions for making global modifications to these templates. To create a custom template, the basic structure is: zero or more email header lines blank line message body The template undergoes property expansion in a `job` , `jobStep` , or `state` context. In addition to normal property paths, an additional event object is accessible via `/myEvent/` . The following example is a sample formatting template for a job: `Subject: Job '$[jobName]' from procedure '$[procedureName]' $[/myEvent/type]—CloudBees Flow notificationcc: owner@example.orgbcc: admin@example.orgCloudBees Flow Notification—from email notifier '$[/myEvent/notifier]'` `Job '$[jobName]' $[/myEvent/type] at: $[/myEvent/time]Project: $[projectName]Procedure: $[procedureName]Started: $[start]Completed: $[finish]Directory Name: $[directoryName]Launched by User: $[launchedByUser]Outcome: $[outcome]Error Code: $[errorCode]Error Message: $[errorMessage]This example demonstrates how you can send this notification using CC or BCC fields in addition to specified Destinations. Because headers are interpreted by SMTP, normal email rules apply.`
Email Configuration	Click inside this field or start typing to bring up a list of possible email configuration names. An email notifier that does not specify an email configuration will use the configuration named 'default' if it exists.
Destinations	A space-separated list of valid email addresses, email aliases, or CloudBees Flow user or group names, or a property reference that expands into such a list, or you can enter an LDAP DL name (group name).

Name

This name can be an arbitrary text string.

Description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">\https://www.google.com</a>.
</span>
</p>▼

renders as follows:

_Note:_ For more information about the *abc* object, see \https://www.google.com.▼

Condition

Use the pull-down menu to select the type of condition you need for this email notifier. Edit the auto-supplied condition in the text box or add a completely new script for your purpose. The condition specifies whether the notifier should send a message depending on the result of a property expansion. If the result is empty or non-zero, the message is sent. If the result is "0", the message is not sent

Formatting Template

Use the pull-down menu to select from a list of global, ready-to-use formatting templates. Depending on the type of email notifier you are creating, the available template choices in the drop-down menu will be different. Make sure the content is formatted correctly, i.e., no illegal characters or spacing. To customize your template, edit the auto-supplied text in the Formatting Template text box or you can add a completely new script for your purpose. Any edits made in this text box will not be saved to the global template. See Email notifier templates for a list of available templates and instructions for making global modifications to these templates. To create a custom template, the basic structure is:

zero or more email header lines
blank line
message body

The template undergoes property expansion in a job , jobStep , or state context. In addition to normal property paths, an additional event object is accessible via /myEvent/ . The following example is a sample formatting template for a job: Subject: Job '$[jobName]' from procedure '$[procedureName]' $[/myEvent/type]—CloudBees Flow notificationcc: owner@example.orgbcc: admin@example.orgCloudBees Flow Notification—from email notifier '$[/myEvent/notifier]' Job '$[jobName]' $[/myEvent/type] at: $[/myEvent/time]Project: $[projectName]Procedure: $[procedureName]Started: $[start]Completed: $[finish]Directory Name: $[directoryName]Launched by User: $[launchedByUser]Outcome: $[outcome]Error Code: $[errorCode]Error Message: $[errorMessage]This example demonstrates how you can send this notification using CC or BCC fields in addition to specified Destinations. Because headers are interpreted by SMTP, normal email rules apply.

Email Configuration

Click inside this field or start typing to bring up a list of possible email configuration names. An email notifier that does not specify an email configuration will use the configuration named 'default' if it exists.

Destinations

A space-separated list of valid email addresses, email aliases, or CloudBees Flow user or group names, or a property reference that expands into such a list, or you can enter an LDAP DL name (group name).

Click OK to save your email notifier configuration.

Editing an existing email notifier template

Modify or add information to any of the fields and click OK to save your changes.

Deleting an email notifier template

Navigate to the property sheet for the notifier you wish to delete.

For jobs, job steps, and workflow states: ` /server/ec_notifierTemplates`
For pipeline tasks and gates: /server/ec_pipelineNotifierTemplates

Email notifier templates

The table below lists global email notifier templates for your use. Each template name is a link to an example of the template output and the script.

Global templates are stored as property sheets under the /server/ec_notifierTemplates and /server/ec_pipelineNotifierTemplates property sheets. You can modify template properties or add new global templates if you have modify privileges on the server property sheet. An email notifier will be updated if changes are made to its global template.

Template Name Format Usage Description

Template Name	Format	Usage	Description
Job Summary text notification	Plain text	Procedure	Formatting template for Procedure starting/completion notifications using the long form of property names (for example, `$[/myJob/jobName]` )
Step summary text notification	Plain text	Procedure step	Formatting template for Procedure Step starting/completion notifications using the long form of property names (for example, `$[/myJobStep/jobStepId]` )
State summary text notification	Plain text	State	Formatting template for State notifications using the long form of property names (for example, `$[/myWorkflow/workflowName]` )
Job summary HTML notification	HTML	Procedure	HTML formatting template for Procedure starting/completion notifications
Step summary HTML notification	HTML	Procedure step	HTML formatting template for Procedure Step starting/completion notifications displaying information about the Job and the Job Step
All steps HTML notification	HTML	Procedure step	HTML formatting template for Procedure Step starting/completion notifications displaying information about the Job and many Job Steps
Approval request HTML notification	HTML	State	HTML formatting template for State notifications displaying information about the workflow and all of its states
Workflow summary HTML notification	HTML	State	HTML formatting template for State notifications providing the recipient with links to view or take a manual transition

Job Summary text notification

Plain text

Procedure

Formatting template for Procedure starting/completion notifications using the long form of property names (for example, $[/myJob/jobName] )

Step summary text notification

Plain text

Procedure step

Formatting template for Procedure Step starting/completion notifications using the long form of property names (for example, $[/myJobStep/jobStepId] )

State summary text notification

Plain text

State

Formatting template for State notifications using the long form of property names (for example, $[/myWorkflow/workflowName] )

Job summary HTML notification

HTML

Procedure

HTML formatting template for Procedure starting/completion notifications

Step summary HTML notification

HTML

Procedure step

HTML formatting template for Procedure Step starting/completion notifications displaying information about the Job and the Job Step

All steps HTML notification

HTML

Procedure step

HTML formatting template for Procedure Step starting/completion notifications displaying information about the Job and many Job Steps

Approval request HTML notification

HTML

State

HTML formatting template for State notifications displaying information about the workflow and all of its states

Workflow summary HTML notification

HTML

State

HTML formatting template for State notifications providing the recipient with links to view or take a manual transition