Creating a Report

12 minute read

The DevOps Insight Report Editor lets you define a report based on criteria such as filters (search criteria), aggregations, and sorting. You create the query definition for a report by using the Report Editor.

These reports are based on Elasticsearch Query DSL and provide an interface to common Elasticsearch queries. The Report Editor includes an Advanced mode, which lets you edit the query DSL directly.

You can add, remove, or alter reporting filters or parameters for command center dashboards in the same manner as the standard types of dashboards. But you cannot add, remove, or alter reporting filters or parameters for the out-of-the-box Release Command Center dashboard. However, you can edit a custom copy of the Release Command Center dashboard, because CloudBees CD creates a copy of the Release Command Center dashboard when you edit and save it for the first time.

You select from a list of available reports when you create a DevOps Insight dashboard widget.

The Reports List

To open the reports list, click DevOps Analytics > Reports from the CloudBees CD main menu in the upper left corner of the CloudBees CD UI: the reports list opens.

The reports list shows all of the reports that are available in the currently-selected project or projects. The list comprises reports included with CloudBees CD as well as any custom reports that you have created. By default, the reports are listed for all projects. You can filter this list by any combination of projects via the projects menu.

A variety of out-of-the-box reports are included with CloudBees CD. These reports can help you learn about the reporting functionality and how to create your own reports. You can also make copies of these reports to use as templates for creating reports. These reports are in the Electric Cloud project and are not editable.

Click the Views button of a specific report for quick access to its Report Editor or Tabular Preview.

Creating a Custom Report

To create a report:

  1. From within the reports list, click the New button.

  2. Click Report > Create New…. The DevOps Insight Report Editor appears.

    This shows the standard editing mode, which is the default mode when you open the Report Editor. The editor lets you define any number of search criteria and aggregation types for creating custom reports.

Editing a Report’s Query by Using Standard Mode

  • Use the Report Editor to create your report’s query. As you create the report, the Code View window shows a read-only view of the underlying DSL code for your query. This view changes dynamically as you modify the report.

  • Click the Save button on the right side of the page to save your changes: you must save the report if you want to subsequently edit the underlying DSL code directly.

Report Search Criteria

The list of search criteria determines the matching for specific object attribute values. You can add one or more search criteria by clicking the Search Criterion button in the Report Editor.

Object Attribute Fields

The Fields pulldown menu displays the list of available object attributes. Examples are Application ID, Job Name, Planned Start Time, Task Type, and Wait for Planned Start.

If the pipeline run, job, or process has output parameters, they appear in the Fields pulldown menu and can be used in the report definition just like any other field. For example, for an output parameter named test, Output Parameter: test is available from the menu. If a desired output parameter is not available in this list, see Sending Additional Data for Pipeline Runs, Deployments, and Jobs to the DevOps Insight Server for instructions.

Search Operators

The following search operators are available:

Operator Applicable Attribute Data Types

Equals

All

Exists

All

Not Exists

All

Greater than

All data types except BOOLEAN

Greater than or Equals

All data types except BOOLEAN

Less than

All data types except BOOLEAN

Less than or Equals

All data types except BOOLEAN

Between

All data types except BOOLEAN

Values to Match

The field in the Value column represents the particular search value to match.

Adding Search Conditions

You can add conditions to the search criteria by clicking the Add Condition button:

Aggregations and Sorting

Aggregations and sorting determine the grouping or order of the query results, respecteively. You can choose either aggregation or sorting, but not both.

Query Result Aggregations

You can add aggregations by clicking the Add Aggregation button.

You can add functions by clicking the Add Function button. The following functions are available:

Function Applicable for Attribute Types

Average

NUMERIC, PERCENT

Count

All

Distinct Count

All

Max

NUMERIC, PERCENT, DATE, DATETIME

Min

NUMERIC, PERCENT, DATE, DATETIME

Sum

NUMERIC, PERCENT

Query Result Sorting

As an alternative to aggregating the query results, you can sort them. For example:

