People Tasks

Appmixer PeopleTask feature allows you to add human entry points in your flows.

Introduction

The Appmixer built-in PeopleTask module allows you to add human decision points in your flows. Each of these decision points create a new task that can either be approved, rejected or due (when the current time passes the "decision by" time configuration of the task). Once the decision is made, the flow continues. As an example, consider a flow for approving employee vacation requests. Your flow may look like this:

Employee vacation requests approvals

When an employee adds a new event in Google Calendar requesting a vacation, the person that's configured as an "approver" receives an email from the “RequestApprovalEmail” component that looks like this:

Request Approval Email

The flow for this particular request is blocked until the approver either approves or rejects this vacation request by clicking on the "Approve"/"Reject" links in their email. If the task is approved, our flow then continues to update the event in Google Calendar by adding a "CONFIRMED" text to the description of the event. If the request is rejected, the employee receives an email that their request was rejected. Both the approver and requester can visit their People Task dashboard that shows them an overview of all their approved/rejected/pending tasks:

People Task Dasbhoard

PeopleTask Components

Appmixer provides two people task components that you can use in your flows: RequestApprovalEmail and RequestApproval. Both are part of the utils.tasks module. Note that both these components are template components and are assumed to be adjusted for your specific needs. For example, you might want to use your own email provider or use your own email template with your own branding and different wording. You might as well have your component send the task requests via SMS instead of email, etc. ...

The implementation of the sample componets is pretty simple since it leverages the built-in PeopleTask REST API. See blow for details.

PeopleTask REST API

Normally, you don't need to deal directly with the PeopleTask REST API unless you have some specific requirements, you need to update the tasks from an external system or if you want to implement your own custom components using the PeopleTask API.

Create a new task

You can create new task by sending an HTTP POST request to the people-task/tasks endpoint:

$ curl -XPOST https://api.appmixer.com/people-task/tasks -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' -d '{ "approver": "david@client.io", "decisionBy": "2020-03-01 19:00:00", "description": "Example description", "requester": "requester@example.com", "title": "My Task title" }'

You should receive a JSON object back that looks like this:

{
"approver": "david@client.io",
"decisionBy": "2020-03-01T18:00:00.000Z",
"description": "Example description",
"requester": "requester@example.com",
"title": "My Task title",
"status": "pending",
"approverSecret": "75a69470a129597b9de7b97829a3501f8fb8ae43e8f818fcae4191552eb70a66",
"requesterSecret": "440197b197b9743b457172d37bcf98db3e006644657f9e19192efcc428125aae",
"created":"2020-02-23T14:39:14.796Z",
"id": "5e528e92095eeb0008b2aa40"
}

Having the ID of the newly created task, you can register a webhook that will be called when the status of the task changes (i.e. from "pending" to e.g. "approved" or "rejected"):

$ curl -XPOST https://api.appmixer.com/people-task/webhooks -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' -d '{ "url": "https://mywebhooks.myserver.com", "taskId": "5e528e92095eeb0008b2aa40" }'

Now when the status of the task changes, the Appmixer engine sends an HTTP POST request to the webhook url registered with the task. In our case, it would send a request to https://mywebhooks.myserver.com with data that looks like this (assuming the task was approved in the meantime):

{
"id": "5e528e92095eeb0008b2aa40",
"title": "My Task title",
"description": "Example description",
"status": "approved",
"approver": "david@client.io",
"requester": "requester@example.com",
"decisionBy": "2020-03-01T18:00:00.000Z",
"decisionMade": "2020-02-23T14:46:39.175Z",
"created": "2020-02-23T14:45:22.669Z",
"mtime": "2020-02-23T14:45:22.669Z"
}

As you can see, the task was approved (status is "approved") and we also receive the time the decision was made on (decisionMade).

Notice also the approverSecret and requesterSecret returned when you create a new task. These secrets allow you list and manipulate tasks of a user for which you have the secret instead of the currently signed-in user (i.e. identified by the token in the Authorization header).

Listing all tasks of a user

