Transformations

Transformations define how events are modified, enriched, or filtered as they pass through the Pipeline Transformation Engine. Each transformation is a YAML or JSON configuration that specifies mapping rules, filters, and computed fields applied to events before delivery to a specific integration.

Transformation Object

{
  "id": "txn_abc123",
  "source_id": "src_abc123",
  "integration_id": "int_xyz789",
  "name": "GA4 Event Mapper",
  "enabled": true,
  "config": {
    "version": "1.0",
    "rules": [
      {
        "type": "map",
        "source": "properties.product_id",
        "target": "items[0].item_id"
      },
      {
        "type": "map",
        "source": "properties.name",
        "target": "items[0].item_name"
      },
      {
        "type": "filter",
        "condition": "event != 'Page Loaded'"
      },
      {
        "type": "set",
        "target": "currency_code",
        "value": "USD"
      }
    ]
  },
  "created_at": "2026-01-20T12:00:00Z",
  "updated_at": "2026-02-15T16:45:00Z"
}

Field	Type	Description
`id`	string	Unique transformation identifier
`source_id`	string	Source this transformation applies to
`integration_id`	string	Integration this transformation targets
`name`	string	Display name
`enabled`	boolean	Whether this transformation is active
`config`	object	Transformation rules in YAML or JSON format
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last-updated timestamp

Rule Types

Transformation configs support the following rule types:

Rule Type	Description	Example
`map`	Copy a value from one field to another	Map `properties.price` to `value`
`set`	Set a field to a static value	Set `currency_code` to `"USD"`
`filter`	Drop events matching a condition	Drop events where `event == "internal_test"`
`rename`	Rename a field	Rename `properties.sku` to `properties.product_id`
`delete`	Remove a field from the event	Delete `properties.internal_flag`
`compute`	Compute a value from an expression	Set `total` to `properties.price * properties.quantity`

List Transformations

`GET /v1/admin/transformations`

Returns a paginated list of transformations.

Query parameters:

Parameter	Type	Default	Description
`source_id`	string	—	Filter by source ID
`integration_id`	string	—	Filter by integration ID
`cursor`	string	—	Pagination cursor
`limit`	integer	50	Items per page (max 100)

Request:

curl -X GET "http://localhost:8084/v1/admin/transformations?source_id=src_abc123" \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "data": [
    {
      "id": "txn_abc123",
      "source_id": "src_abc123",
      "integration_id": "int_xyz789",
      "name": "GA4 Event Mapper",
      "enabled": true,
      "created_at": "2026-01-20T12:00:00Z",
      "updated_at": "2026-02-15T16:45:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Required role: viewer or above.

Create Transformation

`POST /v1/admin/transformations`

Create a new transformation. The config can be provided as JSON or as a YAML string in the config_yaml field.

Request (JSON config):

{
  "source_id": "src_abc123",
  "integration_id": "int_xyz789",
  "name": "Meta CAPI Mapper",
  "enabled": true,
  "config": {
    "version": "1.0",
    "rules": [
      {
        "type": "map",
        "source": "properties.order_id",
        "target": "custom_data.order_id"
      },
      {
        "type": "map",
        "source": "properties.total",
        "target": "custom_data.value"
      },
      {
        "type": "set",
        "target": "custom_data.currency",
        "value": "USD"
      }
    ]
  }
}

Request (YAML config):

{
  "source_id": "src_abc123",
  "integration_id": "int_xyz789",
  "name": "Meta CAPI Mapper",
  "enabled": true,
  "config_yaml": "version: '1.0'\nrules:\n  - type: map\n    source: properties.order_id\n    target: custom_data.order_id\n  - type: map\n    source: properties.total\n    target: custom_data.value\n  - type: set\n    target: custom_data.currency\n    value: USD\n"
}

Response (201 Created): Full transformation object.

Required role: editor or above.

Update Transformation

`PUT /v1/admin/transformations/{id}`

Update an existing transformation’s name, config, or enabled state.

Request:

{
  "name": "Meta CAPI Mapper (v2)",
  "enabled": true,
  "config": {
    "version": "1.0",
    "rules": [
      {
        "type": "map",
        "source": "properties.order_id",
        "target": "custom_data.order_id"
      },
      {
        "type": "map",
        "source": "properties.total",
        "target": "custom_data.value"
      },
      {
        "type": "set",
        "target": "custom_data.currency",
        "value": "EUR"
      },
      {
        "type": "delete",
        "target": "properties.internal_ref"
      }
    ]
  }
}

Response: Updated transformation object.

Required role: editor or above.

Delete Transformation

`DELETE /v1/admin/transformations/{id}`

Delete a transformation. Events will pass through to the integration without this transformation applied.

Request:

curl -X DELETE http://localhost:8084/v1/admin/transformations/txn_abc123 \
  -H "Authorization: Bearer {access_token}"

Response: 204 No Content

Required role: editor or above.

Dry Run

`POST /v1/admin/transformations/{id}/dry-run`

Test a transformation against a sample event without affecting live data. The dry-run endpoint applies the transformation rules to the provided event and returns the transformed output.

Request:

{
  "event": {
    "type": "track",
    "event": "Order Completed",
    "properties": {
      "order_id": "ORD-1234",
      "total": 129.99,
      "currency": "USD",
      "products": [
        {
          "product_id": "SKU-001",
          "name": "Wireless Headphones",
          "price": 79.99,
          "quantity": 1
        },
        {
          "product_id": "SKU-002",
          "name": "Phone Case",
          "price": 24.99,
          "quantity": 2
        }
      ],
      "internal_ref": "INT-9999"
    },
    "userId": "user_98765",
    "timestamp": "2026-02-25T14:30:00.000Z"
  }
}

Response:

{
  "output": {
    "type": "track",
    "event": "Order Completed",
    "properties": {
      "order_id": "ORD-1234",
      "total": 129.99,
      "currency": "USD",
      "products": [
        {
          "product_id": "SKU-001",
          "name": "Wireless Headphones",
          "price": 79.99,
          "quantity": 1
        },
        {
          "product_id": "SKU-002",
          "name": "Phone Case",
          "price": 24.99,
          "quantity": 2
        }
      ]
    },
    "custom_data": {
      "order_id": "ORD-1234",
      "value": 129.99,
      "currency": "EUR"
    },
    "userId": "user_98765",
    "timestamp": "2026-02-25T14:30:00.000Z"
  },
  "rules_applied": 4,
  "rules_matched": 4,
  "warnings": []
}

Field	Type	Description
`output`	object	The event after all transformation rules have been applied
`rules_applied`	integer	Total number of rules in the transformation
`rules_matched`	integer	Number of rules that matched and were executed
`warnings`	string[]	Any warnings generated during transformation (e.g., missing source fields)

Required role: editor or above.

The dry-run endpoint is useful for testing transformation configs before enabling them in production. It does not persist any data or affect live event processing.

⚠️

Dry-run uses the saved transformation config, not the request body. To test changes before saving, update the transformation first (with enabled: false), then dry-run.

Integrations (Legacy)Data Layer