Reporting

Reports, also known as report types, are the main components of a connector and define:

• How data is requested from the API

• How the received data is read and interpreted

• What fields are made available in the connector

A connector can have one or multiple report types, and one report type typically requests data from a one endpoint. If you have multiple endpoints you need data from, you can add multiple report types to the connector.

Note

You will need to configure at least one report type to your connector. Otherwise, the connector does not know what data to fetch.

Report type configuration allows you to tailor your connector to fit the requirements of the data source API, be it a simple GET request with JSON response, or a more complex asynchronous reporting flow with zipped CSV as response.

How report types are shown in Supermetrics

Report types are visible for the user when they’re building a query in Supermetrics products. All the configured report types are selectable as a dropdown after authenticating to the connector.

Structure of report type configuration

Your connector can have one or multiple report types that are configured as an array under the reporting object.

 "reporting": {
        "reportTypes": [
        {
        "id": "report_type_1",
        "title": "1st report type"
        },
        {
        "id": "report_type_2",
        "title": "2nd report type"
        }
        ]
        }

Under each report type, you can then define report type-specific requests, settings, configurations, and fields.

Below, we’ll walk you through all the most essential configuration options.

Basic configurations

Date range configuration

Most of the datasets that you work with contain one or multiple date values, for example:

• Campaign performance data broken down by date

• Ecommerce order data containing order creation date, modification date, and shipping date

Most of the APIs also allow you to filter the data by date already in the data fetching request. In this section, we’ll instruct you on how to configure date range filtering for your connector.

Configuring date range filtering involves a few steps:

1. Enabling date range filtering and default date fields in the connector

2. Configuring start and end date parameters to be sent as part of the request

3. Defining the field that is used to filter the data by date

Let’s go through each of the steps.

Step 1: Enable date range filtering and default date fields in the connector

For the connector to show a date range selection when building a query, the date range filtering must be enabled in the connector. Below you can see an example on how a report type with or without date range filtering looks when using a connector. When the API provides date-based data, we also usually configure a default set of date fields to be available for the user of the connector, which allows users to aggregate the data for different time granularities (date, week, month, year, and so on).

To enable showing the date range selection and default date fields in the connector, we need to configure showDateRange and showDefaultDateFields under config for a report type. Like this:

 "reporting": {
        "reportTypes": [
        {
        "id": "campaign_performance",
        "title": "Campaign performance",
        "config": {
        "showDateRange": true,
        "showDefaultDateFields": true
        }
        }
        ]
        }

Step 2: Configure start and end date parameters to be sent as part of the request

When the connector shows the date range selection, we want to ensure that whatever the user selects as the date range of the query, is also sent as part of the API request. This is done using placeholders in the request configuration.

Let’s assume that the API we’re using accepts starting_from and until_to parameters to define the date range for which data is returned, and the date must be sent in the YYYY-MM-DD format. The report configuration would look like this:

