Extending the data model

3 minute readDeveloper productivityData analytics

The CloudBees Analytics server database is populated with data from managed objects and configured plugins, as described in Understanding 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

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

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 Creating 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 Custom dashboards 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"}' ...