> 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/tasks-2/task-templates.md).

# TaskTemplates

## Introduction

`TaskTemplates` store what a task is and how progress is reported.

Templates can have related [TaskFields](/api-reference/tasks-2/task-fields.md) that define which values are captured into [TaskProgressFields](/api-reference/tasks-2/task-progress-fields.md).

[TaskAssignments](/api-reference/tasks-2/task-assignments.md) use template data to create concrete [TaskExecutions](/api-reference/tasks-2/task-executions.md).

The `description` field uses the shared [Rich Text](/introduction/rich-text.md) HTML format.

## Model Definition

**Alias**

`taskTemplate`

**Relations**

| Key               | Relation                                                      | Type             | Relation Field(s)                                  |
| ----------------- | ------------------------------------------------------------- | ---------------- | -------------------------------------------------- |
| `parent`          | [TaskTemplate](/api-reference/tasks-2/task-templates.md)      | Belongs to       | `parent_id`                                        |
| `children`        | [TaskTemplates](/api-reference/tasks-2/task-templates.md)     | Has many         | `parent_id`                                        |
| `taskAssignments` | [TaskAssignments](/api-reference/tasks-2/task-assignments.md) | Has many         | `task_template_id`                                 |
| `taskExecutions`  | [TaskExecutions](/api-reference/tasks-2/task-executions.md)   | Has many through | `task_template_id`, `task_assignment_id`           |
| `formFields`      | [TaskFields](/api-reference/tasks-2/task-fields.md)           | Has many         | `form_fields.form_id`, `form_fields.form_type`     |
| `user`            | [User](/api-reference/users.md)                               | Belongs to       | `user_id`                                          |
| `layouts`         | [Layouts](/api-reference/layouts/layouts.md)                  | Has many         | `layouts.layoutable_type`, `layouts.layoutable_id` |

**Capabilities**

* [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md) - Direct grants participate in template administration access together with ownership and module permissions.
* [Translations](/introduction/resource-capabilities/translations.md) - The `title` and `description` fields are translatable.

## Admin: List

List all `TaskTemplates` in administration scope.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tasks-2/templates`

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 6,
    "lang_id": "en-US",
    "title": "Safety Checklist",
    "description": "<p>Describe your template</p>",
    "parent_id": null,
    "sort_number": 39,
    "user_id": 144,
    "grade_scale": null,
    "tour_enabled": true,
    "quick_assignable": true
  },
  {
    "id": 7,
    "lang_id": "en-US",
    "title": "Equipment Inspection",
    "description": "<p>Inspect the assigned equipment.</p>",
    "parent_id": null,
    "sort_number": 40,
    "user_id": 145,
    "grade_scale": 100,
    "tour_enabled": false,
    "quick_assignable": true
  }
]
```

## List Quick-Assignable Templates

List `TaskTemplates` available for quick assignment.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/templates/quick-assignable`

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 6,
    "lang_id": "en-US",
    "title": "Safety Checklist",
    "quick_assignable": true
  },
  {
    "id": 7,
    "lang_id": "en-US",
    "title": "Equipment Inspection",
    "quick_assignable": true
  }
]
```

## Admin: Show

Show one `TaskTemplate` in administration scope.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tasks-2/templates/{taskTemplate}`

**Route Parameters**

| Parameter      | Type      | Description      |
| -------------- | --------- | ---------------- |
| `taskTemplate` | `integer` | TaskTemplate ID. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 6,
  "lang_id": "en-US",
  "title": "Safety Checklist",
  "description": "<p>Describe your template</p>",
  "parent_id": null,
  "sort_number": 39,
  "user_id": 144,
  "grade_scale": null,
  "tour_enabled": true,
  "quick_assignable": true
}
```

## Admin: Create

Create a new `TaskTemplate`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/tasks-2/templates`

**Request Keys**

| Key                  | Type                | Default         | Description                                                                             |
| -------------------- | ------------------- | --------------- | --------------------------------------------------------------------------------------- |
| `title`\*            | `string`            | -               | Template title.                                                                         |
| `description`        | `string`            | `null`          | Template description.                                                                   |
| `folder_id`          | `integer` \| `null` | `null`          | Related [Folder](/api-reference/folders.md) ID.                                         |
| `parent_id`          | `integer`           | `null`          | Parent template ID.                                                                     |
| `lang_id`            | `string`            | system language | Language key.                                                                           |
| `sort_number`        | `integer`           | auto            | Sort number.                                                                            |
| `grade_scale`        | `integer`           | `null`          | Grade scale.                                                                            |
| `tour_enabled`       | `boolean`           | `false`         | Enables user tour for executions from this template.                                    |
| `quick_assignable`   | `boolean`           | `false`         | Enables quick-assignment usage.                                                         |
| `grade_mode`         | `string` \| `null`  | `null`          | Grade calculation mode.                                                                 |
| `entity_permissions` | `object[]`          | `[]`            | Direct [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md). |

Keys with `*` are required.

**Behavior**

* `user_id` is set to the authenticated user and cannot select another owner.
* Omitting `lang_id` uses the system language; this example supplies `en-US` explicitly.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/tasks-2/templates', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'Safety Checklist',
        'description' => '<p>Describe your template</p>',
        'lang_id' => 'en-US',
        'quick_assignable' => true
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 6,
    "user_id": 144,
    "lang_id": "en-US",
    "title": "Safety Checklist",
    "description": "<p>Describe your template</p>",
    "parent_id": null,
    "sort_number": 39,
    "quick_assignable": true,
    "tour_enabled": false
  }
}
```

## Admin: Update

Update an existing `TaskTemplate`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/administration/tasks-2/templates/{taskTemplate}`

**Route Parameters**

| Parameter      | Type      | Description |
| -------------- | --------- | ----------- |
| `taskTemplate` | `integer` | Template ID |

**Request Keys**

| Key                  | Type                | Default | Description                |
| -------------------- | ------------------- | ------- | -------------------------- |
| `title`              | `string`            | -       | Template title.            |
| `description`        | `string`            | -       | Template description.      |
| `folder_id`          | `integer` \| `null` | -       | Related folder ID.         |
| `parent_id`          | `integer`           | -       | Parent template ID.        |
| `lang_id`            | `string`            | -       | Language key.              |
| `sort_number`        | `integer`           | -       | Sort number.               |
| `grade_scale`        | `integer`           | -       | Grade scale.               |
| `tour_enabled`       | `boolean`           | -       | Tour-enabled flag.         |
| `quick_assignable`   | `boolean`           | -       | Quick-assignable flag.     |
| `grade_mode`         | `string` \| `null`  | -       | Grade calculation mode.    |
| `entity_permissions` | `object[]`          | -       | Direct Entity Permissions. |

**Behavior**

* `user_id` is replaced with the authenticated user when the request is prepared.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/tasks-2/templates/6', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'Safety Checklist (updated)'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 6,
    "user_id": 144,
    "lang_id": "en-US",
    "title": "Safety Checklist (updated)",
    "quick_assignable": true
  }
}
```

## Admin: Delete

Delete an existing `TaskTemplate`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/tasks-2/templates/{taskTemplate}`

**Route Parameters**

| Parameter      | Type      | Description      |
| -------------- | --------- | ---------------- |
| `taskTemplate` | `integer` | TaskTemplate ID. |

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

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