Creating a new dashboard

11 minute readDeveloper productivityData analytics

When creating a dashboard, you can select a project to contain the dashboard, name the dashboard, and add one or more widgets, which displays the data that you select. You can also add input parameters to a dashboard.

You can create a widget or copy an existing widget for placement in a dashboard. For example, you might want to create a new dashboard consisting of a custom widget, two widgets from one dashboard, and two widgets from a second dashboard.

The Dashboards list

To open the Dashboards list, from the main menu select Analytics  Dashboards. The Dashboards list opens.

The Dashboards list shows all of the CloudBees Analytics dashboards that are available in the currently-selected project or projects. It includes the built-in dashboards and custom dashboards that you have created. By default, the dashboards are listed for all projects. You can filter this list by any combination of projects using the projects menu. For example, the following Dashboards list shows the reports in a project named Electric Cloud:

The Dashboards list
Figure 1. The Dashboards list

Built-in dashboards can help you learn about dashboard functionality and can serve as models to create your own custom dashboards. You can also make copies of these dashboards to use as templates when creating dashboards. These dashboards are in the Electric Cloud project and are not editable.

If you have customized the Release Command Center dashboard, your customization displays separately in this list and is marked with an identifying asterisk (Release Command Center *), in addition to the stock dashboard in the list. However, the Release Editor only displays one instance of the Release Command Center dashboard; either the built-in version or the customized version, if it exists. Precedence is given to the customized version of the Release Command Center dashboard if you created one. If a customized version does not exist, the built-in Release Command Center dashboard is loaded.

Creating a dashboard and assigning it to a project

  1. Select New to create a new CloudBees Analytics dashboard or report. The New Dashboard dialog displays.

  2. Select Create New.

  3. Enter the following details:

    • Name: The name of the dashboard to create. For special characters to avoid in names, refer to Using Special Characters in CloudBees CD/RO Object Names.

    • Select Project: The project associated with the dashboard.

    • (Optional) Description: A description of the dashboard.

    • Dashboard Type: The type of dashboard to create.

      • Standard: Non command-center dashboards such as Releases, Application Deployments, Microservice Deployments, Continuous Integration, or the Code Commit Trends dashboard.

      • Command Center: A command center type of dashboard.

        The Release Command Center is a built-in dashboard that has a special grid- and column-based layout, and is an example of this dashboard type.
  4. Select OK. One of the following displays, depending on your dashboard selection:

    • Dashboard Editor: The new dashboard displays in the Dashboard Editor

    • Command Center: For creating the first column for the new dashboard

  5. Proceed to either Configuring Command-center Dashboards or Configuring Standard Dashboards.

Configuring command-center dashboards

To create a cell in a command-center style of dashboard, you define its underlying widget. You can add, remove, or alter widgets for command center dashboards.

You can add or update columns for a command center type of dashboard using the dashboard editor. Also, you can add widgets that show metrics for any report object type, such as build or code-commit. The Release Command Center editor displays the widgets in different colors based on the object type of the backing report. In the example below, the User Stories widgets appear in blue, while the Test Automation widgets are displayed in pink:

Command-center style dashboard
Figure 2. Configuring a command-center style dashboard

