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

## Model Definition

**Alias**

`formField`

**Relations**

| Relation                                                                 | Key                | Type       | Relation Field(s)                      |
| ------------------------------------------------------------------------ | ------------------ | ---------- | -------------------------------------- |
| [TaskTemplate](/api-reference/tasks-2/task-templates.md)                 | `form`             | Belongs to | `form_id`, `form_type`                 |
| [TaskFieldTypes](/api-reference/tasks-2/task-field-types.md)             | `fieldType`        | Belongs to | `form_field_type_id`                   |
| [TaskFieldValidations](/api-reference/tasks-2/task-field-validations.md) | `fieldValidations` | Has many   | `form_field_validations.form_field_id` |

## \[Adm.] List

**Definition**

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

**Request Keys**

No additional request keys.

**Example Request**

```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}"]
]);
```

**Example Response**

```json
[
  {
    "id": 33,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "text",
    "name": "Comment",
    "config": {}
  }
]
```

## \[Adm.] List by template

**Definition**

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

**Request Keys**

| Key          | Type    | Default | Description     |
| ------------ | ------- | ------- | --------------- |
| `formEntity` | integer | -       | TaskTemplate ID |

**Example Request**

```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}"]
]);
```

**Example Response**

```json
[
  {
    "id": 33,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "text",
    "name": "Comment",
    "config": {}
  }
]
```

## \[Adm.] Create

**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.

**Example Request**

```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',
        'name' => 'Comment'
    ]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 33,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "text",
    "name": "Comment",
    "config": {},
    "hidden": false,
    "disabled": false
  }
}
```

## \[Adm.] Update

**Definition**

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

**Request Keys**

| Key                  | Type    | Description                          |
| -------------------- | ------- | ------------------------------------ |
| `formField`          | integer | Route parameter. Field ID to update. |
| `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. |

**Example Request**

```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)'
    ]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 33,
    "form_type": "taskTemplate",
    "form_id": 21,
    "form_field_type_id": "text",
    "name": "Comment (updated)",
    "config": {}
  }
}
```

## \[Adm.] Delete

**Definition**

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

**Request Keys**

| Key         | Type    | Default | Description |
| ----------- | ------- | ------- | ----------- |
| `formField` | integer | -       | Field ID.   |

**Example Request**

```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}"]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "count": 1
  }
}
```

## Entity-select helpers

These routes are relevant for `entity-select` and `entities-select` fields.

## List preselected entities

**Definition**

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

**Request Keys**

| Key         | Type    | Default | Description |
| ----------- | ------- | ------- | ----------- |
| `formField` | integer | -       | Field ID.   |

No additional JSON body keys are required.

**Example Request**

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

**Example Response**

```json
[]
```

## List selectable entities

**Definition**

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

**Request Keys**

| Key         | Type    | Default | Description |
| ----------- | ------- | ------- | ----------- |
| `formField` | integer | -       | Field ID.   |

No additional JSON body keys are required.

**Example Request**

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

**Example Response**

```json
[
  {
    "id": 5,
    "title": "Sales"
  }
]
```

## List selectable-entity filters

**Definition**

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

**Request Keys**

| Key         | Type    | Default | Description |
| ----------- | ------- | ------- | ----------- |
| `formField` | integer | -       | Field ID.   |

No additional JSON body keys are required.

**Example Request**

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

**Example Response**

```json
[
  {
    "key": "department",
    "title": "Department"
  }
]
```

## List selectable-entity filter options

**Definition**

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

**Request Keys**

| Key         | Type    | Default | Description |
| ----------- | ------- | ------- | ----------- |
| `formField` | integer | -       | Field ID.   |
| `filterKey` | string  | -       | Filter key. |

No additional JSON body keys are required.

**Example Request**

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

**Example Response**

```json
[
  {
    "key": 5,
    "title": "Sales"
  }
]
```

## 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)