Email notifier templates

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

For jobs, job steps, and workflow states:

Email notifier templates are stored as property sheets under the /server/ec_deploy/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 are not 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 are not sent.

For pipelines:

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 notifier template

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: `<i>Note</i>: For more information about the <b>abc</b> 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, for example, no illegal characters or spacing. To customize your template, edit the auto-supplied text in the Formatting Template text box or 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]—{PRODUCT} notification cc: owner@example.org bcc: admin@example.org{PRODUCT} 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 uses the configuration named `default` if it exists.
Destinations	A space-separated list of Valid email addresses Email aliases CloudBees CD/RO user or group names A property reference that expands into a list of user or group names An LDAP distribution list 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:

<i>Note</i>: For more information about the <b>abc</b> 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, for example, no illegal characters or spacing. To customize your template, edit the auto-supplied text in the Formatting Template text box or 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]—{PRODUCT} notification
cc: owner@example.org
bcc: admin@example.org{PRODUCT}
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 uses the configuration named default if it exists.

Destinations

A space-separated list of

Valid email addresses
Email aliases
CloudBees CD/RO user or group names
A property reference that expands into a list of user or group names
An LDAP distribution list name (group name)

Select OK to save your email notifier configuration.

Editing an existing email notifier template

Modify or add information to any of the fields and select 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_deploy/ec_notifierTemplates.
For pipeline tasks and gates: /server/ec_deploy/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_deploy/ec_notifierTemplates and /server/ec_deploy/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	Plain text	Procedure	Formatting template for Procedure starting/completion notifications using the long form of property names (for example, `$[/myJob/jobName]` )
Step summary	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	Plain text	State	Formatting template for State notifications using the long form of property names (for example, `$[/myWorkflow/workflowName]` )
Job summary	HTML	Procedure	HTML formatting template for Procedure starting/completion notifications
Step summary	HTML	Procedure step	HTML formatting template for Procedure Step starting/completion notifications displaying information about the Job and the Job Step
All steps	HTML	Procedure step	HTML formatting template for Procedure Step starting/completion notifications displaying information about the Job and many Job Steps
Approval request	HTML	State	HTML formatting template for State notifications displaying information about the workflow and all of its states
Workflow summary	HTML	State	HTML formatting template for State notifications providing the recipient with links to view or take a manual transition

Job Summary

Plain text

Procedure

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

Step summary

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

Plain text

State

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

Job summary

HTML

Procedure

HTML formatting template for Procedure starting/completion notifications

Step summary

HTML

Procedure step

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

All steps

HTML

Procedure step

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

Approval request

HTML

State

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

Workflow summary

HTML

State

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