Extending the Data Model

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

Adding Fields to Flow Managed Objects

You can inject custom data to Flow managed objects via Flow 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 will be 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 see the API Guide . 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 Flow, 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 DevOps Insight, 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 DevOps Insight 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. See 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 house the widget visualiation for your new report type. Use either the `createDashboard ` API command or via UI. See Creating a 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 sendReportingPayload --reportObjectType cust_market_data --payload ’{"featureName": "purple raincoat", "issues": "152"}’ectool sendReportingPayload --reportObjectType cust_market_data --payload ’{"featureName": "green skirt", "issues": "249"}’
...