You can sort the query results by a specific object attribute field in ascending or descending order. You can specify the number of rows for the query to return. Up to 10000 rows can be returned.

To add a secondary sorting field, click the Add Sorting Field button:

Editing a Report’s Query DSL Code Directly by Using Advanced Mode

Advanced mode shows a view of the underlying query DSL code. You enter and exit advanced mode by clicking the Advanced slider button in the upper right corner of the UI. You can now edit the query DSL code directly.

Note that editing the query DSL code makes it incompatible with Standard mode in the Report Editor. The following warning is always present in Advanced mode as a reminder:

Note: If you make modifications in Advanced Mode and save them, they will not carry over to the Query Editor.

For details about Elasticsearch Query DSL, see the "Elastic Stack and Product Documentation" web page at https://www.elastic.co.

Previewing Report Query Results by Using Tabular Preview

To check your query results, click the Tabular Preview button at the top of the page. This view shows the first 20 rows of output so that you can test your report criteria. The tabular preview provides a preview of the report data from the DevOps Insight server.

The tables in the following examples describe some of the columns that might be returned based on the report that you have defined.

Example Report: AverageDeploymentDuration

This report is included in DevOps Insight.

The following table shows some of the date-based fields stored in Elasticsearch for this report and their corresponding formatted fields.

Column Description

Total

Number of records that matched the report search criteria

<given date field>.

such as Deployment Date

Date in milliseconds since the epoch. This is the raw data as stored in Elasticsearch. For aggregated data, the column representing this data also has an equivalent column (named Deployment Date Label, for example) in which this data is converted to a user-friendly date

<given date field>Label

such as Deployment Date Label

Date formatted as yyyy-MM-dd

Example Report: TopAppsByDeployments

This report is included in DevOps Insight. This is an example of a report containing aggregations.

Column Description

Total

Number of records that matched the report search criteria

<aggregation field>Count

such as Deployment Outcome Count

Number of records that fall into the aggregation bucket. For example, if you define a group by aggregation on deployment outcome, then for each unique deployment outcome such as success and warning, the Deployment Outcome Count column will return the number of deployments that completed with that deployment outcome

Sending Additional Data from Pipeline Runs, Deployments, and Jobs

The data that CloudBees CD manages for CloudBees CD runtime objects (pipelines, jobs, and deployments) and sends automatically to the DevOps Insight server is predetermined based on the specific object type. However, adding output parameters to the runtime objects of your choice in the CloudBees CD Deploy UI lets you capture their data so that it is sent to DevOps Insight in the same payload that is normally sent by CloudBees CD for these objects. In this way, output parameters provide an extensible mechanism for adding fields for these objects to a report.

Adding an output parameter to a report is much simpler than adding an input parameter, because you actually create the output parameter ahead of time outside of the Report Editor. To send additional data from pipeline runs, deployments, and jobs to the DevOps Insight server:

Prerequisites to Make Output Parameters Available in DevOps Insight

  • Declare the output parameter on the desired runtime object in the Floy UI at the object level.

    For details, see "Declaring an Output Parameter" in the CloudBees CD User Guide .

  • Set the output parameter’s value in some manner on the object.

    For details, see "Creating or Editing an Output Parameter" in the CloudBees CD User Guide .

    The menu display name for any output parameter that is available for use in reports is Output Parameter: < parameter_name >. For example, for an output parameter created in the CloudBees CD UI named test, the menu display name in the Report Editor is Output Parameter: test. ++ Output parameters are sent as regular fields in the payload but are prefixed with ec_param_ for identification purposes. For example, for an output parameter named test, the value is saved as ec_param_test in the DevOps Insight server:

  • Run the pipeline, job, or deployment .

    For details, see "Running Pipelines" in the CloudBees CD User Guide .

After the first runtime of that object, the parameter is pushed to the DevOps Insight server and is then available for addition to a report.

Adding the Output Parameters to a Report

Creating a Custom Report from an Existing Report

