# Incremental Activation Parameters

Incremental Activation is a Beta release. For more information, contact your Customer Success Representative.

This reference document describes all parameters used in the Incremental Activation workflow template. Parameters are defined in the `_export.params` block of the workflow configuration.

## Parameter Overview

| Parameter | Required | Auto-Populated | Description |
|  --- | --- | --- | --- |
| `api_endpoint` | Yes | No | API endpoint to fetch the Incremental Activation workflow |
| `id_key` | Yes | No | Unique identifier column in the source table |
| `delta_keys` | Yes | No | Array of columns to check for changes |
| `activation_mappings` | Yes | No | Array of delta record to connector mappings |
| `activation_actions_db` | Conditional | Yes (Activation Action) | Source TD database |
| `activation_actions_table` | Conditional | Yes (Activation Action) | Source table name |
| `result_connection_settings` | Conditional | Yes (Activation Action) | Result connector configuration object |
| `result_connection_name` | Conditional | Yes (Activation Action) | Connector authentication name |


Parameters marked "Yes" under "Auto-Populated" are automatically set when running as an Activation Action within Audience Studio. When running as a standalone workflow, all conditional parameters must be manually configured.

## api_endpoint

**Type**: String
**Required**: Yes
**Auto-Populated**: No

The API endpoint URL for fetching the Incremental Activation workflow. The value depends on your Treasure Data site location.

### Values by TD Site

| TD Site | Endpoint URL |
|  --- | --- |
| US (us01) | `https://integrations-gateway.us01.treasuredata.com` |
| EU (eu01) | `https://integrations-gateway.eu01.treasuredata.com` |
| Asia Pacific (ap02) | `https://integrations-gateway.ap02.treasuredata.com` |
| Japan (co.jp) | `https://integrations-gateway.treasuredata.co.jp` |


### Example


```yaml
_export:
  params:
    api_endpoint: "https://integrations-gateway.us01.treasuredata.com"
```

### Validation

- Must be a valid HTTPS URL
- Must match your Treasure Data site location
- Incorrect endpoints will cause workflow failures


## id_key

**Type**: String
**Required**: Yes
**Auto-Populated**: No

The column name that serves as the unique identifier (primary key) for profiles in your source table. This column's data must be unique across all rows.

### Purpose

The `id_key` column is used to:

- Identify new profiles added to the segment
- Identify profiles removed from the segment
- Match profiles between activation runs for delta calculation


### Common Values

- `td_customer_id` - Treasure Data's unified customer ID
- `email` - Email address
- `phone_number` - Phone number
- `mobile_ad_id` - Mobile advertising ID (IDFA, MAID)
- `customer_id` - Custom customer identifier


### Example


```yaml
_export:
  params:
    id_key: "email"
```

### Requirements

The `id_key` column must contain unique values. Duplicate values will cause errors in delta calculation and may produce incorrect results.

- Column must exist in the source table
- Values must be unique (no duplicates)
- Values should not be null
- Data type should be consistent (all strings or all numbers)


### Best Practices

1. **Choose a stable identifier**: Select a column that rarely changes. If the ID changes, the profile will appear as "deleted" and "new" rather than "unchanged."
2. **Verify uniqueness**: Run a query to confirm no duplicate values exist:

```sql
SELECT id_key, COUNT(*)
FROM your_table
GROUP BY id_key
HAVING COUNT(*) > 1
```
3. **Match destination requirements**: If your destination platform requires a specific identifier (e.g., email hash for Meta), ensure your `id_key` matches.


## delta_keys

**Type**: Array of Strings
**Required**: Yes
**Auto-Populated**: No

An array of column names to check for changes when determining if a profile is "updated" or "unchanged." These columns define which attributes trigger an update status.

### Purpose

The `delta_keys` array determines:

- Whether a profile is marked as "updated" (when any delta key value changes)
- Whether a profile is marked as "unchanged" (when all delta key values remain the same)
- Which attribute changes trigger re-activation


### Examples

