Journey Commands

Manage CDP Journey Orchestration for customer journey automation.

Premium Feature

Journey Orchestration is a premium feature. Contact your Customer Success Representative for more information.

Overview

Journey Orchestration enables marketers to create automated customer journeys that guide customers through stages based on their behavior and attributes. Journeys differ from segments in that they track individual profile progression through defined stages over time.

Key Concepts

Journey: A timeline of stages that customers progress through toward a goal
Stage: A step in the journey with entry criteria, exit criteria, and actions
Step: An action or decision within a stage (wait, activation, decision point, A/B test)
Goal: The desired outcome that marks journey completion
Reentry: Rules for whether profiles can re-enter the journey

Commands

Command	Description
`list`	List journeys in current context
`view`	Show journey details
`pull`	Pull journey configuration to YAML
`push`	Push YAML configuration to TD
`validate`	Validate journey YAML files locally
`run`	Execute journey workflow
`pause`	Pause a running journey
`resume`	Resume a paused journey
`stats`	Show journey statistics

Typical Workflow

bash

# 1. Pull segments from a parent segment
tdx sg pull "My Audience"
# Creates: segments/my-audience/*.yml

# 2. Pull journeys (stored alongside segments)
tdx journey pull
# Creates: segments/my-audience/*.yml (journey files have type: journey)

# 3. Edit YAML files locally
# Edit segments/my-audience/onboarding-journey.yml

# 4. Push changes (preview first with --dry-run)
tdx journey push --dry-run   # Preview journey-only changes
tdx journey push             # Push journey-only changes
# Or push everything (segments, journeys, activations):
tdx sg push --dry-run
tdx sg push

# 5. Monitor journey statistics
tdx journey stats "Onboarding Journey"

YAML Format

Journeys are stored alongside segments in the parent segment folder:

segments/
└── my-audience/
    ├── tdx.json                       # Parent segment context
    ├── high-value-customers.yml       # Segment
    ├── new-signups.yml                # Segment
    ├── onboarding-journey.yml         # Journey
    └── retention-campaign.yml         # Journey

Journey YAML Schema

yaml

# segments/my-audience/onboarding-journey.yml
type: journey
name: Onboarding Journey
description: New customer onboarding flow

# Goal criteria - when is the journey complete?
goal:
  name: Completed Onboarding
  segment: entry-customers  # Reference to embedded segment

# Reentry rules
reentry: no_reentry  # no_reentry | reentry_unless_goal_achieved | reentry_always

# Embedded segments - journey-local segment definitions
# These segments are created/managed with the journey
segments:
  entry-customers:
    description: New customers in the last 7 days
    rule:
      type: And
      conditions:
        - type: Value
          attribute: created_date
          operator:
            type: TimeWithinPast
            value: 7
            unit: day

  engaged-users:
    description: Users who opened welcome email
    rule:
      type: And
      conditions:
        - type: Value
          attribute: welcome_email_opened
          operator:
            type: Equal
            value: true

# Journeys array - always present (even for single version)
journeys:
  - stages:
      - name: Welcome
        description: Initial welcome and introduction

        # Entry criteria - who enters this stage?
        entry_criteria:
          name: New Users
          segment: entry-customers  # Reference to embedded segment above

        # Exit criteria - when to remove from stage (optional)
        exit_criteria:
          - name: Churned
            segment: ref:Churned Users  # ref: prefix for external segments

        # Milestone - optional tracking point
        milestone:
          name: Welcome Email Opened
          segment: engaged-users

        # Steps define the flow within this stage
        # Uses GitHub Actions-like format: type, name, with (type-specific params)
        steps:
          # Wait step - pause before action
          - type: wait
            name: Wait 1 Day
            with:
              duration: 1
              unit: day  # day/days | week/weeks

          # Activation step - send to external system
          - type: activation
            name: Send Welcome Email
            with:
              activation: "Salesforce Marketing Cloud"  # Reference by name

          # Decision point - branch based on behavior
          - type: decision_point
            name: Check Email Open
            with:
              branches:
                - name: Opened Email
                  segment: engaged-users
                  next: send_followup
                - name: Did Not Open
                  segment: ref:Did Not Open Welcome  # External segment
                  excluded: true  # This is the "else" branch
                  next: send_reminder

          # End step - exit the stage (no 'with' needed)
          - type: end
            name: Stage Complete

