Getting Started—Scenario 3—Notification, Scheduling, and Reporting

10 minute read

Scenario requirements: For this scenario, you must set up an Email Configuration to use the email notification feature.

To set up an Email Configuration:

  • Click Administration>Email Configurations.

  • Click the Add Configuration link.

Enter information in the fields to define your mail system.

NameNew versionStatus

Name

Enter a unique name for your email configuration.

Description

Optional) Enter a text description for your reference.

Mail Protocol

Use the drop-down arrow to make a selection.

Mail Host

Enter the name of your mail host.

Enter information in the remaining fields according to the specifications you need. Your New Email Configuration page should look similar to the following example:

Click Save after filling in the fields or click the Test button first if you want to make sure your email configuration works. Enter an email address in the pop-up box and click Send.

For additional help with this CloudBees Flow page, click the Help link in the topright corner of the page.

Overview

This scenario guides you through creating an email notification, invoking your build process with a timed (standard) schedule, invoking your build process using a continuous build integration trigger, and introduces CloudBees Flow reporting features.

At the end of this scenario, you will be familiar with the following CloudBees Flow concepts and features:

  • Creating an email configuration

  • Creating an email notifier

  • Creating schedules

  • Creating reports

Begin Scenario 3

Step 1. Creating an email notifier

On the Procedure Details page for the Basic Build procedure, click the Create On Completion Email Notifier link to begin. This link takes you to the New On Completion Email Notifier page.

Two email notifier types for jobs or job steps:

  • 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.

The fields for each of these notifiers are similar, but we chose the On Completion notifier because you may find you use this one more frequently.

On the New On Completion Email Notifier page:

Enter information into the fields as follows:

Field NameDescription

Name

For this example, we use BuildTeam. This name can be an arbitrary text string.

Description

(Optional) Enter a text description for your reference. CloudBees Flow does not use or interpret this information.

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, non-zero, or "true", the message is sent. If the result is "0" or "false", the message is not sent.

Formatting Template

For this example, choose the "Job summary HTML" notification template, or you can use the drop-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. To customize your template, edit the auto-supplied text in the Formatting Template text box, or you can add a completely new template for your purpose. Note: Any edits made in this text box will not be saved to the global template, and the template will appear as a Custom template when you return to this notifier definition. Additionally, make sure the content is formatted correctly, i.e., no illegal characters or spacing.

Email Configuration

Use TestEmailConfig, the email configuration we created.

Destinations

This is a space-separated list of valid email addresses, email aliases, or CloudBees Flow user names, or a property reference that expands into such a list.

After filling in the fields, your page may look similar to the following example:

Click OK to create your email notifier and to return to the Procedure Details page, where you can now see the Email Notifier you created. For more information, see the Email Notifiers Help topic.

Step 2. Creating a standard schedule

To create a standard timed schedule:

  • Select the Projects tab.

  • Select your project name to go to the Project Details page.

  • Select the Schedules subtab, then select the down-arrow to the right of the Schedule link, and choose Standard Schedule to go to the New Schedule page.

On the New Schedule page:

The following is an example of the New Schedule page.

  • Notice the breadcrumb above the New Schedule page title—this entry displays the name of the project that contains this schedule.

  • After entering a name (unique within your project) for your schedule (we chose Sentry-MainBuild), choose the procedure your schedule will run.

  • Click the Change link adjacent to the Procedure field.

  • In the pop-up menu, leave the Current project selected.

  • Place your cursor in the Procedure field to see a list of procedures in your project.

  • Select the procedure you want this schedule to run. We chose Basic Build.

Enter information in the remaining fields as follows:

FieldDescription

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.

Parameters section: If the procedure has parameters, enter their values in this section. The procedure cannot execute unless all required parameters are provided.

Frequency section: Run at is a summary section. As you make selections for the following Days and Repetition sections, a summary of what you selected appears here.

Days

Select weekdays, month days, or create a custom frequency when you want the schedule to run.

The day applies to the start time if the time range spans two days, that is, if the time range crosses the midnight boundary.

Repetition

  • If Run Once—the schedule will run once per selected day, at the time you specify.

  • If Run Every—the procedure will execute repeatedly during the specified time range. For example, if you select a time range from 11:00-14:00 and an interval of 40 minutes, the procedure will execute 5 times on each of the selected days: at 11:00 am, 11:40 am, 12:20 pm, 1:00 pm, and 1:40 pm.

  • If Run Continuously—as soon as one job ends, the scheduler will trigger immediately to run the job again.

Advanced section

Enabled

If this box is "checked," the schedule will run. You can disable this schedule.

For this scenario, you do not need to enter information for any remaining fields. Later, when creating an actual timed schedule for one of your procedures, refer to the Help topic for this page for more information.

Click OK to create this schedule.

At any time, you can return to the Project Details page for this project, select the Schedules subtab, and then select the Schedule Name from the table to go to the Edit Schedule page to modify this schedule.

Step 2a. Creating a continuous integration build trigger

At a later time when you have procedures and steps created to do the work you need, you may prefer implementing continuous integration build configurations for your software builds. Unlike a standard schedule that runs on days and times you specify, a continuous integration build can be triggered to run each time code is checked into your source code management (SCM) system.

Adding a project to the Continuous Integration Dashboard is quick and easy. Each project can have one or more CI configurations, depending on the number of source branches you want to monitor. After the simple configuration process, you can visually see status and other information about your continuous integration jobs as builds are triggered to run.