**Track job and organization changes**:


```yaml
delta_keys: ["job_title", "organization"]
```

**Track subscription status changes**:


```yaml
delta_keys: ["subscription_status", "tier_level"]
```

**Track location changes**:


```yaml
delta_keys: ["city", "country", "postal_code"]
```

**Track multiple attributes**:


```yaml
delta_keys: ["status", "tier", "email", "phone_number"]
```

### Default Behavior

If `delta_keys` is empty or not specified, it defaults to the value of `id_key`:


```yaml
# These two configurations are equivalent if id_key is "email"
delta_keys: []
# becomes
delta_keys: ["email"]
```

### How Delta Keys Work

The workflow calculates a hash of the `delta_keys` columns for each profile:

1. **Current Run**: Hash of current `delta_keys` values
2. **Previous Run**: Hash of previous `delta_keys` values
3. **Comparison**: If hashes differ, profile is marked "updated"


**Example**:

| Run | email | job_title | organization | Delta Keys Hash | Status |
|  --- | --- | --- | --- | --- | --- |
| 1 | john@example.com | Engineer | Acme Corp | abc123 | new |
| 2 | john@example.com | Senior Engineer | Acme Corp | def456 | updated |
| 3 | john@example.com | Senior Engineer | Acme Corp | def456 | unchanged |


### Best Practices

1. **Include relevant attributes only**: Don't include columns that change frequently but don't require re-activation (e.g., `last_login_timestamp`).
2. **Consider downstream impact**: If your destination charges per data point update, minimize unnecessary delta keys.
3. **Test with representative data**: Verify that your delta keys capture the changes you care about without over-triggering.
4. **Document your choices**: Record why specific columns were chosen as delta keys for future reference.


### Common Patterns

**E-commerce - Loyalty tier changes**:


```yaml
delta_keys: ["loyalty_tier", "points_balance"]
```

**B2B - Lead scoring updates**:


```yaml
delta_keys: ["lead_score", "engagement_level", "company_size"]
```

**Marketing - Preference management**:


```yaml
delta_keys: ["email_opt_in", "sms_opt_in", "preferred_channel"]
```

## activation_mappings

**Type**: Array of Objects
**Required**: Yes
**Auto-Populated**: No

An array of mapping objects that define how delta records are sent to the destination connector. Each mapping connects a delta status to a connector configuration.

For detailed information, see [Incremental Activation Mappings](/products/customer-data-platform/audience-studio/activation/incremental-activation-mappings).

### Structure

Each mapping object contains:

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `delta_status` | String | Yes | One of: `new`, `updated`, `deleted`, `unchanged` |
| `connector_field` | String | Yes | Connector config field name (e.g., `mode`, `operation`) |
| `connector_field_value` | String | Yes | Value to set (e.g., `append`, `delete`, `replace`) |


### Example


```yaml
activation_mappings: [
  {
    "delta_status": "new",
    "connector_field": "mode",
    "connector_field_value": "append"
  },
  {
    "delta_status": "updated",
    "connector_field": "mode",
    "connector_field_value": "append"
  },
  {
    "delta_status": "deleted",
    "connector_field": "mode",
    "connector_field_value": "delete"
  }
]
```

### Limits

- Maximum of 4 mapping elements (one per delta status type)
- Each `delta_status` value should appear only once


## activation_actions_db

**Type**: String
**Required**: Conditional
**Auto-Populated**: Yes (when running as Activation Action)

The name of the source TD database containing the table to process.

### When Auto-Populated

When running as an Activation Action within Audience Studio, this parameter is automatically set to the syndication database (e.g., `cdp_syndication_123`).

### When Required

When running as a standalone workflow, you must specify this parameter manually:


```yaml
_export:
  params:
    activation_actions_db: "my_customer_database"
```

### Validation

- Database must exist in your TD account
- User must have appropriate permissions on the database


## activation_actions_table

**Type**: String
**Required**: Conditional
**Auto-Populated**: Yes (when running as Activation Action)

