Incremental Activation Parameters

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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

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

Example

_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

_export:
  params:
    id_key: "email"

Requirements

• 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:
   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:

delta_keys: ["job_title", "organization"]

Track subscription status changes:

delta_keys: ["subscription_status", "tier_level"]

Track location changes:

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

Track multiple attributes:

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:

# 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:

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:

delta_keys: ["loyalty_tier", "points_balance"]

B2B - Lead scoring updates:

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

Marketing - Preference management:

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.

Structure

Each mapping object contains:

Example

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:

_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:

_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

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

Example - Google Sheets

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:

_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:

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:

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
• Incremental Activation Mappings
• Troubleshooting Incremental Activation

Related Topics

• Incremental Activation Overview
• Activation Actions Parameters