> 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-fields.md).

# TaskFields

## Introduction

`TaskFields` define which values users can enter while progressing or finishing a [TaskExecution](/api-reference/tasks-2/task-executions.md).

They are stored as decorated form fields on [TaskTemplates](/api-reference/tasks-2/task-templates.md).

Rich-text values in `default_value` and type-specific `config` keys use the shared [Rich Text](/introduction/rich-text.md) HTML format. This applies to the `rich-text` and `description` type values and the `privacy-policy` type's `config.text` value.

## Model Definition

**Alias**

`formField`

**Relations**

| Key                   | Relation                                                                                   | Type       | Relation Field(s)                      |
| --------------------- | ------------------------------------------------------------------------------------------ | ---------- | -------------------------------------- |
| `form`                | [TaskTemplate](/api-reference/tasks-2/task-templates.md)                                   | Belongs to | `form_id`, `form_type`                 |
| `fieldType`           | [TaskFieldTypes](/api-reference/tasks-2/task-field-types.md)                               | Belongs to | `form_field_type_id`                   |
| `fieldValidations`    | [TaskFieldValidations](/api-reference/tasks-2/task-field-validations.md)                   | Has many   | `form_field_validations.form_field_id` |
| `defaultValueSources` | [TaskFieldDefaultValueSources](/api-reference/tasks-2/task-field-default-value-sources.md) | Has many   | `default_value_sources.form_field_id`  |
| `displayConditions`   | [TaskFieldDisplayConditions](/api-reference/tasks-2/task-field-display-conditions.md)      | Morph many | `attachable_type`, `attachable_id`     |

**Computed Properties**

* `key_id` - Stable DOM-style key in the form `field-{id}`.

**Capabilities**

* [Entity Permissions](/introduction/resource-capabilities/entity-permissions.md) - Task fields inherit administration and viewing access through their parent template.
* [Translations](/introduction/resource-capabilities/translations.md) - `name`, `default_value`, `placeholder`, and `description` are translatable; individual field types can add translatable configuration keys.

## Admin: List

List all `TaskFields` in administration scope.

**Definition**

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

**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/fields', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 33,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "text",
    "lang_id": "en-US",
    "name": "Comment",
    "key": "comment",
    "config": {
      "scanner": false
    }
  },
  {
    "id": 34,
    "form_type": "taskTemplate",
    "form_id": 22,
    "form_field_type_id": "boolean",
    "lang_id": "en-US",
    "name": "Equipment operational",
    "key": "equipment-operational",
    "config": {
      "type": "labeled_buttons",
      "representation": {
        "true": "Yes",
        "false": "No"
      }
    }
  }
]
```

## Admin: List by Template

List all `TaskFields` for one `TaskTemplate` in administration scope.

**Definition**

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

**Route Parameters**

| Parameter    | Type      | Description     |
| ------------ | --------- | --------------- |
| `formEntity` | `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/21/fields', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 33,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "text",
    "lang_id": "en-US",
    "name": "Comment",
    "key": "comment",
    "config": {
      "scanner": false
    }
  },
  {
    "id": 35,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "datetime",
    "lang_id": "en-US",
    "name": "Inspection time",
    "key": "inspection-time",
    "config": {
      "type": "datetime",
      "format": "DD.MM.YYYY HH:mm"
    }
  }
]
```

## Admin: Create

Create a new `TaskField`.

**Definition**

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

**Request Keys**

| Key                    | Type      | Default             | Description                                                                 |
| ---------------------- | --------- | ------------------- | --------------------------------------------------------------------------- |
| `form_type`\*          | `string`  | -                   | Morph alias of container entity. Use `taskTemplate`.                        |
| `form_id`\*            | `integer` | -                   | Related [TaskTemplate](/api-reference/tasks-2/task-templates.md) ID.        |
| `form_field_type_id`\* | `string`  | -                   | Type key from [TaskFieldTypes](/api-reference/tasks-2/task-field-types.md). |
| `lang_id`              | `string`  | system language     | Language key for translated field text.                                     |
| `name`\*               | `string`  | -                   | Field label shown in task UI.                                               |
| `slug`                 | `string`  | derived from `name` | Technical slug, normalized automatically.                                   |
| `default_value`        | `mixed`   | `null`              | Static default value.                                                       |
| `placeholder`          | `string`  | `null`              | Placeholder text.                                                           |
| `description`          | `string`  | `null`              | Help text shown in UI.                                                      |
| `hidden`               | `boolean` | `false`             | Hide field in UI.                                                           |
| `disabled`             | `boolean` | `false`             | Disable field input.                                                        |
| `config`               | `object`  | type defaults       | Type-specific configuration object.                                         |

Keys with `*` are required.

**Behavior**

* `user_id` is set to the authenticated user.
* `slug` is normalized and stored as the response field `key`.
* Missing `config` values are completed from the selected field type's defaults before validation.

**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/fields', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'form_type' => 'taskTemplate',
        'form_id' => 21,
        'form_field_type_id' => 'text',
        'lang_id' => 'en-US',
        'name' => 'Comment',
        'config' => [
            'scanner' => false
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 33,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "text",
    "lang_id": "en-US",
    "name": "Comment",
    "key": "comment",
    "config": {
      "scanner": false
    },
    "hidden": false,
    "disabled": false
  }
}
```

