Using the Groovy API

DevOps Insight

30 minute readReference
On this page

Dashboard Commands

createDashboard

Creates a new dashboard for the specified project.

You must specify projectName and dashboardName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Unique name of the dashboard within the projectName.

Argument Type: String

columns

(Optional) List of the columns to display for the dashboard of type COMMAND_CENTER.

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

layout

(Optional) Layout to use for adding the widgets to the dashboard. Use FLOW.

Argument Type: DashboardLayout

phases

(Optional) List of the phases to display for the dashboard of type COMMAND_CENTER.

This argument is deprecated and is replaced by columns.

Argument Type: String

type

(Optional) Type of dashboard. Allowed types: COMMAND_CENTER or STANDARD. If not specified, STANDARD is used.

Argument Type: DashboardType

Positional arguments

projectName, dashboardName

Response

Returns a dashboard object.

ec-perl

syntax: $<object>->createDashboard(<projectName>, <dashboardName>, {<optionals>});

Example
$ec->createDashboard("Default", "Executive Overview", {description => "Activity at a glance"});

ectool

syntax: ectool createDashboard <projectName> <dashboardName> [optionals]

Example
ectool createDashboard Default "Executive Overview"

createDashboardColumn

Creates a dashboard column in a Command Center type of dashboard.

You must specify projectName, dashboardName, and column.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Unique name of the dashboard within the projectName.

Argument Type: String

column

Name of the dashboard column.

Argument Type: String

afterColumn

(Optional) Name of the column after which the column should be placed. If neither beforeColumn nor afterColumn are specified, then the column is added as the last column in the dashboard.

Argument Type: String

beforeColumn

(Optional) Name of the column before which the column should be placed. If neither beforeColumn nor afterColumn is specified, then the column is added as the last column in the dashboard.

Argument Type: String

Positional arguments

projectName, dashboardName, and column

Response

Returns a dashboard column object.

ec-perl

syntax: $<object>->createDashboardColumn(<projectName>, <dashboardName>, <column>, {<optionals>});

Example
$ec->createDashboardColumn("Default", "Command Center Test", "Development", {afterColumn => "Planning"});

ectool

syntax: ectool createDashboardColumn <projectName> <dashboardName> <column> [optionals]

Example
ectool createDashboardColumn "Default" "Command Center Test" "Testing" --beforeColumn "SystemTest"

deleteDashboard

Delete the specified dashboard.

You must specify projectName and dashboardName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Unique name of the dashboard within the projectName.

Argument Type: String

Positional arguments

projectName, dashboardName

Response

None.

ec-perl

syntax: $<object>->deleteDashboard(<projectName>, <dashboardName>);

Example
$ec->deleteDashboard("Default", "Weekly Overview");

ectool

syntax: ectool deleteDashboard <projectName> <dashboardName>]

Example
ectool deleteDashboard "Default" "Weekly Overview"

deleteDashboardColumn

Deletes a dashboard column from a Command Center type of dashboard.

You must specify projectName, dashboardName, column, and deleteWidgets.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Unique name of the dashboard within the projectName.

Argument Type: String

column

Name of the dashboard column.

Argument Type: String

deleteWidgets

< Boolean flag0|1|true|false >

Whether to delete the widgets associated with the column that is being deleted. If you specify 0 or false and widgets exist in the column, you must also specify addToColumn.

Argument Type: Boolean

addToColumn

(Optional) Column to which the widgets associated with the column being deleted should be added. Required if deleteWidgets is 0 or false and widgets exist in the column.

Argument Type: String

Positional arguments

projectName, dashboardName, and column

Response

None.

ec-perl

syntax: $<object>->deleteDashboardColumn(<projectName>, <dashboardName>, <columnName>, {deleteWidgets ⇒ <0|1|true|false>, addToColumn ⇒ <column>});

Examples
$ec->deleteDashboardColumn("Default", "Command Center Test", "Development", {deleteWidgets => "false", addToColumn => "Planning"});
$ec->deleteDashboardColumn("Default", "Command Center Test", "Development", {deleteWidgets => "true"});

