Defining a metric and an indicator

Metric

Metric is an object which defines a computation that will be performed over the project's data and visualized in the map.

We have defined a metric that will tell us the number of customers. This is the most basic type of a metric. Let's have a look at the syntax:

Customers metric definition

CODE

{
    "name": "customers_metric",
    "type": "metric",
    "content": {
        "type": "function_count",
        "content": [
            {
                "type": "property",
                "value": "customers.customer_id"
            }
        ]
    }
}

This metric applies the function_count function to the customer_id property of our customers table. Simple as that.

We will save this metric as customers_metric.json to the /metadata/metrics directory and add it to the project using addMetadata.

Indicator

Indicator is linked to a specific Metric, and describes how it's results will be visualized in the map.

The most important content key is metric, which references the metric it visualizes. Note the $projectId placeholder, which is replaced by the real project ID during the push, and vice versa during the dump.

The scale will be standard, because count is a positive phenomenon. It will be displayed on the map in 5 blue colored segments. We will use geometric distribution of the data.

We have to allow the indicator to be visualized as dotmap and heatmap, like we've already allowed in the dataset earlier.

The format of the indicator value is a number and it will not have any places after the decimal point, so fraction is 0.

Customers indicator definition

CODE

{
    "name": "customers_indicator",
    "type": "indicator",
    "title": "Number of customers",
    "description": "Number of customers in the loyalty program",
    "content": {
        "metric": "/rest/projects/$projectId/md/metrics?name=customers_metric",
        "scale": "standard",
        "distribution": "geometric",
        "visualizations": {
            "dotmap": true,
            "heatmap": true
        },
        "format": {
            "type": "number",
            "fraction": 0
        }
    }
}

Save this indicator as customers_indicator.json to the /metadata/indicators directory and add it using addMetadata command.

Each indicator must have its corresponding indicator drill object. Indicator drills are covered in one of the following tutorials. But for now, we'll just add an empty_indicator_drill with empty content key to the project.

Empty indicator drill definition

CODE

{
    "name": "empty_indicator_drill",
    "type": "indicatorDrill",
    "content": {}
}

Save this indicator drill as empty_indicator_drill.json to the /metadata/indicatorDrills directory and add it using addMetadata command.

The final step is to modify the dashboard we've added in one of the previous chapters. We will put there the indicator we've just added. Please note you need to manually edit existing JSON file.

Please note that the id, accessInfo and links objects will be different, as they are generated and read only.

Updated Business overview dashboard definition

CODE

{
    "id": "j2idsg8tq7icp62f",
    "name": "business_overview_dashboard",
    "type": "dashboard",
    "content": {
        "blockRows": [
            {
                "type": "indicator",
                "indicator": "/rest/projects/$projectId/md/indicators?name=customers_indicator",
                "indicatorDrill": "/rest/projects/$projectId/md/indicatorDrills?name=empty_indicator_drill",
                "layout": "primary"
            }
        ]
    },
    "accessInfo": {
        "createdAt": "2020-06-23T17:26:08Z",
        "createdBy": "/rest/accounts/00ubfu7fdyIoFKxXm0h7"
    },
    "links": [
        {
            "rel": "self",
            "href": "/rest/projects/k5t8mf2a80tay2ng/md/dashboards/j2idsg8tq7icp62f"
        }
    ]
}

The content of a dashboard consists of blockRows array, which represents one row of indicators on the dashboard. There's a link to customers_indicator.json and to emtpy_indicator_drill.json. The layout of the indicator is primary. You will learn more about dashboards in one of the following tutorials.

Then use pushProject to push the changes to the previously added object.

We're there! Let's see CleverMaps in action in the last part of this tutorial.