People Tasks

Introduction

The Appmixer built-in PeopleTask module allows you to add human decision points in your flows. Each of these decision points creates 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:

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:

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:

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 components is pretty simple since it leverages the built-in PeopleTask REST API. See below 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 a 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": "[email protected]", "decisionBy": "2020-03-01 19:00:00", "description": "Example description", "requester": "[email protected]", "title": "My Task title" }'

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

{
    "approver": "[email protected]",
    "decisionBy": "2020-03-01T18:00:00.000Z",
    "description": "Example description",
    "requester": "[email protected]",
    "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": "[email protected]",
    "requester": "[email protected]",
    "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 to 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 look like this:

[
  {
    "id": "5e528de61fb74b0008d524e8",
    "title": "My Task title",
    "description": "Example description",
    "status": "pending",
    "approver": "[email protected]",
    "requester": "[email protected]",
    "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": "[email protected]",
    "requester": "[email protected]",
    "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/reject 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:

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'
});