People Tasks
Appmixer PeopleTask feature allows you to add human entry points in your flows.
Last updated
Appmixer PeopleTask feature allows you to add human entry points in your flows.
Last updated
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:
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:
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.
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.
You can create new task by sending an HTTP POST request to the people-task/tasks endpoint:
You should receive a JSON object back that looks like this:
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"):
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):
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).
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:
The returned JSON may looks like this:
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:
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:
or to reject the task:
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" } )
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:
And you can also approve/reject a task of any user (assuming you have their "approver" secret):