Segment References

Journey YAML supports two types of segment references:

Syntax	Description	Example
`name`	Embedded segment (defined in `segments:` section)	`segment: entry-customers`
`ref:Name`	External segment (existing child segment)	`segment: ref:High Value Customers`

When pulling journeys, journey-local segments are automatically embedded, while references to external segments use the ref: prefix.

Segment Reference Conditions

Within segment rules, you can include or exclude members of other segments using type: include or type: exclude:

yaml

segments:
  # Include members of another segment
  vip_in_california:
    description: VIP customers in California
    rule:
      type: And
      conditions:
        - type: include
          segment: california_customers
        - type: Value
          attribute: tier
          operator:
            type: Equal
            value: vip

  # Exclude members of another segment
  new_non_churned:
    description: New users who haven't churned
    rule:
      type: And
      conditions:
        - type: Value
          attribute: signup_date
          operator:
            type: TimeWithinPast
            value: 30
            unit: day
        - type: exclude
          segment: churned_users

Type	Description
`type: include`	Include profiles that are members of the referenced segment
`type: exclude`	Exclude profiles that are members of the referenced segment

Unified Journeys Format

All journeys use a unified journeys array format, whether single or multi-version:

yaml

type: journey
name: Onboarding Journey
description: New customer onboarding flow

# Shared defaults (apply to all versions unless overridden)
goal:
  name: Completed Onboarding
  segment: entry-customers
reentry: no_reentry

segments:
  entry-customers:
    description: New customers
    rule:
      # ...

# Journeys array - each entry is a version
journeys:
  - version: v1
    state: launched
    latest: true  # Active version
    stages:
      - name: Welcome
        # ...

  - version: v2
    state: draft
    # Per-version override (optional)
    goal:
      name: Completed V2
      segment: active-customers
    stages:
      - name: Welcome (New)
        # ...

Key features:

journeys array is always present (even for single-version journeys)
Shared properties (goal, reentry, segments) at top level serve as defaults
Per-version overrides are optional and inherit from top-level defaults
version property is optional (defaults to "v1" for single-version)
latest: true marks the active version
state indicates draft or launched

Step Types

All steps use a consistent format with type, name, and type-specific parameters nested under with:

Type	Description	`with` Parameters
`wait`	Pause execution	`duration`, `unit` (day/week)
`activation`	Send to external system	`activation` (name reference)
`decision_point`	Branch based on segment	`branches[]`
`ab_test`	Split traffic for testing	`variants[]`, `customized_split`
`merge`	Rejoin branched paths	(none - only uses `next`)
`jump`	Go to another journey/stage	`target.journey`, `target.stage`, `target.bundle_id`
`end`	Exit the stage	(none - terminates flow)

Wait Step Options

yaml

# Duration-based wait
- type: wait
  name: Wait 7 Days
  with:
    duration: 7
    unit: day  # day | week

# Wait until specific date
- type: wait
  name: Wait Until Holiday
  with:
    wait_until: "2024-12-25T00:00:00Z"

# Wait until condition met (with timeout)
- type: wait
  name: Wait for Purchase
  with:
    condition:
      segment: "Made Purchase"
      timeout:
        duration: 14
        unit: day

# Wait with different paths for matched vs timeout
- type: wait
  name: Wait for Purchase
  with:
    condition:
      segment: made-purchase      # Wait until segment match
      next: follow-up             # Optional: step when matched (defaults to next step)
      timeout:
        duration: 14
        unit: day
        next: timeout-path        # Step when timeout - triggers branching

Condition Branching

When timeout.next is specified, the wait step branches into two paths:

Matched path: Profiles matching the segment go to condition.next (or the next sequential step if omitted)
Timeout path: Profiles not matching within the duration go to timeout.next

Decision Point Branches

yaml

- type: decision_point
  name: Check Engagement
  with:
    branches:
      - name: High Engagement
        segment: "Active Users"  # Child segment reference
        next: premium_path
      - name: Medium Engagement
        segment: "Moderate Users"
        next: nurture_path
      - name: Low Engagement
        excluded: true  # Catch-all for remaining
        next: reactivation_path

Jump to Another Journey

Use jump steps to transfer profiles to another journey or stage:

yaml

