Creating and configuring transformations in Management API¶

This article documents how to create, list, edit and delete transformations with the Management API.

See GET /api/transformer/, POST /api/transformer/ and PATCH /api/transformer/{id}/ in the API reference.

Prerequisites¶

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

Use a Connect API key with the following permissions:
- Transformation: Read-only (transformation:read) to list and view transformations.
- Transformation: Write (transformation:write) to create, edit, or delete transformations.
- Datastream: Read-only (datastream:read) to list the datastreams a transformation is assigned to.
Picking Write for a permission also gives the key its Read-only access. Without the permission a request needs, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

Note

Creating or editing a transformation with custom-script instructions runs full validation of those instructions. To protect the platform from expensive validation runs, POST, PUT, and PATCH requests to /api/transformer/ are limited to 1000 instructions per request and to 20 such requests per minute for each user. Exceeding either limit returns an error; retry after waiting, or reduce the number of instructions in the request.

Creating a transformation through Management API¶

To create a transformation through Management API, follow these steps:

Create a POST request to the following endpoint:
```
https://{{INSTANCE}}/api/transformer/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the name parameter with the value {{TRANSFORMER_NAME}}.

Replace {{TRANSFORMER_NAME}} with the name you want to give the transformation. This value is always required.
In the HTTP request body, include the stack parameter with the value {{WORKSPACE_NAME}}.

Replace {{WORKSPACE_NAME}} with the name of your workspace. This value is always required.
In the HTTP request body, include the instructions parameter. This parameter does not need a value.
Send the request.

As a result, you create a transformation with the name{{TRANSFORMER_NAME}} in the workspace {{WORKSPACE_NAME}}.

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

curl --request POST 'https://{{INSTANCE}}/api/transformer/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "{{TRANSFORMER_NAME}}",
    "stack": {{WORKSPACE_NAME}},
    "instructions": [
        [
        "select",
            {
            "complement": false,
            "subtable": null,
            "where": "{COLUMN}",
            "_comment": null
            }
        ]
    ]
}'

Listing existing transformations through Management API¶

To obtain a list of all existing transformations through Management API, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/transformer/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

As a result, you obtain a list of all the existing transformations in your Adverity instance.

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

curl --request GET 'https://{{INSTANCE}}/api/transformer/' \
--header 'Authorization: Bearer {{KEY}}'

The example response below shows a list containing just one transformation. The change_url value is a path relative to your Adverity instance, not a full URL. It contains the ID of the enrichment that holds the transformation, which is different from the transformation ID (id). It is not a ready-to-use link: if you add your instance host in front of it, it redirects to the workspace that is currently open in the user’s session, so it is not a stable direct link. To link to a specific transformation, use https://{{INSTANCE}}/workspaces/{{WORKSPACE_UUID}}/enrichments/details/{{ENRICHMENT_ID}}/, with the UUID of the workspace that owns the transformation.

{
   "count": XX,
   "next": null,
   "previous": null,
   "results": [
      {
         "id": {{TRANSFORMER_ID}},
         "name": "{{TRANSFORMER_NAME}}",
         "stack": {{STACK_ID}},
         "change_url": "/current-workspace/enrichments/details/{{ENRICHMENT_ID}}/"
      }
   ]
}

Viewing the instructions within a specific transformation through Management API¶

To view the instructions within the body of a specific transformation through Management API, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/transformer/{{TRANSFORMER_ID}}/
```
Replace {{TRANSFORMER_ID}} with the ID you obtained in the response to the GET request in the previous section. For more information on obtaining the ID, see Listing existing Management API transformations.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

As a result, you obtain a response that contains the body of instructions for the specified enrichment.

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

curl --request GET 'https://{{INSTANCE}}/api/transformer/{{TRANSFORMER_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'

The example response below shows the instructions for a transformation called {{TRANSFORMER_NAME}} containing the instruction “select”.

{
   "id": {{TRANSFORMER_ID}},
   "name": "{{TRANSFORMER_NAME}}",
   "stack": {{STACK_ID}},
   "change_url": "/current-workspace/enrichments/details/{{ENRICHMENT_ID}}/",
   "instructions": [
      [
      "select",
      {
         "complement": false,
         "subtable": null,
         "where": "{column1}",
         "_comment": null
      }
      ]
   ]
}

Editing an existing transformation through Management API¶

To edit an existing transformation through Management API, follow these steps:

Create a PATCH request to the following endpoint:
```
https://{{INSTANCE}}/api/transformer/{{TRANSFORMER_ID}}/
```
Replace {{TRANSFORMER_ID}} with the transformation ID. For more information on obtaining the ID, see Listing existing Management API transformations.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the parameter to be updated with the value you want to set. In the example request below, the name of the transformation is being changed to {{NEW_NAME}}.

As a result, you make the specified change to the transformation.

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

curl --request PATCH 'https://{{INSTANCE}}/api/transformer/{{TRANSFORMER_ID}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"{{NEW_NAME}}"}'

Deleting an existing transformation through Management API¶

To delete an existing transformation through Management API, follow these steps:

Create a DELETE request to the following endpoint:
```
https://{{INSTANCE}}/api/transformer/{{TRANSFORMER_ID}}/
```
Replace {{TRANSFORMER_ID}} with the Management API transformation ID. For more information on obtaining the ID, see Listing existing Management API transformations.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

As a result, you delete the transformation with the ID {{TRANSFORMER_ID}}.

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

curl --request DELETE 'https://{{INSTANCE}}/api/transformer/{{TRANSFORMER_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'

Listing datastreams by transformation¶

To list all datastreams that use a specific transformation, follow these steps:

Create a GET request to the following endpoint, replacing {{TRANSFORMER_ID}} with the transformation ID:
```
https://{{INSTANCE}}/api/datastreams/?transformer={{TRANSFORMER_ID}}
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.

As a result, you obtain the list of datastreams that have the specified transformation assigned.

The cURL request example is the following:

curl --request GET 'https://{{INSTANCE}}/api/datastreams/?transformer={{TRANSFORMER_ID}}' \
--header 'Authorization: Bearer {{KEY}}'