> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Components

> Reference guide for all trigger components that start your automations

# Trigger Components

Triggers are the starting point of every automation. They define **when** your automation runs by listening for specific events in your Statisfy data.

## How Triggers Work

When a trigger event occurs:

1. The trigger component receives the event with the entity ID
2. It loads the full entity data from the database
3. It establishes the **Flow Context** with entity information
4. It outputs a **Data** object containing the entity details
5. Connected downstream nodes begin executing

<Note>
  Every automation must have exactly one trigger. You cannot have multiple triggers or start an automation without one.
</Note>

***

## Account Segment V2

Triggers when an account enters or exits a specified segment.

### When to Use

* Alert when accounts become at-risk
* Notify when accounts qualify for upsell
* Take action when account criteria change

### Configuration

| Field          | Description                           |
| -------------- | ------------------------------------- |
| **Segment**    | Select the account segment to monitor |
| **Trigger On** | Enter, Exit, or Both                  |

### Output Data

```json theme={null}
{
  "account_id": "acc_123",
  "account_data": {
    "name": "Acme Corp",
    "owner_name": "Jane Smith",
    "owner_email": "jane@company.com",
    "health_score": 75,
    "arr": 150000,
    "renewal_date": "2024-06-15",
    "custom_fields": { ... }
  }
}
```

### Flow Context

Sets `account_id` (the account identifier) and `account_data` (the full account object) for downstream nodes. Use `@account_id` to reference the ID and `@account_data.field_name` to access account properties.

***

## Task Segment V2

Triggers when a task matches specified criteria or enters a segment.

### When to Use

* Alert when tasks become overdue
* Notify when high-priority tasks are created
* Escalate tasks based on criteria

### Configuration

| Field          | Description                              |
| -------------- | ---------------------------------------- |
| **Segment**    | Select the task segment to monitor       |
| **Task Types** | Filter by specific task types (optional) |

### Output Data

```json theme={null}
{
  "task_id": "task_456",
  "task_data": {
    "title": "Follow up on renewal",
    "status": "Open",
    "priority": "High",
    "due_date": "2024-03-01",
    "assignee": "john@company.com",
    "description": "..."
  },
  "account_id": "acc_123",
  "account_data": { ... }
}
```

### Flow Context

Sets `task_id` (the task identifier), `task_data` (the full task object), `account_id` (the associated account identifier), and `account_data` (the associated account object) for downstream nodes. Use `@task_data.field_name` to access task properties and `@account_data.field_name` for account properties.

***

## User Segment V2

Triggers when a user/contact enters or exits a specified segment.

### When to Use

* Alert when a champion leaves
* Identify new power users
* Track user engagement changes

### Configuration

| Field       | Description                               |
| ----------- | ----------------------------------------- |
| **Segment** | Select the user/people segment to monitor |

### Output Data

```json theme={null}
{
  "user_id": "user_789",
  "user_data": {
    "name": "John Doe",
    "email": "john@acme.com",
    "title": "VP of Engineering",
    "account_id": "acc_123",
    "last_activity": "2024-02-15"
  }
}
```

### Flow Context

Sets `user_id` (the user identifier) and `user_data` (the full user object) for downstream nodes. Use `@user_id` to reference the ID and `@user_data.field_name` to access user properties.

***

## Contact Segment V2

Triggers when a contact matches specified segment criteria.

### When to Use

* Identify key stakeholders
* Track contact engagement
* Alert on contact role changes

### Configuration

| Field       | Description                           |
| ----------- | ------------------------------------- |
| **Segment** | Select the contact segment to monitor |

### Output Data

Similar to User Segment, contains contact details including name, email, title, and associated account information.

***

## Opportunity Segment V2

Triggers when an opportunity enters or exits a segment.

### When to Use

* Alert on deal stage changes
* Notify when opportunities become at-risk
* Track expansion opportunities

### Configuration

| Field       | Description                               |
| ----------- | ----------------------------------------- |
| **Segment** | Select the opportunity segment to monitor |

### Output Data

```json theme={null}
{
  "opportunity_id": "opp_123",
  "opportunity_data": {
    "name": "Acme Corp - Expansion",
    "stage": "Negotiation",
    "amount": 50000,
    "close_date": "2024-04-30",
    "probability": 75,
    "owner": "sales@company.com"
  }
}
```