# Jump to another journey (by name)
- type: jump
  name: Continue in Retention Journey
  with:
    target:
      journey: "Retention Campaign"  # Journey name
      stage: "Welcome Back"          # Target stage name

# Jump to a journey in a folder
- type: jump
  name: Move to VIP Journey
  with:
    target:
      journey: "Marketing/VIP Journey"  # Folder path + journey name
      stage: "Entry"

# Jump to a local journey file (same project)
- type: jump
  name: Next Journey
  with:
    target:
      journey: retention-journey.yml  # Local .yml file reference
      stage: "Stage 1"

Target Reference Formats:

Format	Description	Example
Journey name	Journey in root folder	`journey: "My Journey"`
Folder/Journey	Journey in subfolder	`journey: "Marketing/Campaign"`
`file.yml`	Local journey file	`journey: "other-journey.yml"`

Cross-Journey Orchestration

Jump steps enable complex multi-journey workflows. Profiles exit the current journey and enter the target journey at the specified stage.

Commands Reference

list

List journeys in the current parent segment context.

bash

tdx journey list [pattern] [options]

Option	Description
`-r, --recursive`	List recursively (tree view)

bash

# List all journeys in context
tdx journey list

# Filter by pattern
tdx journey list "*onboarding*"

# List recursively
tdx journey list -r

view

Show journey details including stages and statistics.

bash

tdx journey view <name-or-path> [options]

The <name-or-path> argument supports:

Journey name: "Onboarding Journey"
Path notation: "My Audience/Onboarding Journey"
YAML file path: segments/my-audience/onboarding-journey.yml

Option	Description
`--include-stats`	Include execution statistics

bash

# View journey by name
tdx journey view "Onboarding Journey"

# View journey by path
tdx journey view "My Audience/Onboarding Journey"

# View journey from YAML file
tdx journey view segments/my-audience/onboarding-journey.yml

# View with statistics
tdx journey view "Onboarding Journey" --include-stats

pull

Pull journey configurations to local YAML files.

bash

tdx journey pull [name] [options]

Option	Description
`--dry-run`	Preview changes without writing files
`-y, --yes`	Skip confirmation prompt

bash

# Pull all journeys (requires context or tdx.json)
tdx journey pull
# Creates: segments/<parent>/*.yml (with type: journey)

# Pull specific journey
tdx journey pull "Onboarding Journey"

# Preview what would be pulled
tdx journey pull --dry-run

The pull command:

Stores journeys alongside segments in the parent segment folder
Embeds journey-local segments in the YAML file
Uses ref:Name syntax for references to external segments
Shows diff for changed files before writing

push

Push journey YAML files to Treasure Data. This command pushes only journeys, without affecting segments or activations.

bash

tdx journey push [target] [options]

The [target] argument can be:

A directory path containing journey YAML files
A specific YAML file path
Omitted to use the current directory or context

Option	Description
`--dry-run`	Preview changes without applying
`-y, --yes`	Skip confirmation prompt

bash

# Preview journey changes
tdx journey push --dry-run

# Push journey changes
tdx journey push

# Push specific directory
tdx journey push segments/my-audience

# Push specific journey file
tdx journey push segments/my-audience/onboarding-journey.yml

# Push all files (segments, journeys, and activations)
tdx sg push

Journey-Only Mode

tdx journey push is equivalent to tdx sg push but only processes journey files (type: journey). Use it when you want to update journeys without modifying segments or activations.

validate

Validate journey YAML files locally without pushing to Treasure Data. This catches syntax errors, missing embedded segment references, and invalid step configurations before pushing.

bash

tdx journey validate [target]

Argument	Description
`target`	File or directory to validate (optional, defaults to context directory)

bash

# Validate all journeys in context directory
tdx journey validate

# Validate a specific journey file
tdx journey validate onboarding-journey.yml

# Validate journeys in a specific directory
tdx journey validate segments/my-audience

Validations performed:

Missing name or empty stages
Duplicate step names within journey
Invalid next step references (must point to existing step)
Wait step condition references to undefined embedded segments
Decision branch references to undefined segments
A/B test variant percentages not summing to 100%
Invalid jump step targets
Embedded segment rule validation

TIP

Validation also runs automatically before tdx journey push and tdx sg push, so errors are caught even if you skip this command.

run

Execute the journey workflow to process profiles.

bash

tdx journey run <name-or-path>

