Lesson 1 Defining a custom metric#

Create a metric definition that you will upload to UrbanCode™ Velocity.

Before you begin

Before you begin this lesson, make sure that you configure your tutorial environment.

About this task

A metric definition is a JSON object, which is a collection of name-value pairs. For information about the structure of metric definitions, see Implementing custom metrics. For information about JSON itself, visit the JSON organization.

To define a metric definition, you set chart defaults and specify an ID that UrbanCode Velocity can use to associate metric records with the metric type. When you are done, you will use the definition in a curl command that loads it into the product.

To create a metric definition, complete the following steps:


  1. Open a text editor and save the blank file as a JSON-type file, for example myMetricDefinition.json.

  2. In myMetricDefinition.json, define the ID for the metric definition: "id": "TUTORIAL_DEFINITION",.

    The ID can contain any string value.

  3. On the second line, specify a name for the metric definition: "name": "Tutorial definition",.

    The name property can contain any string value. Metric records can be associated with metric definitions by using the name or ID properties.

  4. Specify the metric category: "category": "quality",.

    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. The chart that we create in this tutorial will be added to the list of Quality charts.

  5. Specify the tenant ID: tenantId":"my_UCV_TenantID.

    This property identifies your UrbanCode Velocity installation. Use the value that you retrieved in the configuration topic.

  6. Specify the chart default properties.

    This JSON object sets the chart type and determines how data is grouped. The tutorial chart aggregates data by result. Other groupings, such as team, status, or name, can be useful for other data types. Currently, UrbanCode Velocity provides line- and bar-type graphs. Set the default chart type to bar but users can change it after you add the chart to the dashboard.

    "chartDefaults":{ "groupBy":"result", "chartType":"bar", "barMode": "stack" },

  7. Set the aggregation operation property.

    "aggregation":{ "operation":"sum" }

    This property sets the default aggregation logic that is used when multiple records are loaded.

  8. Save the metric definition.


The metric definition that you created will be applied to the data record sent to UrbanCode Velocity in a later lesson.

The following code fragment shows the metric definition that we created in this lesson.

        "id": "TUTORIAL_DEFINITION",
        "name":"Tutorial Definition",
        "category": "quality",
          "barMode": "stack"

What to do next

In the next lesson, we create a curl request with the metric definition and load the definition into UrbanCode Velocity.

Parent topic: Implementing custom metrics