The name of the source table within the database that contains the data to process.

### When Auto-Populated

When running as an Activation Action within Audience Studio, this parameter is automatically set to the segment syndication table (e.g., `segment_12345`).

### When Required

When running as a standalone workflow, you must specify this parameter manually:


```yaml
_export:
  params:
    activation_actions_table: "customer_profiles"
```

### Validation

- Table must exist in the specified database
- Table must contain the columns specified in `id_key` and `delta_keys`
- User must have read permissions on the table


## result_connection_settings

**Type**: Object
**Required**: Conditional
**Auto-Populated**: Yes (when running as Activation Action)

The configuration object for the result export connector. The structure varies depending on the destination connector type.

### When Auto-Populated

When running as an Activation Action within Audience Studio, this parameter is automatically populated based on your activation configuration.

### When Required

When running as a standalone workflow, you must specify the connector configuration manually.

### Example - Snowflake


```yaml
result_connection_settings:
  type: "snowflake"
  database: "MARKETING_DB"
  schema: "PUBLIC"
  table: "CUSTOMER_SEGMENTS"
  mode: "append"
```

### Example - Google Sheets


```yaml
result_connection_settings:
  type: "google_sheets"
  spreadsheet_id: "1ABC...xyz"
  sheet_name: "Customer List"
  mode: "replace"
```

### Connector-Specific Requirements

Refer to your destination connector's documentation for required fields and supported values.

## result_connection_name

**Type**: String
**Required**: Conditional
**Auto-Populated**: Yes (when running as Activation Action)

The name of the connector authentication configured in Treasure Data.

### When Auto-Populated

When running as an Activation Action within Audience Studio, this parameter is automatically populated based on your activation's selected authentication.

### When Required

When running as a standalone workflow, you must specify the authentication name manually:


```yaml
_export:
  params:
    result_connection_name: "my_snowflake_connection"
```

### Validation

- Authentication must exist in your TD account
- Authentication must be valid and not expired
- User must have permission to use the authentication


## Complete Parameter Examples

### Activation Action Mode

Only configure user-specified parameters:


```yaml
timezone: "UTC"
_export:
  params:
    api_endpoint: "https://integrations-gateway.us01.treasuredata.com"
    id_key: "email"
    delta_keys: ["subscription_status", "tier"]
    activation_mappings: [
      {
        "delta_status": "new",
        "connector_field": "mode",
        "connector_field_value": "append"
      },
      {
        "delta_status": "deleted",
        "connector_field": "mode",
        "connector_field_value": "delete"
      }
    ]
```

### Standalone Mode

Configure all parameters:


```yaml
timezone: "UTC"
_export:
  params:
    api_endpoint: "https://integrations-gateway.us01.treasuredata.com"
    id_key: "email"
    delta_keys: ["subscription_status", "tier"]
    activation_mappings: [
      {
        "delta_status": "new",
        "connector_field": "mode",
        "connector_field_value": "append"
      },
      {
        "delta_status": "updated",
        "connector_field": "mode",
        "connector_field_value": "append"
      }
    ]
    activation_actions_db: "customer_data"
    activation_actions_table: "unified_profiles"
    result_connection_name: "snowflake_production"
    result_connection_settings:
      type: "snowflake"
      database: "MARKETING"
      schema: "SEGMENTS"
      table: "ACTIVE_SUBSCRIBERS"
      mode: "append"
```

## Next Steps

- [Configure Incremental Activation](/products/customer-data-platform/audience-studio/activation/configure-incremental-activation)
- [Incremental Activation Mappings](/products/customer-data-platform/audience-studio/activation/incremental-activation-mappings)
- [Troubleshooting Incremental Activation](/products/customer-data-platform/audience-studio/activation/troubleshooting-incremental-activation)


## Related Topics

- [Incremental Activation Overview](/products/customer-data-platform/audience-studio/activation/incremental-activation-overview)
- [Activation Actions Parameters](/products/customer-data-platform/audience-studio/activation/activation-actions-parameters)