{
        "reporting": {
        "reportTypes": [
        {
        "id": "campaign_performance",
        "title": "Campaign performance",
        "config": {
        "showDateRange": true,
        "showDefaultDateFields": true
        },
        "request": {
        "method": "GET",
        "url": "https://api.example.com",
        "parameters": [
        {
        "name": "starting_from",
        "value": "{{query.start_date.date}}"
        },
        {
        "name": "until_to",
        "value": "{{query.end_date.date}}"
        }
        ]
        }
        }
        ]
        }

Step 3: Define the field used for filtering the data by date

When we’re successfully sending the date range filtering params to the API, and we have configured a set of ready date fields for the user to aggregate the data for different granularities, we next need to explain to our system which field to use as a base for all the date operations.

Let’s assume that the API returns order data, and you want the orders to be aggregated based on the order creation date. This order creation date is returned in the API response in the date_of_order value. We will configure:

• A dimension for Order date with following details:

  • Display name (label): Order date

  • ID: order_date

  • Data type: string.time.date

  • Value for the field to come from jsonPath (JSON response provided by the API), and we read the value from the date_of_order field

• We configure readDateFrom under the config object to pinpoint to this order_date field we just created.

The full configuration would look like this:

 "reporting": {
        "reportTypes": [
        {
        "id": "campaign_performance",
        "title": "Campaign performance",
        "config": {
        "showDateRange": true,
        "showDefaultDateFields": true,
        "readDateFrom": "order_date"
        },
        "request": {
        "method": "GET",
        "url": "https://api.example.com",
        "parameters": [
        {
        "name": "starting_from",
        "value": "{{query.start_date.date}}"
        },
        {
        "name": "until_to",
        "value": "{{query.end_date.date}}"
        }
        ]
        },
        "dimensions": {
        "groups": [
        {
        "label": "DIMENSIONS",
        "fields": [
        {
        "id": "order_date",
        "label": "Order date",
        "dataType": "string.time.date",
        "value": {
        "source": "jsonPath",
        "value": "$.date_of_order"
        }
        }
        ]
        }
        ]
        }
        }
        ]
        }

Field configuration (metrics and dimensions)

Configuring the fields for your connector is an essential part in defining what data is available in the connector. Fields are divided into two categories:

• Dimensions:

  • Dimensions are descriptive attributes used to segment data, splitting your metrics into different categories. Common dimensions include, for example, campaign, country, device, contact ID, and order time.

• Metrics:

  • Metrics are quantitative measurements used to provide specific numbers about behavior or performance. One way to think about metrics is that you can apply mathematical operations to them, like summing them together or calculating an average value. Common metrics are, for example, spend, impressions, clicks, click-through rate, conversion rate, cost per acquisition, and return on investment (ROI).

When configuring fields to your connector, you need to configure each field under dimensions or metrics , so we know whether the field should be used to segment your data or to aggregate the data. You can configure as many fields in your connector as you want.

Example configuration for fields split to dimensions and metrics looks like this:

 "dimensions": {
        "groups": [
        {
        "label": "DIMENSIONS",
        "fields": [
        {
        "id": "campaign_id",
        "label": "Campaign ID",
        "dataType": "string.text.value",
        "value": {
        "source": "jsonPath",
        "value": "$.campaign_id"
        }
        }
        ]
        }
        ]
        },
        "metrics": {
        "groups": [
        {
        "label": "METRICS",
        "fields": [
        {
        "id": "impressions",
        "label": "Impressions",
        "dataType": "int.number.value",
        "value": {
        "source": "jsonPath",
        "value": "$.impressions"
        },
        "aggregationType": "sum"
        }
        ]
        }
        ]
        }

Field properties

Below you can find what different properties you should configure for your fields.

"value": {
                            "source": "jsonPath",
                            "value": "$.impressions"
                            }

Report type configuration template

{
        "reporting": {
        "reportTypes": [
        {
        "id": "[report_id]",
        "title": "[report_id]",
        "request": {
        "method": "GET",
        "url": "[endpoint URL]",
        "headers": [
        {
        "name": "Authorization",
        "value": "{{user.access_token}}"
        }
        ],
        "parameters": [
        {
        "name": "start_date",
        "value": "{{query.start_date.date}}"
        },
        {
        "name": "end_date",
        "value": "{{query.end_date.date}}"
        }
        ],
        "response": {
        "type": "JSON",
        "dataRows": {
        "source": "jsonPath",
        "value": "$[json path to data rows in the response]"
        },
        "pagination": {
        "type": "none"
        }
        }
        },
        "dimensions": {
        "groups": [
        {
        "label": "Dimension group name",
        "fields": [
        {
        "id": "field_id",
        "label": "field display name",
        "dataType": "string.text.value",
        "value": {
        "source": "jsonPath",
        "value": "$[jsonpath to field in API response]"
        }
        }
        ]
        }
        ]
        },
        "metrics": {
        "groups": [
        {
        "label": "Metrics group name",
        "fields": [
        {
        "id": "field_id",
        "label": "field display name",
        "dataType": "int.number.value",
        "aggregationType": "sum",
        "value": {
        "source": "jsonPath",
        "value": "$[jsonpath to field in API response]"
        }
        }
        ]
        }
        ]
        }
        }
        ]
        }
        }