# People Task

The People Task Appmixer module provides an API that lets you create tasks that can be approved or rejected by other people. This module is used by the [appmixer.ui.PeopleTask UI SDK](https://github.com/clientIO/appmixer-docs-gitbook/blob/v5.2.0/api/broken-reference/README.md) module in combination with the appmixer.utils.tasks.RequestApproval and appmixer.utils.tasks.RequestApprovalEmail components. Please see the [People Tasks tutorial](https://docs.appmixer.com/6.0/5.2/tutorials/people-tasks) for more details.

Each task carries an email address of the requester and approver of the task together with title, description and due date. Tasks can have registered webhooks that the Appmixer engine calls when the status of the task changes (pending -> approved and pending -> rejected). Components can register these webhooks and trigger their outputs based on the result of the task resolution.

## Get Tasks

<mark style="color:blue;">`GET`</mark> `https://api.appmixer.com/people-task/tasks`

Return all tasks of a user.

#### Query Parameters

| Name       | Type   | Description                                                                                                                                                                                                                                                                                                    |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| secret     | string | Approver or requester secret. This is the secret that you get in the `approverSecret` or `requesterSecret` property when you create a new task. This secret allows you to list tasks of any user for which you have the secret (instead of just the user identified by the token in the Authorization header). |
| limit      | number | Maximum items returned. Default is 100. Useful for paging.                                                                                                                                                                                                                                                     |
| offset     | number | The index of the first item returned. Default is 0. Useful for paging.                                                                                                                                                                                                                                         |
| projection | string | Exclude task object properties. Example: "-description".                                                                                                                                                                                                                                                       |
| sort       | string | Sorting parameter. Can be any task object property followed by semicolon and 1 (ascending), -1 (descending). Example: "decisionBy:-1".                                                                                                                                                                         |
| filter     | string | Filter tasks by their property values. Example: "status:pending" returns only pending tasks.                                                                                                                                                                                                                   |
| pattern    | string | Filter tasks by a search term (searches the tasks title).                                                                                                                                                                                                                                                      |
| role       | string | Filter tasks by role ("approver" or "requester").                                                                                                                                                                                                                                                              |

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

```javascript
 [{
    "approver": "approver@example.com",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "requester@example.com",
    "status": "pending",
    "title": "Example title",
    "id": "5da9ed9ff29cd51c5fa27380"
}, {
    "approver": "approver@example.com",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "requester@example.com",
    "status": "pending",
    "title": "Example title",
    "id": "5da9ed9ff29cd51c5fa27380"
}]
```

{% endtab %}
{% endtabs %}

## Get Task Count

<mark style="color:blue;">`GET`</mark> `https://api.appmixer.com/people-task/tasks-count`

Get the number of all tasks of a user.

#### Query Parameters

| Name    | Type   | Description                                                                                                                                                                                                                                                                                                |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| secret  | string | Approver or requester secret. This is the secret that you get in the approverSecret or requesterSecret property when you create a new task. This secret allows you to list tasks of any user for which you have the secret (instead of just the user identified by the token in the Authorization header). |
| filter  | string | Filter tasks by their property values. Example: "status:pending" returns only pending tasks.                                                                                                                                                                                                               |
| pattern | string | Filter tasks by a search term (searches the tasks title).                                                                                                                                                                                                                                                  |
| role    | string | Filter tasks by role ("approver" or "requester").                                                                                                                                                                                                                                                          |

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

```
{
    "count": 23
}
```

{% endtab %}
{% endtabs %}

## Get Task

<mark style="color:blue;">`GET`</mark> `https://api.appmixer.com/people-task/tasks/:id`

Get a task detail.

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | ID of a task. |

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

```
{
    "approver": "approver@example.com",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "requester@example.com",
    "status": "pending",
    "title": "Example title",
    "id": "5da9ed9ff29cd51c5fa27380"
}
```

{% endtab %}
{% endtabs %}

## Create a New Task

<mark style="color:green;">`POST`</mark> `https://api.appmixer.com/people-task/tasks`

#### Request Body

| Name        | Type   | Description                                                     |
| ----------- | ------ | --------------------------------------------------------------- |
| decisionBy  | string | Date by which the task is due. ISO 8601 format.                 |
| status      | string | Status of the task. One of "pending", "approved" or "rejected". |
| description | string | The description of the task.                                    |
| title       | string | The title of the task.                                          |
| requester   | string | Requester's email address.                                      |
| approver    | string | Approver's email address.                                       |

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

```
{
    "approver": "approver@example.com",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "requester@example.com",
    "status": "pending",
    "public": true,
    "title": "Example title",
    "approverSecret": "3dbd67d6db7a2c45b413ed7a0788175e764c4a7d11d44289bd2706e09ea4318f",
    "requesterSecret": "440197b197b9743b457172d37bcf98db3e006644657f9e19192efcc428125aae",
    "id": "5da9ed9ff29cd51c5fa27380"
}
```

{% endtab %}
{% endtabs %}

## Register a Webhook for a Task

<mark style="color:green;">`POST`</mark> `https://api.appmixer.com/people-task/webhooks`

Register a new webhook URL for a task. Appmixer will send a POST request to this URL whenever the status of the task changes. This is usually done right after creating a new task so that you can get notified as soon as the task gets approved or rejected.

#### Request Body

| Name   | Type   | Description                                              |
| ------ | ------ | -------------------------------------------------------- |
| url    | string | URL to be triggered when the status of the task changes. |
| taskId | string | ID of a task.                                            |

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

```
{
    "url": "https://api.appmixer.com/flows/551945f2-6bbb-4ea4-a792-fb3635943372/components/a54b47fa-e7ce-463f-87bc-715ceb612947?correlationId=ee325876-4b3e-4537-9a12-58b4929f6cd8&correlationInPort=task",
    "taskId": "1234",
    "status": "pending",
    "id": "5da9ee4cf29cd51c5fa27381"
}
```

{% endtab %}
{% endtabs %}

## Delete a Webhook

<mark style="color:blue;">`GET`</mark> `https://api.appmixer.com/people-task/webhooks/:id`

Delete a previously registered webhook.

#### Path Parameters

| Name | Type   | Description                                                                                       |
| ---- | ------ | ------------------------------------------------------------------------------------------------- |
| id   | string | Webhook ID, i.e. the `id` returned from the /people-task/webhooks when registering a new webhook. |

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

```
```

{% endtab %}
{% endtabs %}

## Edit a Task

<mark style="color:orange;">`PUT`</mark> `https://api.appmixer.com/people-task/tasks/:id`

Edit an existing task.

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | Id of a task. |

#### Request Body

| Name        | Type   | Description                                                         |
| ----------- | ------ | ------------------------------------------------------------------- |
| decisionBy  | string | Date by which the task is due. ISO 8601 format.                     |
| status      | string | The status of the task. One of "pending", "approved" or "rejected". |
| description | string | The description of the task.                                        |
| title       | string | The title of the task.                                              |
| requester   | string | Requester's email address.                                          |
| approver    | string | Approver's email address.                                           |

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

```
{
    "approver": "approver@example.com",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "requester@example.com",
    "status": "pending",
    "title": "Example title",
    "id": "5da9ed9ff29cd51c5fa27380"
}
```

{% endtab %}
{% endtabs %}

## Approve a Task

<mark style="color:orange;">`PUT`</mark> `https://api.appmixer.com/people-task/tasks/:id/approve`

This endpoint approves a task triggering all the registered webhooks for this task announcing a new `approved` status.

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | ID of a task. |

#### Request Body

| Name   | Type   | Description                                                                                                                                                                                       |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| secret | string | Approver secret. This is the secret that you get in the `approverSecret` property when you create a new task. This secret allows you to approve a task of any user for which you have the secret. |

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

```
{
    "id": "5da9ed9ff29cd51c5fa27380",
    "approver": "e2etest@gmail.com",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "e2etest@gmail.com",
    "status": "approved",
    "title": "Example title"
}
```

{% endtab %}
{% endtabs %}

## Reject a Task

<mark style="color:orange;">`PUT`</mark> `https://api.appmixer.com/people-task/tasks/:id/reject`

This endpoint rejects a task triggering all the registered webhooks for this task announcing a new `rejected` status.

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | ID of a task. |

#### Request Body

| Name   | Type   | Description                                                                                                                                                                                      |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| secret | string | Approver secret. This is the secret that you get in the `approverSecret` property when you create a new task. This secret allows you to reject a task of any user for which you have the secret. |

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

```
{
    "id": "5da9ed9ff29cd51c5fa27380",
    "approver": "e2etest@gmail.com",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "e2etest@gmail.com",
    "status": "rejected",
    "title": "Example title"
}
```

{% endtab %}
{% endtabs %}