***

## Field Change

Triggers when one of the **custom field values you're watching** changes on a record. Unlike segment triggers (which fire when a record enters or exits a segment), Field Change fires on the *edit itself* — so you can react to a specific field being updated, regardless of whether the record's segment membership changed.

This trigger comes in three entity variants:

* **Account Field Change** — watches custom fields on accounts
* **Contact Field Change** — watches custom fields on contacts
* **Opportunity Field Change** — watches custom fields on opportunities

### When to Use

* Run an automation when a specific custom field is edited (e.g., "Renewal Stage", "Onboarding Status")
* Sync a field change out to an external system via an API Call
* Notify an owner when a watched field flips to a particular value

### Configuration

| Field                  | Description                                                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Field Keys**         | The custom fields to watch. Pick from the entity's registered custom fields — the trigger only fires when one of these changes.                                |
| **Segment (optional)** | Optional pre-filter. When set, only records matching this segment will fire, even if a watched field changes on another record.                                |
| **Test Record**        | *(Advanced)* Pin a sample record and a set of simulated changed fields so you can use **Run** in the builder to test the flow without waiting for a real edit. |

### Output Data

**Account Field Change**

```json theme={null}
{
  "account_id": "acc_123",
  "account_data": { "name": "Acme Corp", ... },
  "changed_fields": ["renewal_stage", "onboarding_status"]
}
```

**Contact Field Change** and **Opportunity Field Change** additionally resolve the parent account, so they also include `account_id` and `account_data`:

```json theme={null}
{
  "opportunity_id": "opp_123",
  "opportunity_data": { "name": "Acme Corp - Expansion", ... },
  "account_id": "acc_123",
  "account_data": { ... },
  "changed_fields": ["close_date"]
}
```

`changed_fields` is the subset of your watched **Field Keys** that actually changed on this event — use it to branch (e.g., a Condition that checks whether a particular key is in the list).

### Flow Context

Sets the entity ID and data for the triggering record (`account_id`/`account_data`, `contact_id`/`contact_data`, or `opportunity_id`/`opportunity_data`). The Contact and Opportunity variants also set the linked `account_id` and `account_data`. Reference values downstream with `@account_data.field_name`, and use `@changed_fields` to access the list of changed keys.

<Note>
  Field Change triggers fire on every matching edit — they do not use the **Expiration Days** re-trigger window that segment triggers have. Narrow the **Field Keys** (and optionally the **Segment**) to avoid running the flow more often than you intend.
</Note>

***

## Process Activity V2

Triggers after a customer activity is processed by Statisfy's activity engine.

### When to Use

* React to specific customer activities
* Trigger workflows based on engagement
* Process activity-driven automations

### Configuration

| Field              | Description                                  |
| ------------------ | -------------------------------------------- |
| **Activity Types** | Filter by specific activity types (optional) |
| **Sources**        | Filter by activity source (optional)         |

### Output Data

```json theme={null}
{
  "activity_id": "act_456",
  "activity_data": {
    "type": "Meeting",
    "source": "Calendar",
    "timestamp": "2024-02-20T10:00:00Z",
    "participants": ["john@acme.com", "jane@company.com"],
    "summary": "..."
  },
  "account_id": "acc_123",
  "account_data": { ... }
}
```

### Flow Context

Sets `activity_id` (the activity identifier), `activity_data` (the full activity object), `account_id` (the associated account identifier), and `account_data` (the associated account object) for downstream nodes. Use `@activity_data.field_name` to access activity properties and `@account_data.field_name` for account properties.

***

## Activity Segment V2

Triggers when activities match segment criteria.

### When to Use

* Monitor for specific activity patterns
* Alert on activity anomalies
* Track engagement thresholds

### Configuration

| Field       | Description                            |
| ----------- | -------------------------------------- |
| **Segment** | Select the activity segment to monitor |

***

## Meeting Segment V2

Triggers when meetings match specified criteria.

### When to Use

* Follow up after customer meetings
* Track meeting frequency
* Alert on missed meetings

### Configuration