## Admin: Update

Update an existing `TaskField`.

**Definition**

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

**Route Parameters**

| Parameter   | Type      | Description         |
| ----------- | --------- | ------------------- |
| `formField` | `integer` | Field ID to update. |

**Request Keys**

| Key                  | Type      | Description                          |
| -------------------- | --------- | ------------------------------------ |
| `form_field_type_id` | `string`  | New field type key.                  |
| `lang_id`            | `string`  | New language key.                    |
| `name`               | `string`  | New label.                           |
| `slug`               | `string`  | New technical slug.                  |
| `default_value`      | `mixed`   | New static default value.            |
| `placeholder`        | `string`  | New placeholder text.                |
| `description`        | `string`  | New help text.                       |
| `hidden`             | `boolean` | New hidden state.                    |
| `disabled`           | `boolean` | New disabled state.                  |
| `config`             | `object`  | Updated type-specific configuration. |

**Behavior**

* `form_id`, `form_type`, and `user_id` cannot be changed by this endpoint.
* Changing `name` without supplying `slug` regenerates the normalized response `key`.

**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/fields/33', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Comment (updated)'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 33,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "text",
    "lang_id": "en-US",
    "name": "Comment (updated)",
    "key": "comment-updated",
    "config": {
      "scanner": false
    }
  }
}
```

## Admin: Delete

Delete an existing `TaskField`.

**Definition**

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

**Route Parameters**

| Parameter   | Type      | Description |
| ----------- | --------- | ----------- |
| `formField` | `integer` | Field 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/fields/33', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

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

## Entity-Select Helpers

These routes are relevant for `entity-select` and `entities-select` fields. Entity lists and filter-option lists use [count-less pagination](/introduction/query-manipulation/result-control.md#count-less-pagination), so their `total` value is `null`.

## List Preselected Entities

List entities preselected for one `TaskField`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/templates/fields/{formField}/preselected-entities`

**Route Parameters**

| Parameter   | Type      | Description                                    |
| ----------- | --------- | ---------------------------------------------- |
| `formField` | `integer` | `entity-select` or `entities-select` field ID. |

**Request Keys**

| Key        | Type      | Default     | Description       |
| ---------- | --------- | ----------- | ----------------- |
| `page`     | `integer` | `1`         | Result page.      |
| `per_page` | `integer` | API default | Results per page. |

**Behavior**