ectool

syntax: ectool deleteDashboardColumn <projectName> <dashboardName> <columnName> --deleteWidgets <0|1|true|false> [--addToColumn <column>]

Examples
ectool deleteDashboardColumn "Default" "Command Center Test" "Development" --deleteWidgets "false" --addToColumn "Planning"
ectool deleteDashboardColumn "Default" "Command Center Test" "Development" --deleteWidgets "true"

getDashboard

Get the specified dashboard.

You must specify the projectName and dashboardName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Unique name of the dashboard within the projectName.

Argument Type: String

includeDetails

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1,include propertySheet and widget details. If not specified, false is used.

Argument Type: Boolean

Positional arguments

projectName, dashboardName

Response

Returns a dashboard object.

ec-perl

syntax: $<object>->getDashboard(<projectName>, <dashboardName>, {includeDetails ⇒ <0|1|true|false>]});

Example
$ec->getDashboard("Default", "Weekly Overview", {includeDetails => true});

ectool

syntax: ectool getDashboard <projectName> <dashboardName> [--includeDetails <0|1|true|false>]

Example
ectool getDashboard Default "Weekly Overview" --includeDetails true

getDashboards

Get all dashboards or (optionally) dashboards for the specified project.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Positional arguments

None.

Response

Returns one or more dashboard objects.

ec-perl

syntax: $<object>->getDashboards, {projectName};

Example
$ec->getDashboards {projectName => Default};

ectool

syntax: ectool getDashboards [projectName]

Example
ectool getDashboards --projectName Default

modifyDashboard

Modifies an existing dashboard for the specified project.

You must specify the projectName and dashboardName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Unique name of the dashboard within the projectName.

Argument Type: String

clearColumns

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, columns are cleared. If not specified, false is used.

Argument Type: Boolean

clearPhases

(Optional) < Boolean flag0|1|true|false >

This argument is deprecated and is replaced by clearColumns.

When this argument is set to true or 1, phases are cleared. If not specified, false is used.

Argument Type: Boolean

columns

(Optional) List of the columns to display for the dashboard. Applies only to a COMMAND_CENTER type of dashboard.

Argument Type: Collection

customize

(Optional) < Boolean flag0|1|true|false >

Set to 1 or true to create a custom copy of the out-of-the-box Release Command Center dashboard.

Argument Type: Boolean

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

layout

(Optional) Layout to use for adding the widgets to the dashboard. Use FLOW.

Argument Type: DashboardLayout

newName

(Optional) New dashboard name.

Argument Type: String

phases

(Optional) List of the phases to display for a dashboard of type COMMAND_CENTER.

This argument is deprecated and is replaced by columns.

Argument Type: String

type

(Optional) Type of dashboard. Allowed types: COMMAND_CENTER, STANDARD. If not specified, STANDARD is used.

Argument Type: DashboardType

If customize is true, dashboardName is Release Command Center, and projectName is CloudBees, then a copy is created with a predefined name of Release Command Center in the CloudBees project. The associated reports are not cloned at the same time. If you need to modify the report definitions, you must create a copy of the report before changing it (as with other out-of-the-box reports).

Positional arguments

projectName, dashboardName

Response

Returns an updated dashboard object.

ec-perl

syntax: $<object>->modifyDashboard(<projectName>, <dashboardName>, {<optionals>});

Example
$ec->modifyDashboard("Default", "Executive Overview", {newName => "Weekly Overview"});

ectool

syntax: ectool modifyDashboard <projectName> <dashboardName> [optionals]

Example
ectool modifyDashboard Default "Executive Overview" --newName "Weekly Overview"

modifyDashboardColumn

Modifies a dashboard column in a Command Center type of dashboard.

You must specify projectName, dashboardName, and column.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Unique name of the dashboard within the projectName.

Argument Type: String

column

Name of the dashboard column.

Argument Type: String

afterColumn

(Optional) Name of the column after which the column should be placed. If neither beforeColumn nor afterColumn are specified, then the column is added as the last column.

Argument Type: String