Fill in the dialog for creating the first column for the new dashboard as follows:

  1. In the Name field, enter a name for the new column and select OK. The new column appears in the dashboard. For example

  2. Select New Widget to add a widget to a column and select Create New. The Edit Widget Details dialog for creating the first widget for the new dashboard appears. Supply details as shown in the table below.

    Menu or Field Description

    Name

    Name of the widget to create.

    Description

    (Optional) Description of the new widget.

    Place into…

    Header or column in which to add the new widget. Select Header or Column (the default), and then select the specific header or column.

    Widget position

    Location of the new widget in relation to another widget (if one already exists) that you choose via the Select Widget menu. You can ignore this setting if this is the first widget, because the menu is not yet populated with values. If there are existing widgets, you can select one of them from the menu.

    Add Another

    Button that opens a dialog to let you add another widget “on the fly” without exiting the Edit Widget Details dialog. This button lets you quickly populate a dashboard with numerous widgets.

    Define

    Button for opening the Edit Widget dialog (described below).

    Done

    Button that saves the changes that you made in the Edit Widget Details dialog.

  3. Complete the dialog as described above, and select Define. The Edit Widget Definition dialog for the new widget appears. The Details tab is pre-populated with the widget name and details that you previously entered, but you can modify them here if desired.

  4. Select the Definition tab. The Definition tab lets you enter the widget definition details such as the backing report and input parameters to use.

    Menu or Field Description

    Widget Title

    Title to be displayed on top of the widget in the dashboard UI.

    Filter by Project

    Limits the selection of reports and input parameters to a specific project.

    Report

    (Optional) Report used by the widget to retrieve data for visualization from the CloudBees Analytics server.

    For details about creating reports, refer to Creating a Report.

    You can select the Report Preview tab to view sample output based on the report you selected.

    Input Parameters

    Free-form input values that can be fed to a dashboard or report to “slice and dice” the data based on the parameter value. For example, metrics and trends over the last 10 days.

  5. Complete the fields in the Definition tab as needed.

  6. Select the Visualization tab. The Visualization tab lets you set up the type of visualization to use for rendering the data returned by the widget’s backing report. The Select Visualization menu provides a variety of widget visualizations such as Area Chart, Donut Chart, and Metric.

    Menu or Field Description

    Visualization Settings

    Visualization

    Image that previews the actual rendering of the widget as it appears in the dashboard.

    Display Trend Arrow

    Determines whether to display a trend indicator arrow, which shows the general direction of an already-formed trend:

    Trend Value

    (Available only if Display Trend Arrow is checked) Select this checkbox to display the trend column value next to the trend indicator arrow. From the Display Trend Value as menu that appears, you must select Number or Percent.

    Display icons using

    Icon to display along with the metric value.

    Metric Settings

    Select Type

    The choices are Single or Total.

    Select Column

    Column in which to place the widget.

    Select “Total” Column

    Field containing the total value on which the metric value is based. If set, this field appears along with the metric value as metric_value of total_value.

    For example, 7 of 10 Planning Complete.

    Display Metric as

    Type of unit for the metric. Valid values are None, Number, Duration, or Percent

    Trend Settings

    Select Trend Column

    Field to contain the trend value. If defined, it determines the direction for the trend indicator arrow on the widget

  7. Complete the Visualization tab as described above, and then select the Report Preview tab. This tab lets you preview the results of the report used by the widget to retrieve data for visualization from the CloudBees Analytics server. It lets you view the report data as you are defining the widget to know which columns to choose but is not meant as a preview for what will be saved.

  8. Select the Color Map tab. This tab lets you enter the range of background colors corresponding to metric column values.

    Menu or Field Description

    Color Range

    List of color ranges that are already specified.

    Add

    Color code for a specific range of values. For example, RGB 195, 232, 247 (light blue) for values greater than or equal to 90.

    The possible values are Greater than or equal to, Less than, or Between.

  9. Complete the Color Map tab as described above, and then select the Drill-Down tab. This tab lets you drill down into certain widgets in the columns for more information.

    Menu or Field Description

    Target

    Target page to navigate to when the user drills down from the widget. You can select Deployments, Microservice Deployments, External, Releases, or Pipeline Runs.

  10. Complete the fields and menu options in the Drill-down tab as follows. The exact set of menu options or fields in this section varies with the type of target that you select from the Target menu.

    Menu or Field Description, where more than field name is available)

    Target

    Page to navigate to when you drill down through the dashboard widget

    External URL

    External URL to navigate to

    Release Actual End Date Range - Minimum

    Minimum actual end date and time for the release

    Release Actual End Date Range - Maximum

    Maximum actual end date and time for the release

    Release Planned End Date Range - Minimum

    Minimum planned end date and time for the release

    Release Planned End Date Range - Maximum

    Maximum planned end date and time for the release

    Path to the Pipeline Task

    Field containing the / separated path to the pipeline task. For example, group1/parentTask1/task1.

    Each of these fields represents a field or column from the corresponding report definition that you created above. For example, in the Application Name field, you could enter ${applicationName}, where applicationName is a column in the report definition that you created in the Report section above.

    Also, for example, in the External URL field, you could enter ${drilldown_base_url}^incident_state=6^ORincident_state=7, where drilldown_base_url is a column in the report definition that you created in the Report section above.

  11. Select OK to save your changes.

  12. (Optional) Rearrange the widgets or columns in the new dashboard.

    You can select and drag a widget to move it from any part of the dashboard to a different part (section, column, or simply rearrange the order in a column).

    You can also delete an entire column by selecting Delete from the column’s menu:

    Delete an entire column
    Figure 3. Delete a column

    You can choose to move the deleted column’s widgets to another column rather than deleting them altogether.

Configuring standard dashboards