Copying another report lets you create a custom report more quickly. You can copy your custom reports as well as reports that are included with CloudBees CD. You cannot edit reports that are included with CloudBees CD, but copying them provides a substitute for customizing their functionality while preserving them to use as templates for future custom reports.

  1. From within the Reports list, click the New DevOps Insight Dashboard or Report ) button.

    This button is also available in the DevOps Insight Dashboards list and any DevOps Insight dashboard.
  2. Click Report > Copy Existing: the From Report dialog box appears.

  3. Click the name of the report that you want to copy.

    You can narrow down the list of projects by selecting one or more projects from the projects pulldown menu or by entering search terms into the Search field: the New Report dialog box appears.

  4. Enter the new report name into the dialog box, and then select the project that will contain the report.

    By default, new reports are added to the Electric Cloud project. You can enter a report description into the comments field if needed.

  5. Click OK to save your changes: the new report appears in the Report Editor.

  6. Customize the new report’s query as described in Report Search Criteria .

Editing a Custom Report

Any custom report is editable. To edit a report:

  • Open the Reports List as described in The Reports List .

  • Do one of the following to open the Report Editor:

    • Click the report.

    • Click the corresponding view selector button for the report, and select Report Editor.

  • Edit the report as described in Editing a Custom Report .

Adding Input Parameters to Reports

Parameters are free-form input values that can be fed to a dashboard or report to filter the data based on the parameter value. For example, the Release Command Center dashboard shows metrics and trends over the last 10 days.

You might want to view the trend over a different time interval such as the last month or last two weeks based on the duration of your releases. In this case, parameters let you define the time interval as a parameter that can be used by the dashboard or report viewer to change the time interval for viewing the Release Command Center metrics.