| Field       | Description                           |
| ----------- | ------------------------------------- |
| **Segment** | Select the meeting segment to monitor |

### Output Data

Contains meeting details including participants, time, duration, and associated account information.

***

## Upcoming Meeting V2

Triggers for **calendar events that are about to happen** (e.g., one hour before a meeting starts). Use this to drive meeting-prep workflows that need to run *before* the meeting, not after it.

### When to Use

* Generate a meeting briefing for the account owner an hour before the call
* Post a Slack reminder with attendees and recent activity
* Create a follow-up task ahead of a renewal meeting

### Configuration

| Field               | Description                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Trigger Type**    | `event` — fires when a matching calendar event is created or updated. `scheduled` — sweeps the segment on a cron.     |
| **Schedule**        | Cron expression (used only when Trigger Type is `scheduled`).                                                         |
| **Meeting Segment** | Segment of calendar events to monitor — filter by scope (internal/external), participants, account, time window, etc. |
| **Expiration Days** | Re-trigger window. Defaults to 180 days; set to 0 to fire only once per event.                                        |

### Output Data

```json theme={null}
{
  "id": "evt_123",
  "event_data": {
    "title": "QBR — Acme Corp",
    "start_time": "2026-05-20T14:00:00Z",
    "end_time": "2026-05-20T15:00:00Z",
    "participants": ["jane@acme.com", "csm@company.com"],
    "description": "Quarterly business review"
  },
  "account_id": "acc_123",
  "account_data": { ... }
}
```

### Flow Context

Sets `id` (the calendar event identifier), `event_data` (the full event object), `account_id` (the linked account identifier), and `account_data` (the linked account object) for downstream nodes.

***

## Project Segment V2

Triggers when a project enters or exits a segment.

### When to Use

* Alert on project health changes
* Track implementation progress
* Monitor onboarding projects

### Configuration

| Field       | Description                           |
| ----------- | ------------------------------------- |
| **Segment** | Select the project segment to monitor |

### Output Data

Contains project details including name, status, tasks, and associated account information.

***

## Scheduler V2

Triggers on a scheduled time basis (cron-style scheduling).

### When to Use

* Run daily/weekly reports
* Periodic data updates
* Scheduled batch operations

### Configuration

| Field        | Description                        |
| ------------ | ---------------------------------- |
| **Schedule** | Cron expression or preset schedule |
| **Timezone** | Timezone for schedule evaluation   |

### Output Data

```json theme={null}
{
  "triggered_at": "2024-02-20T09:00:00Z",
  "schedule": "0 9 * * *"
}
```

<Note>
  Scheduler triggers don't have entity context. You'll need to use processing nodes to fetch the data you need.
</Note>

***

## Re-Trigger Window (Expiration Days)

Most segment triggers (Account, Contact, Task, User, Opportunity, Activity, Project, Upcoming Meeting) expose an **Expiration Days** setting. It controls how long Statisfy waits before allowing the **same entity** to trigger the **same flow** again.

| Value                | Behavior                                                                |
| -------------------- | ----------------------------------------------------------------------- |
| `180` (default)      | The flow re-triggers for the same entity at most once every 180 days.   |
| `0`                  | One-time execution — the flow fires for an entity once and never again. |
| Any positive integer | Custom cooldown window, in days.                                        |

Use a longer window for high-noise segments (e.g., "Health \< 50") to avoid spamming the same account every day. Use `0` for one-shot lifecycle events like "Account created."

***

## Common Trigger Patterns

### Pattern: Segment + Condition

Combine segment triggers with conditions for fine-grained control:

```
Account Segment → Condition (ARR > 100K) → Action
```

### Pattern: Multi-Entity Context

When you need data from multiple entities:

```
Task Segment → (has account_data from context) → Send Email
```

### Pattern: Scheduled + Data Fetch

For scheduled operations that need entity data:

```
Scheduler → SQL Query (fetch accounts) → Loop through results
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Action Components" icon="paper-plane" href="/agent-studio/automations/actions">
    Learn about actions you can take
  </Card>

  <Card title="Processing Components" icon="gears" href="/agent-studio/automations/processing">
    Transform and manipulate data
  </Card>
</CardGroup>