* Results are derived from the field's `default_value`; the example field stores user IDs `3,4`.

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/templates/fields/40/preselected-entities', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => [
        'page' => 1,
        'per_page' => 10
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "data": [
    {
      "id": 3,
      "title": "Alice Adams",
      "sub_title": "alice.adams",
      "url": "/users/3",
      "tags": []
    },
    {
      "id": 4,
      "title": "Ben Brown",
      "sub_title": "ben.brown",
      "url": "/users/4",
      "tags": []
    }
  ],
  "current_page": 1,
  "total": null,
  "per_page": 10
}
```

## List Selectable Entities

List entities selectable for one `TaskField`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/templates/fields/{formField}/selectable-entities`

**Route Parameters**

| Parameter   | Type      | Description                                    |
| ----------- | --------- | ---------------------------------------------- |
| `formField` | `integer` | `entity-select` or `entities-select` field ID. |

**Request Keys**

| Key        | Type      | Default     | Description                                                                            |
| ---------- | --------- | ----------- | -------------------------------------------------------------------------------------- |
| `page`     | `integer` | `1`         | Result page.                                                                           |
| `per_page` | `integer` | API default | Results per page.                                                                      |
| `filter`   | `object`  | `{}`        | Optional [Result Control](/introduction/query-manipulation/result-control.md) filters. |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/templates/fields/40/selectable-entities', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'filter' => [
            'id' => ['in' => '3,4']
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "data": [
    {
      "id": 3,
      "title": "Alice Adams",
      "sub_title": "alice.adams",
      "url": "/users/3",
      "tags": []
    },
    {
      "id": 4,
      "title": "Ben Brown",
      "sub_title": "ben.brown",
      "url": "/users/4",
      "tags": []
    }
  ],
  "current_page": 1,
  "total": null,
  "per_page": 15
}
```

## List Selectable-Entity Filters

List selectable-entity filters for one `TaskField`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/templates/fields/{formField}/selectable-entities/filters`

**Route Parameters**

| Parameter   | Type      | Description                                    |
| ----------- | --------- | ---------------------------------------------- |
| `formField` | `integer` | `entity-select` or `entities-select` field ID. |

**Behavior**

* Available filter definitions depend on the field's configured `entity_type`.

**Example Request**

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

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "data": [
    {
      "key": "role.department.id",
      "label": "Department",
      "type": "multi-select",
      "operators": []
    },
    {
      "key": "group_account",
      "label": "Group account",
      "type": "multi-select",
      "operators": [
        "is"
      ]
    }
  ]
}
```

## List Selectable-Entity Filter Options

List options for one selectable-entity filter of a `TaskField`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/templates/fields/{formField}/selectable-entities/{filterKey}/options`

**Route Parameters**

| Parameter   | Type      | Description                                               |
| ----------- | --------- | --------------------------------------------------------- |
| `formField` | `integer` | Field ID.                                                 |
| `filterKey` | `string`  | Multi-select filter key returned by the filters endpoint. |

**Request Keys**

| Key        | Type      | Default     | Description       |
| ---------- | --------- | ----------- | ----------------- |
| `page`     | `integer` | `1`         | Result page.      |
| `per_page` | `integer` | API default | Results per page. |

**Example Request**

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

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/templates/fields/40/selectable-entities/role.department.id/options', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => [
        'page' => 1,
        'per_page' => 10
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "data": [
    {
      "value": 7,
      "label": "Production",
      "additionalData": {}
    },
    {
      "value": 8,
      "label": "Sales",
      "additionalData": {}
    }
  ],
  "total": null,
  "per_page": 10,
  "current_page": 1,
  "last_page": 1
}
```

## Admin: List Preselected Entities

List the configured default entities while administering a task field.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/tasks-2/templates/fields/{formField}/preselected-entities`

**Route Parameters**

| Parameter   | Type      | Description |
| ----------- | --------- | ----------- |
| `formField` | `integer` | Field ID.   |

**Request Keys**

