Configuring Data Mapping in Management API

This guide explains how to retrieve all tracked columns, retrieve details about specific columns, and assign target columns with the Management API.

Prerequisites

Before you complete the procedure in this guide, perform all of the following actions:

• Create a datastream and determine its datastream ID. For more information, see Creating datastreams.

• Collect data from your datastream. For more information, see Collecting data through Management API.

Retrieving current Data Mapping

Retrieving all tracked columns in an instance

To retrieve all tracked columns, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/columns/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/columns/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Retrieving all tracked columns in a datastream

To retrieve all tracked columns per datastream, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Retrieving details of a specific column

To retrieve details of a specific column, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/columns/{{COLUMN_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/columns/{{COLUMN_ID}}' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Assigning target columns

To assign columns you retrieved from the datastream to target columns, search through available target columns, create a new target column, and then assign the column to the target column. Sections below document this process.

Retrieving all available target columns

To retrieve all available target columns in your instance, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/target-columns/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/target-columns/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Searching through available target columns by name

This section uses an example in which you search for the target column called day using the name parameter. To search through the available target columns using the name parameter, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/target-columns/?name=day
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/target-columns/?name=day' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Retrieving available options for target column configuration

To retrieve all available options for a new target column, including the optional parameters, follow the steps below:

1. Create an OPTIONS request to the following endpoint:

   https://{{INSTANCE}}/api/target-columns/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request OPTIONS 'https://{{INSTANCE}}/api/target-columns/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Creating a new target column

If you could not find a target column matching the necessary configuration, create a new target column which you can later assign to a column retrieved from a datastream. To create a new target column, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/target-columns/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following required parameters:

   {
       "type": "String",
       "name": "{{TARGET_COLUMN_NAME}}",
       "usage": "dimension"
   }
   

   These are the required parameters. The value of the usage parameter is either dimension or metric.

   Note

   For metrics, the measure parameter defaults to SUM if not specified.

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request POST 'https://{{INSTANCE}}/api/target-columns/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "String",
    "name": "{{TARGET_COLUMN_NAME}}",
    "usage": "dimension"
}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Viewing a target column mapping

To view the list of source columns assigned to a target column, follow the steps below:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/target-columns/{{TARGET_COLUMN_ID}}/mappings/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/target-columns/{{TARGET_COLUMN_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Updating column mapping

In this section, you assign a column to a target column, or in other words, you configure the Data Mapping.

To update column mapping, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/{{COLUMN_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following required parameters:

   {
       "is_key_column":"false",
       "set_default": "false",
       "target_column": {"id": {{TARGET_COLUMN_ID}}}
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request PATCH 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/{{COLUMN_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "is_key_column":"false",
    "set_default": "false",
    "target_column": {"id": {{TARGET_COLUMN_ID}}}
}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Bulk assigning column mappings

Instead of mapping columns one by one, you can assign multiple source columns to target columns in a single request. This operation replaces all existing mappings for the datastream - any column not included in the request body will be left unmapped.

To bulk assign column mappings, follow these steps:

1. Create a PUT request to the following endpoint:

   https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/map/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include a list of mapping objects. Each object must contain the following parameters:

   • schema_column - the name of the target column to assign to.

   • source_column - the name of the source column from the datastream to map.

   [
       {
           "schema_column": "{{TARGET_COLUMN_NAME}}",
           "source_column": "{{SOURCE_COLUMN_NAME}}"
       },
       {
           "schema_column": "{{TARGET_COLUMN_NAME}}",
           "source_column": "{{SOURCE_COLUMN_NAME}}"
       }
   ]
   

   Note

   If any schema_column or source_column value in the list is not found, the entire request fails and no mappings are changed.

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request PUT 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/map/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "schema_column": "{{TARGET_COLUMN_NAME}}",
        "source_column": "{{SOURCE_COLUMN_NAME}}"
    }
]'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Removing column mapping

In this section, you remove a column’s mapping (unmap a column) using Management API.

To remove a column’s mapping (unmap a column), follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/{{COLUMN_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include an empty target_column object:

   {
       "target_column": {}
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request PATCH 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/{{COLUMN_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "target_column": {}
}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.