> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/automation/triggers.md).

# Triggers

## Introduction

`Triggers` are the starting point of any automation workflow. They define "when" something should happen. Triggers are attached to "Targetables" (e.g., Models like Users, Documents, etc.) and serve as the anchor for automation rules.

When a Trigger matches an event or schedule, it evaluates its associated Conditions given by the `HasConditions` trait. If the conditions are met, it executes the linked [Actions](/api-reference/automation/actions.md).

Triggers are typically accessed via the `triggers` relation on the targetable entity.

## Model Definition

### Relations

| Key                 | Relation                                             | Type       | Relation Field(s)                  |
| ------------------- | ---------------------------------------------------- | ---------- | ---------------------------------- |
| `actions`           | [Action](/api-reference/automation/actions.md)       | Morph Many | -                                  |
| `conditions`        | [Condition](/api-reference/automation/conditions.md) | Morph Many | -                                  |
| `triggerDispatches` | TriggerDispatch                                      | Has Many   | `trigger_id`                       |
| `targetable`        | (Polymorphic)                                        | Morph To   | `targetable_id`, `targetable_type` |

### Traits

* `HasTargetable`
* `HasConditions`
* `HasActions`
* `SoftDeletes`
* `Sortable`
* `HasFactory`
* `Translatable`

## Supported Entities

The following entities support `Triggers` via the `HasTriggers` trait:

* Form (`Modules\Forms\Entities\Form`)
* TaskTemplate (`Modules\Tasks\Entities\TaskTemplate`)
* PlannedJob (`Modules\Automation\Entities\PlannedJob`)
* Action (`Modules\Automation\Entities\Action`)

## Create

Create a new `Trigger`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/triggers`

**Request Keys**

| Key                 | Type    | Default         | Description                                                                                                            |
| ------------------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `targetable_type`\* | string  | -               | Morph alias of the entity that should own the Trigger. Allowed values: `action`, `form`, `plannedJob`, `taskTemplate`. |
| `targetable_id`\*   | integer | -               | ID of the targetable entity instance.                                                                                  |
| `lang_id`           | string  | system language | Language for translatable Trigger fields. If omitted, the system language is used.                                     |
| `title`\*           | string  | -               | Display title of the Trigger.                                                                                          |
| `allow_parallel`    | boolean | `false`         | Whether multiple executions may run in parallel.                                                                       |
| `active`            | boolean | `true`          | Whether the Trigger is active.                                                                                         |
| `sort_number`       | integer | -               | Sort order within the targetable context.                                                                              |

Keys marked with `*` are required.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/triggers', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'On TaskTemplate Event',
        'targetable_type' => 'taskTemplate',
        'targetable_id' => 123,
        'lang_id' => 'de',
        'allow_parallel' => false,
        'active' => true,
        'sort_number' => 10
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 1,
    "title": "On TaskTemplate Event",
    "targetable_type": "taskTemplate",
    "targetable_id": 123,
    "lang_id": "de",
    "allow_parallel": false,
    "active": true,
    "sort_number": 10,
    "created_at": "2024-01-01 10:00:00",
    "updated_at": "2024-01-01 10:00:00",
    "deleted_at": null
  }
}
```

## Update

Update an existing `Trigger`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/triggers/{trigger}`

**Request Keys**

| Key               | Type    | Default | Description                                                                                               |
| ----------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `targetable_type` | string  | -       | Morph alias of the new targetable entity. Allowed values: `action`, `form`, `plannedJob`, `taskTemplate`. |
| `targetable_id`   | integer | -       | ID of the new targetable entity instance.                                                                 |
| `lang_id`         | string  | -       | Updated language for translatable Trigger fields.                                                         |
| `title`           | string  | -       | Updated title of the Trigger.                                                                             |
| `allow_parallel`  | boolean | -       | Updated parallel execution behavior.                                                                      |
| `active`          | boolean | -       | Updated active state.                                                                                     |
| `sort_number`     | integer | -       | Updated sort order.                                                                                       |

All keys are optional for `Update`.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/triggers/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'Updated Trigger Title',
        'allow_parallel' => true
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 1,
    "title": "Updated Trigger Title",
    "targetable_type": "taskTemplate",
    "targetable_id": 123,
    "lang_id": "de",
    "allow_parallel": true,
    "active": true,
    "sort_number": 10,
    "created_at": "2024-01-01 10:00:00",
    "updated_at": "2024-01-02 11:00:00",
    "deleted_at": null
  }
}
```

## Delete

Delete a `Trigger`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/triggers/{trigger}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/triggers/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": null
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.api.intratool.de/api-reference/automation/triggers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.