The <name-or-path> argument supports:

Journey name: "Onboarding Journey"
Path notation: "My Audience/Onboarding Journey"
YAML file path: segments/my-audience/onboarding-journey.yml

bash

# Run journey workflow
tdx journey run "Onboarding Journey"

pause

Pause a running journey and its activations.

bash

tdx journey pause <name-or-path>

The <name-or-path> argument supports journey name, path notation, or YAML file path.

bash

# Pause journey by name
tdx journey pause "Onboarding Journey"

# Pause journey from YAML file
tdx journey pause segments/my-audience/onboarding-journey.yml

resume

Resume a paused journey.

bash

tdx journey resume <name-or-path>

The <name-or-path> argument supports journey name, path notation, or YAML file path.

bash

# Resume journey by name
tdx journey resume "Onboarding Journey"

# Resume journey from YAML file
tdx journey resume segments/my-audience/onboarding-journey.yml

stats

Show journey statistics including stage populations and conversion rates.

bash

tdx journey stats <name-or-path> [options]

The <name-or-path> argument supports journey name, path notation, or YAML file path.

Option	Description
`--stage <name>`	Show stats for specific stage
`--period <days>`	Time period for statistics (default: 30)

bash

# Show overall journey stats
tdx journey stats "Onboarding Journey"

# Show specific stage stats
tdx journey stats "Onboarding Journey" --stage "Welcome"

Output:

Journey: Onboarding Journey
Status: Running
Last Execution: 2024-01-15 10:30:00 UTC

Stage Statistics
────────────────────────────────────────────────
  Stage        Population  Entered  Exited  Goal Rate
  Welcome           1,234    5,678   4,444     23.4%
  Engagement          890    4,444   3,554     18.2%
  Conversion          456    3,554   3,098     12.8%
  ────────────────────────────────────────────────
  Total Goal:      1,456 (25.6% of entered)

Journey States

State	Description
`draft`	Journey is being edited, not yet launched
`simulation`	Running in simulation mode for testing
`launched`	Journey is live and processing profiles
`paused`	Journey is paused, no new profiles enter

Best Practices

Stage Design

Limit stages to 8 maximum - Keep journeys focused and manageable
Clear entry criteria - Each stage should have well-defined entry conditions
Use milestones for tracking - Add milestones to measure intermediate success
Plan exit criteria - Define when profiles should leave the journey

Activation Setup

Test activations first - Ensure activations work before adding to journey
Use A/B testing - Test different approaches before full rollout
Monitor delivery rates - Check activation success in statistics

Activation Configuration

Journey activations can include connector_config for connector-specific settings:

yaml

steps:
  - type: activation
    name: Export to S3
    with:
      activation:
        name: S3 Export
        connection: my-s3-connection
        all_columns: true
        connector_config:
          bucket: my-bucket
          path: journey-exports/users.csv
          format: csv

Schema Validation

When pushing journeys, tdx automatically validates connector_config against the connector's schema. Use tdx connection schema <type> to see available fields for each connector type.

Reentry Strategy

Strategy	Use Case
`no_reentry`	One-time journeys (welcome, onboarding)
`reentry_unless_goal_achieved`	Repeat until goal met (conversion)
`reentry_always`	Recurring journeys (monthly engagement)

Journey Commands ​

Overview ​

Key Concepts ​

Commands ​

Typical Workflow ​

YAML Format ​

Journey YAML Schema ​

Segment References ​

Segment Reference Conditions ​

Unified Journeys Format ​

Step Types ​

Wait Step Options ​

Decision Point Branches ​

Jump to Another Journey ​

Commands Reference ​

list ​

view ​

pull ​

push ​

validate ​

run ​

pause ​

resume ​

stats ​

Journey States ​

Best Practices ​

Stage Design ​

Activation Setup ​

Activation Configuration ​

Reentry Strategy ​

Learn More ​

Journey Commands

Overview

Key Concepts

Commands

Typical Workflow

YAML Format

Journey YAML Schema

Segment References

Segment Reference Conditions

Unified Journeys Format

Step Types

Wait Step Options

Decision Point Branches

Jump to Another Journey

Commands Reference

list

view

pull

push

validate

run

pause

resume

stats

Journey States

Best Practices

Stage Design

Activation Setup

Activation Configuration

Reentry Strategy

Learn More