Implementing custom metrics

Provide custom metric data to your value streams and dashboards.

Custom metric definitions can be defined in the value_stream.json file attached to a value stream. You can add graphs or charts derived from the data to dashboards, the value stream Metrics bar, or the list view on the Value Streams page.

Note: Until new users are assigned to teams, they are automatically assigned to the Default team in the Viewer and Participant roles. Users in these roles can view objects, such as releases and value streams, but they cannot create or edit them. Additionally, users in these roles can generate user access tokens and access API endpoints with GET requests. Administrators grant users elevated permissions when they assign them to roles such as Lead Developer or Release Manager.

The following steps describe how to add custom metric data to HCL™ Accelerate:

  1. Using the properties defined later in this topic, define a custom metric definition.
  2. Upload the metric definition to HCL™ Accelerate.
  3. Send data to HCL™ Accelerate that conforms to the metric definition.
  4. Add charts based on the custom data to value streams and dashboards.

Metric definition properties

Metric data properties are described in the following table:

Table 1. Value stream metrics properties
Property Description
id This string-type property is used to link metric records to the metric definition. Required.
name This string-type property identifies the metric definition. The name appears in the Add charts area of the Dashboards page. Required.
category This string-type property defines the category to which the metric definition belongs. The categories are listed in the Add charts area of the Dashboards page. Possible values include: quality, deliveryFlow, risk, team, and effort. Required.
tenantId This string-type property is generated by HCL™ Accelerate and is used by the product to identify your installation. You can find your tenant ID by downloading a value stream JSON file. Required.
valueType This string-type property indicates the expected value of the metric data. Possible values include: percent, countset, and count.
chartDefaults This JSON object sets default options for the chart associated with the metric definition. The object properties are: groupBy (string), chartType (bar or line), barMode (stack or group), and threshold (number).
aggregation This JSON object sets the default aggregation logic.
createdBy Name or ID of the metric definition creator. String
description Metric definition description. String.

Example metric definition

The following example shows the curl command for a metric definition. HCL™ Accelerate uses the "Authorization: UserAccessKey" property to authenticate client access. You can create an user access token on the User Access Keys page, Settings > My Profile.

 curl -X POST "https://localhost/api/v1/metricDefinition" \
  -H "accept: application/json" \
  -H "Authorization: UserAccessKey my_user_access_key" \
  -H "Content-Type: application/json" \
  -k \
  -d '{
        "id": "MY_CUSTOM_DEFINITION",
        "name":"My Custom Definition",
        "category": "quality",
        "tenantId":"my_UCV_TenantID",
        "chartDefaults":{
          "groupBy":"result",
          "chartType":"bar",
          "barMode": "stack"
        },
        "aggregation":{ 
          "operation":"sum"
        },  
        "createdBy": "A. Coder", 
        "description": "New custom metric",  
      }'