API

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 module in combination with the appmixer.utils.tasks.RequestApproval and appmixer.utils.tasks.RequestApprovalEmail components. Please see the People Tasks tutorial for more details.

Each task carries an email address of the requester and approver of the task together with the 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

GET https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/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").

200

 [{
    "approver": "[email protected]",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "[email protected]",
    "status": "pending",
    "title": "Example title",
    "id": "5da9ed9ff29cd51c5fa27380"
}, {
    "approver": "[email protected]",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "[email protected]",
    "status": "pending",
    "title": "Example title",
    "id": "5da9ed9ff29cd51c5fa27380"
}]

Get Task Count

GET https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/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").

200

{
    "count": 23
}

Get Task

GET https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/tasks/:id

Get a task detail.

Path Parameters

Name	Type	Description
id	string	ID of a task.

200

{
    "approver": "[email protected]",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "[email protected]",
    "status": "pending",
    "title": "Example title",
    "id": "5da9ed9ff29cd51c5fa27380"
}

Create a New Task

POST https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/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.

200

{
    "approver": "[email protected]",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "[email protected]",
    "status": "pending",
    "public": true,
    "title": "Example title",
    "approverSecret": "3dbd67d6db7a2c45b413ed7a0788175e764c4a7d11d44289bd2706e09ea4318f",
    "requesterSecret": "440197b197b9743b457172d37bcf98db3e006644657f9e19192efcc428125aae",
    "id": "5da9ed9ff29cd51c5fa27380"
}

Register a Webhook for a Task

POST https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/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.

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"
}

Delete a Webhook

GET https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/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.

200

Edit a Task

PUT https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/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.

200

{
    "approver": "[email protected]",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "[email protected]",
    "status": "pending",
    "title": "Example title",
    "id": "5da9ed9ff29cd51c5fa27380"
}

Approve a Task

PUT https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/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.

200

{
    "id": "5da9ed9ff29cd51c5fa27380",
    "approver": "[email protected]",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "[email protected]",
    "status": "approved",
    "title": "Example title"
}

Reject a Task

PUT https://api.YOUR_TENANT.appmixer.cloud/plugins/appmixer/utils/tasks/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.

200

{
    "id": "5da9ed9ff29cd51c5fa27380",
    "approver": "[email protected]",
    "decisionBy": "2020-01-01 19:00:00",
    "description": "Example description",
    "requester": "[email protected]",
    "status": "rejected",
    "title": "Example title"
}