Extend the data model

The CloudBees Analytics server database is populated with data from managed objects and configured plugins, as described in Understand the CloudBees Analytics data model. This data is, in turn, visualized in widgets on a CloudBees Analytics server dashboard. Data from a user-defined, external source can also be injected into the database and visualized via custom widgets. This section describes how to extend the CloudBees Analytics data model by injecting user-defined custom data into the database.

Adding fields to CloudBees CD/RO managed objects

You can inject custom data to CloudBees CD/RO managed objects using CloudBees CD/RO output parameters. The following scenarios provide examples of how output parameters are useful:

I wrote a procedure that creates a number of properties in property sheets that is used in a later job creating a report. When writing the report procedure, I do not remember the exact name of property sheets and hierarchy that I am creating. I have to go back to the procedure code to copy and paste the names.
I am calling a plugin to run a set of tests from my pipeline task. In the automated exit gate condition, now I need to reference the result property generated by the plugin but do not know its name or how or where it is stored.
I am calling a common utility procedure written by other team members and need to use the output values.

The table below shows the relationship of output parameter declaration to the resulting report object type.

Declare in Define in Report object type

Declare in	Define in	Report object type
procedure	procedure command step	`job`, `deployment`
application process	application process command step	`job`, `deployment`
pipeline	pipeline command task	`job`, `pipelinerun`, `release`

procedure

procedure command step

job, deployment

application process

application process command step

job, deployment

pipeline

pipeline command task

job, pipelinerun, release

Adding fields leverages the setOutputParameter API command, regardless of the context. For more information about this command, refer to the CloudBees CD/RO APIs. The three sections below provide an overview of setting an output parameter.

With the UI

Declare an output parameter at the procedure, application process, or pipeline level object level.
Invoke the setOutputParameter API command as the command to execute on a procedure command step, application process command step, or a pipeline command task. The command looks something like this:
```
ectool setOutputParameter param1 "output value 1"▼
```
Using the report editor, peruse the report data type corresponding to the runtime object containing the parameter data. Your custom data is injected into the field name

Output Parameter: <parameter_name>.

With the API

ectool setOutputParameter param1 "output value 1"▼

With DSL

In any DSL editor instance within CloudBees CD/RO, enter a DSL script similar to the following:

project "TestProj",{
  procedure "TestProc",{
    formalOutputParameter "param1"
    step "Test", command: 'ectool setOutputParameter param1 "output value 1"'
  }
}▼

Accessing the data

Using the report editor, peruse the report data type corresponding to the runtime object containing the parameter data. Your custom data is injected into the field name prefaced by Output Parameter:.

Output Parameter: <parameter_name>

It is ready to be used in reports and widgets just like any other field.

Sending data from an external source

With CloudBees Analytics, you have the ability to inject user data based on your custom schema. You create a custom report object type corresponding to your data schema. From there, create custom dashboard widgets to visual your data.

Information in this section uses custom data based on this schema:

Field Name	Type	Required
featureName	STRING	yes
issues	NUMBER	yes

Field Name

Type

Required

featureName

STRING

yes

issues

NUMBER

yes

Configure CloudBees Analytics to receive your data.

Create a report object type to hold your schema using the createReportObjectType API command. For this example, the report object type name is cust_market_stats.
```
ectool createReportObjectType "cust_market_stats" --displayName "Market Stats"▼
```
Define fields in the report object type using the createReportObjectAttribute API command. Issue this command once for each field.
```
ectool createReportObjectAttribute featureName cust_market_statsectool createReportObjectAttribute issues cust_market_stats▼
```
Create the report that sources its data from your new report type using either the createReport API command or via the UI. Refer to Create a report for details. In overview, here is the API command:
```
ectool createReport "Default" "Market Stats" --reportObjectTypeName "cust_market_stats"▼
```
Create or modify a dashboard to store the widget visualization for your new report type. Use either the createDashboard API command or the UI. Refer to Create a customized CloudBees Analytics dashboard for details.
Create a widget to visualize your data. Use either the createWidget API command or via UI.

Send data to the reporting server. Use the sendReportingData API command to send your own data. Issue this command for each data record you wish to send. This example sends two records:

ectool sendReportingData "cust_market_stats" '{"featureName": "purple raincoat", "issues": "152"}'
...▼

ectool sendReportingData "cust_market_stats" '{"featureName": "green skirt", "issues": "249"}'
...▼