beforeColumn

(Optional) Name of the column before which the column should be placed. If neither beforeColumn nor afterColumn are specified, then the column is added as the last column.

Argument Type: String

Positional arguments

projectName, dashboardName, and column

Response

Returns an updated dashboard column object.

ec-perl

syntax: $<object>->modifyDashboardColumn(<projectName>, <dashboardName>, <column>, {<optionals>});

Example
$ec->modifyDashboardColumn("Default", "Command Center Test", "Development", {afterColumn => "Planning"});

ectool

syntax: ectool modifyDashboardColumn <projectName> <dashboardName> <column> [optionals]

Example
ectool modifyDashboardColumn "Default" "Command Center Test" "Development" --beforeColumn "Production"

Data Source Commands

createDevOpsInsightDataSource

Creates a new data source for the specified project.

You must specify projectName, releaseName, and devOpsInsightDataSourceName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

devOpsInsightDataSourceName

Name of this data source.

Argument Type: String

description

(Optional) User-provided text describing this instance.

Argument Type: String

pluginKey

(Optional) Plugin key. For example, EC-MyPlugin.

Argument Type: String

pluginParameters

(Optional) Plugin parameters to be passed to the plugin for creating the required schedule and polling procedure.

Argument Type: Map

reportObjectTypeName

(Optional) Name of the report object type.

Argument Type: String

Positional arguments

projectName, releaseName, devOpsInsightDataSourceName

Response

Returns a devOpsInsightDataSource object.

ec-perl

syntax: $<object>->createDevOpsInsightDataSource(<projectName>, <releaseName>, <devOpsInsightDataSourceName>, {<optionals>});

Example
$ec->createDevOpsInsightDataSource("Default", "Executive Overview", {description => "Activity at a glance"});

ectool

syntax: ectool createDevOpsInsightDataSource <projectName> <releaseName> <devOpsInsightDataSourceName> [optionals]

Example
ectool createDevOpsInsightDataSource Default "Executive Overview"

deleteDevOpsInsightDataSource

Delete the specified data source.

You must specify projectName, releaseName, and devOpsInsightDataSourceName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

devOpsInsightDataSourceName

Name of this data source.

Argument Type: String

Positional arguments

projectName, releaseName, devOpsInsightDataSourceName

Response

None.

ec-perl

syntax: $<object>->deleteDevOpsInsightDataSource(<projectName>, <releaseName>, <devOpsInsightDataSourceName>);

Example
$ec->deleteDevOpsInsightDataSource("Default", "Weekly Overview");

ectool

syntax: ectool deleteDevOpsInsightDataSource <projectName> <releaseName> <devOpsInsightDataSourceName>]

Example
ectool deleteDevOpsInsightDataSource Default "Weekly Overview"

getDevOpsInsightDataSource

Get the specified data source.

You must specify projectName, releaseName, and devOpsInsightDataSourceName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

devOpsInsightDataSourceName

Name of this data source.

Argument Type: String

Positional arguments

projectName, releaseName, devOpsInsightDataSourceName

Response

Returns a devOpsInsightDataSource object.

ec-perl

syntax: $<object>->getDevOpsInsightDataSource(<projectName>, <releaseName>, <devOpsInsightDataSourceName>, {includeDetails ⇒ <0|1|true|false>]});

Example
$ec->getDevOpsInsightDataSource("Default", "Weekly Overview", {includeDetails => true});

ectool

syntax: ectool getDevOpsInsightDataSource <projectName> <releaseName> <devOpsInsightDataSourceName> [--includeDetails <0|1|true|false>]

Example
ectool getDevOpsInsightDataSource Default "Weekly Overview" --includeDetails true

getDevOpsInsightDataSources

Get all data sources or, optionally, data sources for the specified project.

You must specify projectName and releaseName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

reportObjectTypeName

(Optional) Name of the report object type for which to retrieve the DevOps Insight data sources defined for the release. If not specified, then all the DevOps Insight data sources defined for the release are retrieved.

Argument Type: String

Positional arguments

projectName, releaseName

Response