To find the Continuous Integration Dashboard, select the Home tab, then select the Continuous Integration subtab. The dashboard will be empty until you start adding projects. For help using the Continuous Integration Manager and Dashboard, click the Help link in the upper-right corner of the dashboard web page.

Step 3. Creating a report

CloudBees Flow provides multiple reports and custom report capabilities to help you manage your build environment. Summary of available report types:

  • Real-time reports—filtered view of your CloudBees Flow data in real-time

  • Build reports—summary reports produced at the end of a build and attached to the job

  • Batch reports—summaries of your build environment with trends over time, two types:

  • Default Batch reports—automatically installed during CloudBees Flow installation and scheduled to run daily (Cross Project Summary, Variant Trend, Daily Summary, Resource Summary, Resource Detail)

  • Optional Batch reports—you can configure and schedule these reports to fit your requirements (Category, Procedure Usage, Count Over Time, or Multiple Series reports)

  • Custom reports—your choice to create and add at any time

Batch and Custom reports must be run on the CloudBees Flow server agent (local agent) only. These reports use the BIRT report engine, which is installed only on the CloudBees Flow server.

Before you create a report, you need to define a search to focus the report on the information you want to see.

Enter information into the fields as follows:

FieldDescription

Object Type

Use the drop-down menu to select the object you wish to search.

Criteria

Click Add Criteria one or more times to further define the sort criteria for your search. * Use the drop-down arrow to select a criteria argument. These arguments are properties. For a description of any of these properties, see the Properties Help topic. * Use the drop-down arrow to select an operator for the search. * To narrow your search, enter an actual object name. For example, if you selected Project Name to begin your search, you might want to enter the actual project name in this field or the first few letters if you have multiple projects named in a similar pattern.

Custom Criteria

Not needed for this scenario.

Your Searching and Filtering page will look similar to the following example:

Click OK after filling in the fields and to go to the Search Results page.

Click Save Report Filter. In the dialog box, use the drop-down arrow to select the project name for your report, then enter a name of your choice for the filter. We used BasicBuildFilter for the filter name to tie the filter name to the Basic Build procedure for which we are creating a filter.

Click OK to return to the Job Search Results page. Now we are ready to define the report we want to see.

Define the report

For this scenario, we create an Optional Batch report. Select the Projects tab, select your project name to go to the Project Details page, then select the Reports subtab.

Click Create Report.

On the Optional Batch Reports page

For this scenario, select the Multiple Series report tab.

Enter information in the fields or select the appropriate values as follows:

FieldDescription

Report Title

This is your report title. Type over the default report name, choosing any unique name for your report. We supplied Basic Build Report for our report name.

Saved Filter

Project—Click your mouse inside this field to see a list of projects from which to make a selection. We select our FirstNewProject project name. Filter—Use the BasicBuildFilter we created earlier.

Time Period

Use the drop-down menu to select the time period.

Create thumbnail?

Check this box so you can view this report on your Home page. (We will create a “thumbnail” report view on your Home page at the end of this scenario.)

Object Type

Use the drop-down menu to select Job for this example.

Table column choices

Chart Type

Use the drop-down menu to choose the chart type.

Function

Use the drop-down menu to choose the function you need.

Property Name

Use the default property value or delete the text and click your mouse in the blank field to see a list of possible properties. We chose "outcome" for this example.

Display Name

You can choose a different unique Display Name if you prefer to do so.

Stacked

Select this check box to see your report results "stacked" versus overlaid.

The "X" icon

Click this icon to delete any row you no longer need.

Add Series button

Select this button if you would like to create additional table entries for additional report information.

Chart Options

Use the down-arrow to adjust the Time Grouping and see the defaults for the X and Y axis.

Your Multiple Series report page is similar to the following example:

  • Run Report button—(information only for this scenario) this button takes you to the Job Details page to run the report immediately—one time only.

  • Create Schedule button—this button displays a box with a default schedule name you can change.

  • Enter a name for the schedule—again, we tied the schedule name to the procedure name for which we want the report.

  • Click OK to go to the Project Details page.

Now you can see the report you just created listed in the Schedules table.

Click the Run link in the Actions column to run this report and then go to the Job Details page.

On the Job Details page, you see your report running.

When the report is generated, you will see a Links section in the summary section at the top of the Job Details page. This section contains a link to the report you generated. Click this link to see your report.

For more information about the Job Details page, click here . For more information about CloudBees Flow reports, see the Reports and other report Help topics.

Scenario extension—Add a thumbnail report to your Home page

When we created a report, we "checked" the Create thumbnail? checkbox, so we are ready to activate the thumbnail report view on the Home page.

Viewing an interesting report assumes there is ample data to report. While you can see a report after running one job, it is not very interesting unless you can see trends or comparisons after running numerous jobs.

To see a thumbnail report on the Home page:

  • Select the Home tab.

  • Click the Add Report link and a New Report page is displayed.

    On the New Reports page:

  • Project—Use the down-arrow to select the project containing the report you want to view—FirstNewProject.

  • Report—This is the report name you entered in the Report Title field when you configured this report—Basic Build Report.

  • Title—This is the report title you want to see on your Home page to identify this report. We used the same Basic Build Report name.

Click OK to generate the thumbnail report view and to go to the Home page.

The following screen example illustrates how your Home page may look with the thumbnail report.

For more information about how to use the Home page, see xref:help-home.adoc[Automation Platform Home Page] Help topic.

Summary

This scenario demonstrated how to create an Email Configuration so you could use an email notifier, how to create a continuous integration schedule, and how to set up a basic report with a "thumbnail" report view on your Home page.

Go to Scenario 4