Incremental Activation Parameters

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.

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

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

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

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.

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

• 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

_export:
  params:
    id_key: "email"

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

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.

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.

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

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"]

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"]

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:

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.

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"]

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.

Each mapping object contains:

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"
  }
]

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

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

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

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

_export:
  params:
    activation_actions_db: "my_customer_database"

• Database must exist in your Treasure account
• User must have appropriate permissions on the database

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

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

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

_export:
  params:
    activation_actions_table: "customer_profiles"

• 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

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

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

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

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

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

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

The name of the connector authentication configured in Treasure Data.

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

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

_export:
  params:
    result_connection_name: "my_snowflake_connection"

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

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"
      }
    ]

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"

• Configure Incremental Activation
• Incremental Activation Mappings
• Troubleshooting Incremental Activation

• Incremental Activation Overview
• Activation Actions Parameters