To create a cell, you define its underlying widget.

  1. Select New Widget to add a widget to a column and select Create New. A dialog for creating the first widget for the new dashboard appears.

  2. In the dialog for creating the first widget for the new dashboard, enter a name for the widget and select Define.

    The Edit Widget <widget_name> dialog for the new widget displays. You can change the name of the widget (in the Widget Name field) in this dialog and also add a description of the widget (in the Description field). Both of these fields are optional at this time, and you can change them later.

  3. Select the Definition tab.

    The Definition tab lets you enter the widget definition details such as the backing report and input parameters to use.

  4. Complete the fields in the Definition tab as needed.

  5. Select the Visualization tab. The Visualization tab lets you set up the type of visualization to use for rendering the data returned by the widget’s backing report. The Select Visualization menu provides a variety of widget visualizations such as Area Chart, Donut Chart, and Metric.

    Menu or Field Description

    Visualization Settings

    Visualization

    Image that previews the actual rendering of the widget as it appears in the dashboard.

    Display Trend Arrow

    Used to render a trend indicator arrow, which is based on the value of a report column that represents the trend. This arrow shows the general direction of an already-formed trend (meaning whether the numbers are going up or down over time).

    Trend Value

    (Available only if Display Trend Arrow is checked) Select this checkbox to display the actual trend value below the trend indicator arrow. This value is from a report column that represents the trend (whether the numbers are going up or down over time).

    From the Display Trend Value as menu that appears, you must select Number or Percent:

    Display icons using

    Icon to display on the widget (along with the metric value)

    Metric Settings

    Select Type

    The choices are:

    • Single: Renders a single metric (or “number”) such as number of builds or number of failed tests.

      If you choose Single, you must also choose the type of unit for the metric by selecting Number, Duration, or Percent from the Display Metric as menu.

    • Total: Renders a metric as “number”

      If you choose Total, you must also choose values from the Select Column and Select "Total" Column menus (described in this table)

    Select Column

    The column in which to place the widget.

    Select "Total" Column

    Field containing the total value on which the metric value is based. If set, this field appears along with the metric value as metric_value of total_value:

    For example, 7 of 10 Planning Complete

    Display Metric as

    Type of unit for the metric. Valid values are None, Number, Duration, or Percent.

    Trend Settings

    Select Trend Column

    Field to contain the trend value. If defined, it determines the direction for the trend indicator arrow on the widget.

  6. Complete the Visualization tab as described above, and then select the Report Preview tab.

    This tab lets you preview the results of the report used by the widget to retrieve data from the CloudBees Analytics server for visualization. It lets you view the report data as you are defining the widget to know which columns to choose, but it is not intended to be a preview for what will be saved.

  7. Select the Color Map tab.

    In the Color Map tab, you enter the colors used when rendering the widget. These colors are based on values returned by the widget’s backing report and correspond to metric column values. The exact set of fields in the Color Map tab varies with the type of visualization that you selected.

    Menu or field Description

    Color Range

    List of color ranges that are already specified.

    Add

    Color code for a specific range of values. For example, RGB 195, 232, 247 (light blue) for values greater than or equal to 90. The possible values are Greater than or equal to, Less than, or Between

  8. Complete the Color Map tab as described above, and then select the Drill-Down tab. This tab lets you drill down into certain widgets in the columns for more information.

    Menu or field Description

    Target

    Target page to navigate to when the user drills down from the widget. You can select Deployments, Microservice Deployments, External, Releases, or Pipeline Runs

  9. Complete the fields and menu options in the Drill-down tab as follows.

    The exact set of menu options or fields in this section varies with the type of target that you select from the Target menu.

    Menu or Field Description (where more than field name is available)

    Target

    Page to navigate to when you drill down through the dashboard widget

    Deployment Outcome

    Deployment outcome

    Application Project Name

    Application project name

    Application Name

    Application name

    Environment Project Name

    Environment project name

    Environment Name

    Environment name

    Deployment Date Range - Minimum

    Minimum deployment date

    Deployment Date Range - Maximum

    Maximum deployment date

    Microservice Project Name

    Microservice project name

    Microservice Name

    Microservice name

    Cluster Name

    Cluster name

    External URL

    External URL to navigate to

    Release Project Name

    Release project name

    Release Name

    Release name

    Release Actual End Date Range - Minimum

    Minimum actual end date and time for the release

    Release Actual End Date Range - Maximum

    Maximum actual end date and time for the release

    Release Planned End Date Range - Minimum

    Minimum planned end date and time for the release

    Release Planned End Date Range - Maximum

    Maximum planned end date and time for the release

    Pipeline Project Name

    Pipeline project name

    Pipeline Runtime Name

    Pipeline runtime name

    Pipeline Stage Name

    Pipeline stage name

    Path to the Pipeline Task

    Field containing the / separated path to the pipeline task. For example, group1/parentTask1/task1

    Each of these fields represents a field or column from the corresponding report definition that you created above. For example, in the Application Name field, you could enter ${applicationName}, where applicationName is a column in the report definition that you created in the Report section above.

    Also, for example, in the External URL field, you could enter ${drilldown_base_url}^incident_state=6^ORincident_state=7, where drilldown_base_url is a column in the report definition that you created in the Report section above.

    You can also enter hardcoded values into certain fields. For example, in the External URL field, you could enter https://10.200.1.171:8081/job/TestProject.

  10. Select OK to save your changes.

  11. (Optional) Select Add Widget to add additional widgets to the dashboard, and then repeat the prior steps to create the widgets.

You can also create a widget by copying a widget from another dashboard. For details, refer to Copying a widget.

Input parameters for a dashboard

Parameters are free-form input values that can be fed to a dashboard or report to customize 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. 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.

For details about how to add input parameters, refer to Adding Parameters.