Notifications overview

4 minute read

CloudBees Flow can be configured to send email notifications to recipients at various junctures along the deployment process. Recipients can be CloudBees Flow users and groups, as well as interested third parties. These objects support email notifications:

  • Pipeline sub-objects

    • Manual task completion and outcome

    • Approval gate rules

    • Manual retry-on-error events

  • Process (Applications and Microservices) objects

    • Process-level completion and outcome

    • Manual process steps

    • Manual retry-on-error events

Email Configurations

Create one or more email configurations: click the main menu button and select Platform Home page from the DevOps Essentials list, then navigate to Administration > Email Configurations. Define email configurations based on the context of the notifier. For example, define a Release Approvals configuration to notify recipients interested in release approval notifications. Another example: define a Deploy Notification configuration for general application process run notifications. You must define at least one configuration in order to implement notifications. For information on creating email configurations, see Email Configuration—create new or edit existing email configuration .

Application or Microservice Processes and Process Steps

CloudBees Flow sends email notifications to users and groups at the application-process or microservice-process and application-process-step or microservice-process-step (type: process) levels. The notifications are triggered based on how the job finishes (the onCompletion event) and on the job outcome (success or failure).

When configuring email notifications:

  • You specify users, groups, or email addresses as recipients of the notifications.

  • You can also target notifications at specific environments.

  • You can enable or disable notifications at the application-process-step or microservice-process-step levels.

  • You can enable or disable email notifications for manual steps.

The user and group settings are defined and managed at the platform level. See Users and Groups for more information.

Go to Configuring Email Notifications in Application or Microservice Processes about how to set up email notifications. When notifications are enabled and a default template is used, you do not have to perform additional steps to set up an email notification.

CloudBees Flow provides default templates for success and failure outcomes. All the templates have a name, subject, body, and type content that are stored as properties in CloudBees Flow.

You can edit existing templates or create new email templates in CloudBees Flow. See Email Notifier—manage notifier templates for details about editing HTML default notifications and to create new email templates.

CloudBees Flow also sends notifications for assignees and approvers of manual process steps. See Manual Steps and Tasks for more information.

Jobs, Workflow States, and Procedures

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.

You must create an email configuration before you create and configure email notifiers at the platform level. Then you can send them to individuals and groups.

To create or edit email notifiers, see Email Notifier—manage notifier templates . See the topics starting with "Email Notifier Template" for examples of HTML templates that you can use as-is or copy and rename to create a new template.

Pipelines

Notifications for pipelines are automatically sent in the following scenarios. You do not have to perform any additional steps to send email notifications.

  • For a manual task in a stage, the appropriate notifications are sent to the user or group who performs that task and to the user or group who responds when the task is completed.

  • When entry and exit gates have specified approvers, CloudBees Flow sends approval notifications to them.

    • You can set the approvals such that approval from only one of the approvers is sufficient for the pipeline to progress. In this case, you can have one approval rule and have all the approvers assigned to that rule.

    • Instead, if you want all the key individuals to approve sequentially, you can specify multiple approval rules, each for a specific user.

    • In addition to specific users, approval rules support groups. Approval or rejection from any user in the group will allow the pipeline to progress or stop.

  • You can enable or disable email notifications for pipeline gate tasks and manual task approvals.

After approvers log into CloudBees Flow, they can approve or reject the approval rules. The pipeline’s progress continues if the approval rules are approved. The pipeline will end with the appropriate error if the rules are rejected.

See Pipeline Concepts for more information about notifications in pipelines.