# Entity Triggers

> Automatic actions and state machines bound to record events.

## Overview

Entity Triggers run an automatic action whenever something happens in your Custom Entities. "When a new request record is created, notify the responsible team", "when an order record is updated, inform another system", "when the status moves to Done, fill in the completion date automatically" — you hand these rules to the platform instead of tracking them by hand.

Every trigger answers three questions: **when** (a record is created, updated, deleted, or a specific field changes), **under what condition** (optional — for example only if an amount exceeds a threshold), and **what to do** (send a notification, call an external service, or fill in a field automatically). You set the rules; the platform carries them out.

Triggers run **in the background**: the person creating the record gets an instant response while the action runs separately. If an action temporarily fails, the platform retries it automatically; jobs that keep failing are collected in a separate list, so no event disappears silently. For safety, triggers only run permitted action types, and one trigger is prevented from putting another into an endless loop.

## Who uses it

- **Process owners:** People who want to automate repetitive manual steps such as sending notifications, filling fields, or alerting another team.
- **Organization administrators:** People who define what happens on which event for which entity and manage the triggers.
- **Integration owners:** People who want to inform an external system (for example an accounting or notification service) when a record changes.

For example, a support team sets up a trigger so the owner is notified when a new complaint record is opened; a sales team calls an external service to start invoicing when an order is approved.

## Step-by-step process

1. **Choose an entity.** Decide which Custom Entity the trigger is for and open that entity's Triggers section.
2. **Pick the event.** Choose when the trigger fires: when a record is created, updated, deleted, or when a specific field changes.
3. **Add a condition (optional).** If you want the action to run only in a specific situation rather than every time, define a condition — for example only when priority is "High".
4. **Choose the action.** Decide what to do: send a notification, make a safe call to an external service (a webhook), or fill in one of the record's fields automatically.
5. **Enter the action settings.** Provide what the chosen action needs: recipient and message for a notification, target address for an external call, or which field takes which value for a field fill.
6. **Activate the trigger.** Once you save, the trigger becomes active. You can deactivate or edit it at any time, or define several triggers for the same event to run in order.

## Process flow

```mermaid
flowchart TD
    A[Record created / updated / deleted] --> B{Is there a matching trigger?}
    B -- No --> Z[Nothing happens]
    B -- Yes --> C{Is the condition met?}
    C -- No --> Z
    C -- Yes --> D[Action runs in the background]
    D --> E{Successful?}
    E -- Yes --> F[Completed]
    E -- No --> G[Retry automatically]
    G --> H[If still failing, flag in a separate list]
```

## Frequently asked questions

**Do I have to wait for the trigger while saving my record?**
No. Actions run in the background; you get your response the moment you create the record. Even if an external service responds slowly, you do not wait.

**What happens if an action fails?**
The platform retries the action automatically a few times. If it still fails after a set number of attempts, the job is flagged in a separate list and kept for review — it does not vanish silently.

**Is it safe to call an external system?**
Yes. External calls only go to safe addresses (over an encrypted connection), and access to internal network or system addresses is blocked. This keeps a trigger from reaching sensitive internal resources.

**Can one trigger fire another and create an endless loop?**
No. The platform limits the length of chains where one record change triggers another. This protection cuts off endless loops from the start.

**Can I define more than one trigger for the same event?**
Yes. For example, when a record is created you can both send a notification and fill in a field. You can order the triggers and keep each one active or inactive independently.

**Can users write their own code in a trigger?**
For safety, triggers only run predefined, safe action types (notification, external call, field fill). Running free-form code is not part of this scope; more advanced automation needs are handled through separate, controlled paths.