| Key        | Type      | Default     | Description       |
| ---------- | --------- | ----------- | ----------------- |
| `page`     | `integer` | `1`         | Result page.      |
| `per_page` | `integer` | API default | Results per page. |

**Behavior**

* The response is calculated from the field's stored `default_value` and configured entity type.

**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/fields/40/preselected-entities', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => ['page' => 1, 'per_page' => 10]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "data": [
    {
      "id": 3,
      "title": "Alice Adams",
      "sub_title": "alice.adams"
    },
    {
      "id": 4,
      "title": "Ben Brown",
      "sub_title": "ben.brown"
    }
  ],
  "current_page": 1,
  "total": null,
  "per_page": 10
}
```

## Admin: List Selectable Entities

List selectable entities while administering a task field.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/tasks-2/templates/fields/{formField}/selectable-entities`

**Route Parameters**

| Parameter   | Type      | Description |
| ----------- | --------- | ----------- |
| `formField` | `integer` | Field ID.   |

**Request Keys**

| Key        | Type      | Default     | Description                      |
| ---------- | --------- | ----------- | -------------------------------- |
| `page`     | `integer` | `1`         | Result page.                     |
| `per_page` | `integer` | API default | Results per page.                |
| `filter`   | `object`  | `{}`        | Optional Result Control filters. |

**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/fields/40/selectable-entities', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'filter' => [
            'id' => ['in' => '3,4']
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "data": [
    {
      "id": 3,
      "title": "Alice Adams",
      "sub_title": "alice.adams"
    },
    {
      "id": 4,
      "title": "Ben Brown",
      "sub_title": "ben.brown"
    }
  ],
  "current_page": 1,
  "total": null,
  "per_page": 15
}
```

## Admin: List Selectable-Entity Filters

List filter definitions while administering a task field.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/tasks-2/templates/fields/{formField}/selectable-entities/filters`

**Route Parameters**

| Parameter   | Type      | Description |
| ----------- | --------- | ----------- |
| `formField` | `integer` | Field ID.   |

**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/fields/40/selectable-entities/filters', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "data": [
    {
      "key": "role.department.id",
      "label": "Department",
      "type": "multi-select"
    },
    {
      "key": "group_account",
      "label": "Group account",
      "type": "multi-select"
    }
  ]
}
```

## Admin: List Selectable-Entity Filter Options

List options for one multi-select filter while administering a task field.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/tasks-2/templates/fields/{formField}/selectable-entities/{filterKey}/options`

**Route Parameters**

| Parameter   | Type      | Description              |
| ----------- | --------- | ------------------------ |
| `formField` | `integer` | Field ID.                |
| `filterKey` | `string`  | Multi-select filter key. |

**Request Keys**

| Key        | Type      | Default     | Description       |
| ---------- | --------- | ----------- | ----------------- |
| `page`     | `integer` | `1`         | Result page.      |
| `per_page` | `integer` | API default | Results per page. |

**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/fields/40/selectable-entities/role.department.id/options', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => ['page' => 1, 'per_page' => 10]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "data": [
    {
      "value": 7,
      "label": "Production",
      "additionalData": {}
    },
    {
      "value": 8,
      "label": "Sales",
      "additionalData": {}
    }
  ],
  "total": null,
  "per_page": 10,
  "current_page": 1,
  "last_page": 1
}
```

## Related resources

* [TaskFieldTypes](/api-reference/tasks-2/task-field-types.md)
* [TaskFieldValidationTypes](/api-reference/tasks-2/task-field-validation-types.md)
* [TaskFieldValidations](/api-reference/tasks-2/task-field-validations.md)
* [TaskFieldDefaultValueSources](/api-reference/tasks-2/task-field-default-value-sources.md)
* [TaskFieldDisplayConditions](/api-reference/tasks-2/task-field-display-conditions.md)
* [TaskProgressFields](/api-reference/tasks-2/task-progress-fields.md)