# Setting Up Triggers

Triggers automatically execute a workflow when something happens in your Drupal site — for example, when content is created, a user logs in, or cron runs. Instead of manually running workflows, triggers make them event-driven.

!!! note "Module Required"
    Enable the `flowdrop_trigger` module before using triggers:
    ```bash
    drush en flowdrop_trigger
    ```

## How Triggers Work

1. You add a **Trigger node** to your workflow in the visual editor.
2. FlowDrop automatically creates a trigger configuration linked to that node.
3. When the matching event occurs in Drupal, FlowDrop executes the workflow and passes event data into the workflow.

The trigger configuration is tied to the trigger node — if you remove the node from the workflow, the trigger configuration is automatically deleted.

## Step-by-Step: Create an Entity Trigger

This example creates a trigger that runs a workflow whenever an Article is created.

### Step 1: Create a Workflow

1. Navigate to **Administration > FlowDrop > Workflows** (`/admin/flowdrop/workflows`).
2. Click **+ Add Workflow**.
3. Enter a label (e.g., "New Article Handler") and click **Save**.
4. Open the workflow in the visual editor.

### Step 2: Add a Trigger Node

1. Click the **+** button in the editor to open the node palette.
2. Search for "Trigger" or browse the node categories.
3. Add the **Trigger** node to the canvas.

The trigger node appears on the canvas. Unlike regular nodes, it has no input ports — it is the starting point of a triggered workflow. FlowDrop automatically creates a trigger configuration entity linked to this node.

### Step 3: Configure the Trigger

Click on the trigger node to open its configuration panel, then configure:

1. Set the **Event Type** to `entity.insert` (fires when an entity is created).
2. Set the **Entity Type** to `node` (for content entities).
3. Set the **Bundle** to `article`.
4. Review the **Orchestrator** setting — triggers default to **Asynchronous** for most event types, which is recommended.

### Step 4: Add Processing Nodes

Now add the nodes that should process the event:

1. Add a **Logger** node (or any processing node you need).
2. Connect the trigger node's output port to your processing node's input port.

The trigger node's output contains the event data — for entity events, this includes the serialized entity with all its fields.

### Step 5: Save and Enable

1. Click **Save** in the editor toolbar.
2. Ensure the workflow is **enabled** (status = true). Disabled workflows will not respond to triggers.

### Step 6: Test the Trigger

1. Create a new Article in your Drupal site.
2. Check execution results at **Administration > FlowDrop > Pipelines** (`/admin/flowdrop/pipelines`).
3. You should see a new pipeline created for your workflow.

!!! tip
    If using the asynchronous orchestrator, make sure queues are being processed. See [Execution Modes](execution-modes.md#setting-up-queue-processing) for queue setup.

## Available Event Types

### Entity Events

| Event | Fires When | Default Orchestrator |
|-------|-----------|---------------------|
| Entity Insert | An entity is created | Asynchronous |
| Entity Update | An entity is updated | Asynchronous |
| Entity Delete | An entity is deleted | Asynchronous |
| Entity Presave | Just before an entity is saved | Synchronous |

!!! warning
    **Entity Presave** runs synchronously during the entity save operation. Keep presave workflows fast and lightweight to avoid slowing down content editing.

### User Events

| Event | Fires When | Default Orchestrator |
|-------|-----------|---------------------|
| User Login | A user logs in | Asynchronous |
| User Logout | A user logs out | Asynchronous |

### Form Events

| Event | Fires When | Default Orchestrator |
|-------|-----------|---------------------|
| Form Submit | A form is submitted | Asynchronous |
| Form Validate | During form validation | Synchronous |

### Cron Events

| Event | Fires When | Default Orchestrator |
|-------|-----------|---------------------|
| Cron Run | Drupal's cron runs | Asynchronous |

Cron triggers are useful for scheduled tasks like periodic data synchronization, automated content publishing, or cleanup operations.

## Event Data in Workflows

When a trigger fires, it passes contextual data into the workflow. For entity events, the available data includes:

| Field | Description |
|-------|-------------|
| `entity` | The full serialized entity (all fields and values) |
| `original_entity` | The entity before the change (for update and presave events) |
| `entity_type` | The entity type ID (e.g., `node`, `user`) |
| `entity_id` | The entity ID |
| `bundle` | The entity bundle (e.g., `article`, `page`) |
| `is_new` | Whether the entity is newly created |
| `timestamp` | Unix timestamp of the event |

You can access these values in your workflow using nodes like **DataExtractor** to pull out specific fields.

## Managing Trigger Configurations

### Viewing Triggers

Navigate to **Administration > FlowDrop > Triggers** (`/admin/flowdrop/triggers`) to see all active trigger configurations.

### Trigger Settings

Configure global trigger settings at **Administration > FlowDrop > Configuration > Triggers** (`/admin/flowdrop/config/triggers`):

- **General settings** — Default orchestrator and logging options
- **Entity settings** — Entity event configuration
- **User settings** — User event configuration
- **Cron settings** — Cron schedule configuration

### Disabling a Trigger

To temporarily disable a trigger without removing it:

1. Navigate to the trigger configuration list.
2. Edit the trigger configuration and set it to disabled.

Alternatively, disabling the parent workflow will prevent all its triggers from firing.

## Troubleshooting

### Trigger not firing?

1. **Check the workflow is enabled** — Disabled workflows ignore triggers.
2. **Check conditions match** — Entity type and bundle must match the actual entity.
3. **Check queues** — Async triggers need queue processing. Run `drush queue:run flowdrop_runtime_pipeline_execution`.
4. **Check logs** — Look for trigger-specific log entries:
   ```bash
   drush watchdog:show --type=flowdrop_trigger
   ```

For more troubleshooting help, see the [Troubleshooting](troubleshooting.md) guide.

## Next Steps

- **[Execution Modes](execution-modes.md)** — Understand orchestrators and queue processing
- **[Monitoring Workflows](monitoring-workflows.md)** — Track triggered workflow execution
- **[Troubleshooting](troubleshooting.md)** — Common issues and solutions