To get a list of all the tasks of a user (identified by the "Bearer" token in the "Authorization" header), you can issue a GET request to the /people-task/tasks endpoint:

$ curl -XGET https://api.appmixer.com/people-task/tasks -H 'Authorization: Bearer TOKEN'

The returned JSON may looks like this:

[
{
"id": "5e528de61fb74b0008d524e8",
"title": "My Task title",
"description": "Example description",
"status": "pending",
"approver": "david@client.io",
"requester": "requester@example.com",
"decisionBy": "2020-03-01T18:00:00.000Z",
"created": "2020-02-23T14:36:22.730Z",
"mtime": "2020-02-23T14:36:22.732Z",
"isApprover": true
},
{
"id": "5e529002095eeb0008b2aa41",
"title": "My Task title",
"description": "Example description",
"status": "approved",
"approver": "david@client.io",
"requester": "daviddurman@gmail.com",
"decisionBy": "2020-03-01T18:00:00.000Z",
"decisionMade": "2020-02-23T14:46:55.290Z",
"created": "2020-02-23T14:45:22.669Z",
"mtime": "2020-02-23T14:46:55.293Z",
"isApprover": true
}
]

You can also get all the tasks of a user for which you have a secret (approverSecret or requesterSecret) instead of the currently signed-in user:

$ curl -XGET "https://api.appmixer.com/people-task/tasks?secret=75a69470a129597b9de7b97829a3501f8fb8ae43e8f818fcae4191552eb70a66"

Approving and Rejecting Tasks

To approve or reject tasks, you can issue an HTTP PUT request to the /people-task/tasks/:id/approve or /people-task/tasks/:id/reject endpoints:

$ curl -XPUT https://api.qa.appmixer.com/people-task/tasks/5e528de61fb74b0008d524e8/approve -H 'Authorization: Bearer TOKEN'

or to reject the task:

$ curl -XPUT https://api.qa.appmixer.com/people-task/tasks/5e528de61fb74b0008d524e8/reject -H 'Authorization: Bearer TOKEN'

Appmixer engine then looks up all the webhooks registered for this task and calls these webhooks notifying the receiver about the task status change.

Note that the example above approves/rejects a task that belongs to the signed-in user (i.e. the user identified by the token in the "Authorization" header). However, you can approve/rejects tasks of any user if you have their "approverSecret" (just send a JSON to the same endpoint with { "secret": "MY_APPROVER_SECRET" } )

$ curl -XPUT https://api.qa.appmixer.com/people-task/tasks/5e528de61fb74b0008d524e8/approve -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' -d '{ "secret": "75a69470a129597b9de7b97829a3501f8fb8ae43e8f818fcae4191552eb70a66" }'

PeopleTasks SDK Component

The Appmixer SDK provides a UI widget that allows you to display the approver or requester dashboards. In order to display a dashboard of a user, you need to have the secret that you get when the task is created. This secret is a string that gives you the permission to display a dashboard of the user that the secret belongs to and approve or reject tasks of this user. Usually, this secret is used to construct the URLs that are part of an email - as hyperlinks - sent to the user and that allows the user to approve/reject a task with one single click:

Direct links as part of an email to approve/reject a task or visit a user task dashboard

Therefore, having the secret, you can display the user dashboard with:

var peopleTasks = appmixer.ui.PeopleTasks({ el: '#your-people-tasks' });
peopleTasks.set('secret', '7crn14y8ew7a2c45b413ed7a0788175e764c4a7d11d44289bd2706e09ea4318f');
peopleTasks.open();

And you can also approve/reject a task of any user (assuming you have their "approver" secret):

appmixer.api.approveTask('5e529002095eeb0008b2aa41' /*task ID*/, {
secret: '7crn14y8ew7a2c45b413ed7a0788175e764c4a7d11d44289bd2706e09ea4318f'
});
// or
appmixer.api.rejectTask('5e529002095eeb0008b2aa41' /*task ID*/, {
secret: '7crn14y8ew7a2c45b413ed7a0788175e764c4a7d11d44289bd2706e09ea4318f'
});