To add a parameter, open the Parameters dialog, click on the object menu located in the upper right corner of the report editor, and select Parameters.

  1. Click Add, or if no parameters have not yet defined for the object, click There are no Parameters yet. Add one + to add a parameter: the New Parameter dialog box opens.

  2. Enter the following information. In addition to the information below, several input fields have tool tips, denoted with , with additional information to help you. Click OK when finished with the parameter definition.

    Field Name Description

    Name

    A unique name for the parameter.

    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.

    This description renders as a tool tip for the parameter at object runtime.

    You can include hyperlinks as part of an object description for any CloudBees CD object.

    Label

    (Optional) The label for this parameter as it appears on the parameters panel at object runtime.

    Parameter Type

    Select the parameter type from the drop-down menu. The following types are available.

    Application

    Creates an Application drop down to select an application object. In order to use this parameter type, you need to first provide a way for the user to select the application’s project via a Project, Dropdown Menu, or Text Entry parameter.

    Note: not available for Dashboard or Report objects.

    Checkbox

    Creates a checkbox for a value to select (or not) when the parameter is presented.

    • Value when unchecked —The value of the parameter when the checkbox is unchecked.

    • Value when checked —The value of the checkbox when the checkbox is selected.

    Credential

    Selecting this option requires the user to specify a user name and password to use this parameter at runtime.

    Note: not available for Dashboard or Report objects.

    Date

    Allows for a date value to be selected using a date chooser. The selected date value is in ISO 8601 yyyy-MM-dd .

    Dropdown Menu

    Creates a drop-down menu from which to select a value when the parameter is presented.

    • Enter options —Click Add Option + to add a new row. Type-in the text and value for each option. The text is what will be displayed in the menu, and the value is the parameter value if that option is selected.

    • Load options from list —Enter a pipe-separated list of options (for example, foo|bar|baz ). The text and value for the options will be the same.

    • Load Options from Properties —Enter the path to property sheet that contains options for the parameter. This selection has two choices.

    • Load options using fixed structure:

    The options to display for the Parameter are determined using the following properties that must exist within the property sheet.

    optionCount=<Number of available options, e.g., 3> option1/ text=<Text to display> value=<Parameter value to use> option2/ text=<Text to display> value=<Parameter value to use> ...and so on till optionN/ text=<Text to display> value=<Parameter value to use>
    • Options from a property sheet:

    Example 1: If the Property Sheet contains the following Properties:

    Version7=7.0 Version8=8.0 Version9=9.2 ...then the following options will automatically be displayed using the Property name as the text to display and the Property value as the Parametervalue to use. Version7 Version8 Version9

    Example 2: If the Property Sheet contains the following nested Property Sheets:

    Version7/ Version8/ Version9/ ...then the following options will automatically be displayed using the Property Sheet name as both the text to display as well as the Parameter value to use. Version7 Version8 Version9
    • Load options using DSL —Enter a DSL script that allows for dynamically populating the drop-down menu. Click the tooltip icon for this selection to see an example. Additional examples are available in the CloudBees CD API Guide at Using the CloudBees CD DSL.

    Environment

    Creates an Environment drop down to select an environment object. In order to use this parameter type, you need to first provide a way for the user to select the object’s project via a Project, Dropdown Menu, or Text Entry parameter.

    Note: not available for Dashboard or Report objects.

    Header

    Used to render a heading. When rendered, this header is positioned before one or more parameters based on its position in the parameter list. There is no other explicit association with other parameters.

    Integer

    Allows for an integer value.

    Microservice

    Creates a Microservice drop down to select an microservice object. In order to use this parameter type, you need to first provide a way for the user to select the object’s project via a Project, Dropdown Menu, or Text Entry parameter.

    Note: not available for Dashboard or Report objects.

    Pipeline

    Creates a Pipeline drop down to select an pipeline object. In order to use this parameter type, you need to first provide a way for the user to select the object’s project via a Project, Dropdown Menu, or Text Entry parameter.

    This is not available for Dashboard or Report objects.

    Project

    Creates a Project drop down to select a project name.

    Radio Selector

    Creates "radio" buttons to select an entry when the parameter is presented.

    • Enter options —Click + Add Option to add a new row. Type-in the text and value for each option. The text is what will be displayed in the menu, and the value is the parameter value if that option is selected.

    • Load options from list —Enter a pipe-separated list of options (for example, foo|bar|baz ). The text and value for the options will be the same.

    • Load options from property sheet —Enter the path to property sheet that contains options for the parameter. The property sheet must be created in a specific format:

    • An optionCount property must exist whose value is the number of options.

    • For each option, create a nested property sheet called option N, where N is the option number, starting with 1.

    • In each nested sheet, create two properties— text and value. The value of the property text will be displayed in the menu. The value of the property value is the parameter value if that option is selected.

    • If optionCount is set to 3, you must create three nested sheets— option1, option2, and option3.

    Release

    Creates a Release drop down to select an release object. In order to use this parameter type, you need to first provide a way for the user to select the object’s project via a Project, Dropdown Menu, or Text Entry parameter.

    Note: not available for Dashboard or Report objects.

    Text Area

    Allows for a longer text entry.

    Text Entry

    Allows for a short text entry.

    Default Value

    Default value to assign to the parameter if no explicit value is provided.

    Required

    Click the checkbox to select the parameter as required. A value must be provided for the parameter if it is required.

    Defer Expansion

    Determines whether to defer parameter value expansion when the parameter value contains $[].

    • If unchecked (default), expansion is not deferred and is done at the time the parameter value is passed to the process, procedure, task, and so on, depending on where the parameter was defined.

    • If checked, expansion is deferred and occurs when the process step, procedure step, and so on, executes.

    Custom Validation

    Provides run-time validation on parameters via a user-supplied DSL script. If selected, the Custom Validation dialog displays, allowing you to supply the validation DSL script.

    If left empty, no validation occurs.

    Click the tooltip icon for this selection on the New Input Parameter dialog to see examples.

    Render Condition

    Render this parameter based on the condition of another parameter. For example, render this parameter if anotherparam equals 10.

    If left empty, this parameter renders by default.

    Click the tooltip icon for this selection to see examples.

    Dependencies

    One or more formal parameters on which this parameter depends on for custom validations or for rendering drop-down options using DSL. For an example, see the "createFormalParameter" section of the CloudBees CD API Guide on this page: Parameter Management.

    If left empty, this parameter renders by default.