Returns one or more devOpsInsightDataSource objects.

ec-perl

syntax: $<object>->getDevOpsInsightDataSources, {projectName};

Example
$ec->getDevOpsInsightDataSources{projectName => Default};

ectool

syntax: ectool getDevOpsInsightDataSources [projectName]

Example
ectool getDevOpsInsightDataSources --projectName Default

modifyDevOpsInsightDataSource

Modifies an existing data source for the specified project.

You must specify projectName, releaseName, and devOpsInsightDataSourceName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

devOpsInsightDataSourceName

Name of this data source.

Argument Type: String

description

(Optional) User-provided text describing this instance.

Argument Type: String

newName

(Optional) New name for the data source that is being renamed.

Argument Type: String

pluginParameters

(Optional) Plugin parameters to be passed to the plugin for creating the required schedule and polling procedure.

Argument Type: Map

Positional arguments

projectName, releaseName, devOpsInsightDataSourceName

Response

Returns a devOpsInsightDataSource object.

ec-perl

syntax: $<object>->modifyDevOpsInsightDataSource(<projectName>, <releaseName>, <devOpsInsightDataSourceNameName>, {<optionals>});

Example
$ec->modifyDevOpsInsightDataSource("Default", "Executive Overview", {newName => "Weekly Overview"});

ectool

syntax: ectool modifyDevOpsInsightDataSource <projectName> <releaseName> <devOpsInsightDataSourceNameName> [optionals]

Example
ectool modifyDevOpsInsightDataSource Default "Executive Overview" --newName "Weekly Overview"

Report Commands

createReport

Creates a new report for the specified project.

You must specify projectName and reportName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

reportName

Unique name of the report within the projectName. This name appears in report lists.

Argument Type: String

definition

(Optional) The Elasticsearch query definition to use for retrieving the report data from the DevOps Insight server.

Argument Type: String

description

(Optional) Report description. If not specified, description is not set.

Argument Type: String

parameters

(Optional) Input parameters in JSON format accepted by the report definition. See Sample DSL below for expected format.

Argument Type: String

reportQuery

(Optional) The report query definition, in JSON format, to use for retrieving the report data from the DevOps Insight server. This definition can be built through the Report Editor.

Argument Type: String

title

(Optional) The title of the report. If not specified, title is not set.

Argument Type: String

One of the following is required.

reportObjectTypeName

Report object type name.

Argument Type: String

uri

An advanced mode option for identifying the Elasticsearch URI to use for retrieving the report result from the reporting system. For ElasticSearch, this attribute would point to one or more indices.

Argument Type: String

Positional arguments

projectName, reportName

Response

Returns a report object.

Sample DSL

report reportName: ‘AppsByDeploymentStatus’, projectName: ‘CloudBees’, {
  description: 'report desc'
  uri: 'ef-deployment-*/\_search?pretty'
  // report query definition to use when searching in ElasticSearch.
  definition: '''
{
    "query" : {
    ...
}
  ...
  parameters: ...
  [{
      name: 'appIdParam',
      label: 'Select application'
      // optional default value to use if none specified for runReport
      defaultValue: '',
      // the report should be able to handle he case where the parameter is not required and no optional value is specified.
      required: false,
      // parameter type. Supported types: 'text', 'dateRange', 'select', 'application', 'release', 'environment', 'pipeline'
      // parameter value will be based on the parameter type.
      // UI would need to support the different parameter types. For deploy types such as 'application', 'release', 'environment', 'pipeline',
      // the user should be presented with a chooser to select the application, release, etc and the selected object's id should be returned
      // as the parameter value.
      type: 'application',
      filterExpression: 'match: {"applicationId": "appIdParam"}'
   },
   {
   }]
  ...
}

ec-perl

syntax: $<object>->createReport(<projectName>, <reportName>, {<optionals>});

Example
$ec->createReport("Default", "All Pipeline Runs", {description => "Activity at a glance"});

ectool

syntax: ectool createReport <projectName> <reportName> [optionals]

Example
ectool createReport Default "All Pipeline Runs" --description "Activity at a glance"

deleteReport

Delete the specified report.

You must specify the projectName and reportName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

reportName

Unique name of the report within the projectName.

Argument Type: String

Positional arguments

projectName, reportName

Response

None.

ec-perl

syntax: $<object>->deleteReport(<projectName>, <reportName>);

Example
$ec->deleteReport("Default", "Weekly Overview");

ectool

syntax: ectool deleteReport <projectName> <reportName>]

Example
ectool deleteReport Default "Weekly Overview"

getReport

Get the specified report.

You must specify projectName and reportName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

reportName

Unique name of the report within the projectName.

Argument Type: String

Positional arguments

projectName, reportName

Response

Returns a report object.

ec-perl

syntax: $<object>->getreport(<projectName>, <reportdName>);

Example
$ec->getReport("Default", "All Pipeline Runs");

ectool

syntax: ectool getReport <projectName> <reportName>

Example
ectool getReport Default "All Pipeline Runs"

getReports

Get all reports from the specified project.

You must specify the projectName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Positional arguments

projectName

Response

Returns all report objects for the specified project.

ec-perl

syntax: $<object>->getReports(<projectName>);

Example
$ec->getReports("Default");

ectool

syntax: ectool getReports <projectName>

Example
ectool getReports Default

modifyReport

Creates a new report for the specified project.

You must specify the projectName and reportName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

reportName

Unique name of the report within the projectName. This name appears in report lists.

Argument Type: String

definition

(Optional) The Elasticsearch query or search definition to use for retrieving the required data for the reporting system.

Argument Type: String

description

(Optional) Report description. If not specified, description is not set.

Argument Type: String

newName

(Optional) New name for an existing object that is being renamed.

Argument Type: String

parameters

(Optional) Input parameters in JSON format accepted by the report definition.

Argument Type: String

reportObjectTypeName

(Optional) Name of the report object type.

Argument Type: String

reportQuery

(Optional) The report query in JSON format. It will be translated to the Elasticsearch query definition when retrieving report data.

Argument Type: String

title

(Optional) The title of the report. If not specified, title is not set.

Argument Type: String

uri

(Optional) An advanced mode option for identifying the Elasticsearch URI to use for retrieving the report result from the reporting system. For ElasticSearch, this attribute would point to one or more indices. If not specified, uri is not set.

Argument Type: String

Positional arguments

projectName, reportName

Response

Returns a report object.

ec-perl

syntax: $<object>->modifyReport(<projectName>, <reportName>, {<optionals>});

Example
$ec->modifyReport("Default", "All Pipeline Runs", {uri => "myreport/_search?pretty"});

ectool

syntax: ectool modifyReport <projectName> <reportName> [optionals]

Example
ectool modifyReport Default "All Pipeline Runs" --uri "myreport/_search?pretty"

runReport

Run the specified report.

You must specify the projectName and reportName.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

reportName

Unique name of the report within the projectName.

Argument Type: String

actualParameter

(Optional) Parameters passed as arguments to the report.

Argument Type: String

dashboardName

(Optional) The name of the dashboard that the widget using the report belongs to.

Argument Type: String

dashboardProjectName

(Optional) Specify if the dashboard is in a different project than the report.

Argument Type: String

definition

(Optional) The Elasticsearch query definition to use for retrieving report data.

Argument Type: String

filters

(Optional) Filters

Argument Type: String

previewMode

(Optional) <_Boolean flag_ — 0|1|true|false>

When this argument is set to true or 1,report is run in preview mode. If not specified, false is used. Preview mode returns a small result sample.

Argument Type: Boolean

reportObjectTypeName

(Optional) Report object type name

Argument Type: String

reportQuery

(Optional) The report query in JSON format. It will be translated to the Elasticsearch query definition when retrieving report data.

Argument Type: String

uri

(Optional) An advanced mode option for identifying the Elasticsearch URI to use for retrieving report data. By default, the reportObjectTypeName argument will be used to construct the URI based on the Elasticsearch index for the report object.

Argument Type: String

widgetName

(Optional) The name of the widget using the report.

Argument Type: String

Positional arguments

projectName, reportName

Response

Returns a report object.

ec-perl

syntax: $<object>->runReport(<projectName>, <reportName>);

Example
$ec->runReport (Default, "All Pipeline Runs");

ectool

syntax: ectool runReport <projectName> <reportName>

Example
ectool runReport Default "All Pipeline Runs"

sendReportingData

Sends data to the DevOps Insight server.

You must specify reportObjectTypeName and payload.

ArgumentsDescriptions

reportObjectTypeName

Name of the report object for which the data (payload) is being sent to the DevOps Insight server.

Argument Type: String

payload

Payload with the attribute values for the report object in JSON text format.

Argument Type: String

validate

(Optional) If set to true or 1, validate the fields in the payload based on the attributes defined for the report object type.

Default is false or 0.

Argument Type: Boolean

Positional arguments

reportObjectTypeName, payload

Response

None or a status OK message.

===Payload validation

By default, no validation is performed on payload. Setting the validate argument to true causes payload to be validated based on the attributes defined for the report object type.

ec-perl

syntax: $<object>->sendReportingData({reportObjectTypeName ⇒ <reportObjectTypeName>, payload ⇒ <payload>})

Examples
my $payload = qq{{
  "field1": "value1",
  "field2": "value2",
  "field3Integer": 25,
  "field4Date": "2018-02-28'T'20:25:50.555"
}}
$cmdr->sendReportingData({reportObjectTypeName => "sample", payload => $payload})

Each record in the DevOps Insight server is automatically assigned an identifier that uniquely identifies the record. For most types of records, you do not need to explicitly assign a user-defined identifier. Each record sent through the sendReportingData command is automatically assigned a unique identifier by the DevOps Insight server.

However if the records stored in the DevOps Insight server need to be uniquely identified using user-defined identifiers, then the documentId field can be sent as part of the payload in the sendReportingData API. For example:

my $payload = qq{{
  "documentId": "2319024098340985"
  "field1": "value1",
  "field2": "value2",
  "field3Integer": 25,
  "field4Date": "2018-02-28'T'20:25:50.555"
}}
$cmdr->sendReportingData({reportObjectTypeName => "sample", payload => $payload})

If a record already exists with the same documentId, then it will be updated. Otherwise, a new record will be created for the given documentId in the DevOps Insight server.

ectool

syntax: ectool sendReportingPayload --reportObjectType <reportObjectTypeName> --payload <payload>

Example
ectool sendReportingPayload --reportObjectType sample --payload ’{"documentId": "2319024098340985", "field1": "value1", "field2": "value2"}’

ReportingFilter Commands

createReportingFilter

Creates a new reportingFilter object.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Name of the dashboard to which this filter belongs.

Argument Type: String

reportingFilterName

Report object type for which this association is defined. The association is owned by the specified report object type.

Argument Type: String

description

(Optional) A user-defined description of this object.

Argument Type: String

operator

(Optional) Operator type to use when applying the filter to the report. Possible values are:

  • IN

  • EQUALS

  • BETWEEN

Attribute Type: String

orderIndex

(Optional) Order in which the reporting filter should be displayed.

Argument Type: Integer

parameterName

(Optional) Parameter name on which to filter. Required when type is set to DATE.

Argument Type: String

reportObjectTypeName

(Optional) The name of the report object type.

Argument Type: String

required

(Optional) < Boolean flag0|1|true|false >

Whether the filter is required and should be enforced on the client side UI.

When this argument is set to true or 1, the association must be present.

Default is false or 0.

Argument Type: Boolean

type

(Optional) The attribute type. Possible values:

  • DATE yyyy-MM-dd This is a special enum value and expects the attribute to be a string formatted using the ISO date format 'yyyy-MM-dd')

  • ENVIRONMENT

  • RELEASE

  • APPLICATION

Attribute Type: String

widgetName

(Optional) Name of the widget within the dashboard, if the reporting filter belongs to a widget.

Argument Type: String

Positional arguments

projectName, dashboardName, reportingFilterName

Response

Returns a reportingFilter object.

ec-perl

syntax: $cmdr->createReportingFilter(<projectName>, <dashboardName>, <reportingFilterName>, {<optionals>});

Example
$cmdr->createReportingFilter("Default", "ExecDashboard", "MonthlyRollup");

ectool

syntax: ectool createReportingFilter <projectName> <dashboardName> <reportingFilterName> [<optionals>]

Example
ectool createReportingFilter Default ExecDashboard MonthlyRollup

deleteReportingFilter

Deletes the specified reportReportingFilter object.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Name of the dashboard to which this filter belongs.

Argument Type: String

reportingFilterName

Report object type for which this association is defined. The association is owned by the specified report object type.

Argument Type: String

widgetName

(Optional) Name of the widget within the dashboard, if the reporting filter belongs to a widget.

Argument Type: String

Positional arguments

projectName, dashboardName, reportingFilterName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteReportingFilter(<projectName>, <dashboardName> , <reportingFilterName>);

Example
$cmdr->deleteReportingFilter("Default", "ExecDashboard", "MonthlyRollup");

ectool

syntax: ectool deleteReportingFilter <projectName dashboardName reportingFilterName> <associatedType>

Example
ectool deleteReportingFilter "Default", "ExecDashboard", "MonthlyRollup"

getReportingFilter

Retrieves the specified reportingFilter object.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Name of the dashboard to which this filter belongs.

Argument Type: String

reportingFilterName

Report object type for which this association is defined. The association is owned by the specified report object type.

Argument Type: String

widgetName

(Optional) Name of the widget within the dashboard, if the reporting filter belongs to a widget.

Argument Type: String

Positional arguments

projectName, dashboardName, reportingFilterName

Response

Returns the specified reportingFilter object.

ec-perl

syntax: $cmdr->getReportingFilter(<projectName>, <dashboardName> , <reportingFilterName>);

Example
$cmdr->getReportingFilter("Default", "ExecDashboard", "MonthlyRollup");

ectool

syntax: ectool getReportingFilter <projectName dashboardName reportingFilterName> <associatedType>

Example
ectool getReportingFilter "Default", "ExecDashboard", "MonthlyRollup"

getReportingFilters

Retrieves the specified reportingFilter objects.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Name of the dashboard to which this filter belongs.

Argument Type: String

widgetName

(Optional) Name of the widget within the dashboard, if the reporting filter belongs to a widget.

Argument Type: String

Positional arguments

projectName, dashboardName

Response

Returns zero or more reportReportingFilter objects.

ec-perl

syntax: $cmdr->getReportingFilters(<projectName>, <dashboardName>);

Example
$cmdr->getReportingFilters("Default", "ExecDashboard");

ectool

syntax: ectool getReportingFilters <projectName, dashboardName>

Example
ectool getReportingFilters Default ExecDashboard

modifyReportingFilter

Modifies the specified reportReportingFilter object.

ArgumentsDescriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

dashboardName

Name of the dashboard to which this filter belongs.

Argument Type: String

reportingFilterName

Report object type for which this association is defined. The association is owned by the specified report object type.

Argument Type: String

description

(Optional) A user-defined description of this object.

Argument Type: String

newName

(Optional) Used to rename this attribute.

Argument Type: String

operator

(Optional) Operator type to use when applying the filter to the report. Possible values are:

  • IN

  • EQUALS

  • BETWEEN

Attribute Type: String

orderIndex

(Optional) Order in which the reporting filter should be displayed.

Argument Type: Integer

parameterName

(Optional) Parameter name on which to filter. Required when type is set to DATE.

Argument Type: String

reportObjectTypeName

(Optional) The name of the report object type.

Argument Type: String

type

(Optional) The attribute type. Possible values:

  • DATE yyyy-MM-dd This is a special enum value and expects the attribute to be a string formatted using the ISO date format 'yyyy-MM-dd')

  • ENVIRONMENT

  • RELEASE

  • APPLICATION

Attribute Type: String

required

(Optional) < Boolean flag0|1|true|false >

Whether the filter is required and should be enforced on the client side UI.

When this argument is set to true or 1, the association must be present.

Default is false or 0.

Argument Type: Boolean

widgetName

(Optional) Name of the widget within the dashboard, if the reporting filter belongs to a widget.

Argument Type: String

Positional arguments

projectName, dashboardName, reportingFilterName

Response

Returns a reportingFilter object.

ec-perl

syntax: $cmdr->modifyReportingFilter(<projectName>, <dashboardName>, <reportingFilterName>, {<optionals>});

Example
$cmdr->modifyReportingFilter("Default", "ExecDashboard", "MonthlyRollup", newName => "AprilRollup");

ectool

syntax: ectool modifyReportingFilter<<projectName dashboardName reportingFilterName> [<optionals>]

Example
ectool modifyReportingFilter Default ExecDashboard MonthlyRollup --newName AprilRollup

Report Object Type Commands

createReportObjectType

Creates a new reportObjectType object.

You must specify reportObjectTypeName.

ArgumentsDescriptions

reportObjectTypeName

Name of the report object type. No special characters or uppercase characters are allowed. Valid characters include [a-z][0-9][-].

Argument Type: String

colorCode

(Optional) Color associated with the report object type in hex code format \#rrggbb.

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

displayName

(Optional) Display name of report object type.

Argument Type: String

sourceType

(Optional) Category of the third-party tool from which data for the given report object type is obtained.

Argument Type: String

sourceTypeDescription

(Optional) Description of the category of the third-party tool that may be displayed on the UI.

Argument Type: String

storagePattern

(Optional) Time-based storage pattern used for storing the report object type data. This field, if set, is used by ElasticSearch as the index name pattern.

The valid values are NONE, YYYY, YYYY_MM, or YYYY_MM_dd. Defaults to YYYY.

Argument type: ReportObjectTypeStoragePattern

Positional arguments

reportObjectTypeName

Response

Returns a reportObjectType object.

===DSL Example of a report object type definition

reportObjectType 'cust_market_stats', {
  description = 'Application features delivered as part of a release'

  reportObjectAttribute 'featureName', {
   type = 'STRING'
   required = true
  }
  reportObjectAttribute 'issues', {
   type = 'NUMBER'
   required = true
  }
reportObjectAssociation 'release', {
   sourceFields = 'releaseName, releaseProjectName'
   targetFields = 'releaseName, releaseProjectName'
   required = true
  }

  reportObjectAssociation 'application', {
   sourceFields = 'applicationName, projectName'
   targetFields = 'applicationName, applicationProjectName'
  }
}

ec-perl

syntax: $cmdr->createReportObjectType(<reportObjectTypeName>, {<optionals>});

Example
$cmdr->createReportObjectType("feature", {colorCode => #ff0000});

ectool

syntax: ectool createReportObjectType <reportObjectTypeName> [<optionals>]

Example
ectool createReportObjectType "feature" --colorCode #ff0000

deleteReportObjectType

Deletes the specified reportObjectType object.

ArgumentsDescriptions

reportObjectTypeName

The name of the reportObjectTypeName object to delete.

Argument Type: String

Positional arguments

reportObjectTypeName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteReportObjectType(<ReportObjectTypeName>);

Example
$cmdr->deleteReportObjectType("feature");

ectool

syntax: ectool deleteReportObjectType <ReportObjectTypeName>

Example
ectool deleteReportObjectType "feature"

getReportObjectType

Retrieves the specified reportObjectType object.

ArgumentsDescriptions

reportObjectTypeName

The name of the reportObjectType object to retrieve.

Argument Type: String

includeDetails

(Optional) < Boolean flag0|1|true|false >

true to include details such as report object association details (default is false or 0 ).

Argument Type: Boolean

Positional arguments

reportObjectTypeName

Response

Returns the specified reportObjectType object.

ec-perl

syntax: $cmdr->getReportObjectType(<reportObjectTypeName>, {<optionals>});

Example
$cmdr->getReportObjectType("feature", {includeDetails => "true&q