| Status | ||||
|---|---|---|---|---|
|
Using Slack with ProcessMaker I/O
| Table of Contents |
|---|
Video Walk through of this Tutorial
...
| Widget Connector | ||
|---|---|---|
|
General Description
...
Leave Absence Request Use case
This example covers absence requests and approval actions via Slack bot.
Process Description
- A user sends an absence request via a Slack slash command and sets the parameters of this request: from date and to date
- The user gets a message notifying them that their request is pending approval
- The approver gets the request in the Approval channel, makes a decision and clicks the corresponding button
- The user receives a message notifying them about the approver's decision from the Slack bot
Process Scheme
Participants
...
Process name
...
Description
...
Requester
...
The user who requests a day off
...
Approver
...
A user or group of users who have permission to approve a day off in the company
...
Slack Action Receiver
...
The technical process for receiving and processing button responses from Slack
Process Items
The tasks in the process are listed in the table below:
...
Task
...
Type
...
Process
...
Connector
...
Description
...
Time Off Request
...
Start Event
...
Requester
...
...
Starts the Requester process
...
Initiate SlackBot
...
Script Task
...
Requester
...
...
This technical task runs script and sets up the Slack application parameters, such as AppNumber, Dates, Slack bot token and Slack channel name
...
Send Time Off Request
...
Service Task
...
Requester
...
Slack\APIConnector
...
This is where the user requests the time off.
...
Slack Request Sent
...
Intermediate Message Event
...
Requester
...
...
This message event sends the request for approval
...
Approve Request
...
Start Message Event
...
Approver
...
...
This start event is initiated by the Slack Request Sent message event and launches the approver process
...
Slack Response Received
...
Start Event
...
Slack Action
...
...
This event launches the Slack API when the "Approve" or "Reject" button is clicked
...
Parse Payload
...
Script Task
...
Slack Action
...
...
This script decodes JSON and prepares the data to send in the Slack API response to the approver
...
Get Slack Callback
...
Intermediate Message Event
...
Slack Action
...
CorrelationKeys
...
Gets the callback and sends the Slack response to the appropriate process instance
...
Response Confirmation
...
Service Task
...
Slack Action
...
Slack\SendMessageConnector
...
This connector sends the Slack webhook
...
Get Slack Response
...
Intermediate Message Event
...
Approver
...
...
When the approver gets the response from the Slack webhook, the approver can continue with the approval process
...
Send Approval/Send Decline
...
Service Task
...
Approver
...
Slack\APIConnector
...
This is where the approver makes a decision
...
Send Confirmation Request Accepted
...
Service Task
...
Requester
...
Slack\SendMessageConnector
...
This is where the requester gets a message notifying them that their request is being reviewed
...
Decision Made
...
Intermediate Message Event
...
Requester
...
CorrelationKeys
...
This message event sends a notification to the requester with the approver's decision
Forms
Since there are no forms because everything is accessed through Slack, we only need to define the fields that will house the data for each case.
...
Field ID
...
Field Label
...
User Filled
...
Field Type
...
Field Description
...
RequesterUsername
...
Requester Username
...
N
...
String
...
The requester's username
...
RequestorFullname
...
Requester Full Name
...
N
...
String
...
The full name of the requester
...
RequestDate
...
Request Date
...
N
...
Datetime
...
Date of the request
...
TimeOffDateStart
...
Time Off Start
...
Y
...
Datetime
...
Date the time off will start
...
TimeOffDateEnd
...
Time Off End
...
Y
...
Datetime
...
Date the time off will end
...
ReasonForTimeOff
...
Reason For Taking Time Off
...
Y
...
String
...
The reason why the requester is requesting time off
...
Status
...
Status
...
N
...
String
...
The current status of the request. Options are:
{
Pending Approval
Approved
Rejected
}
Messages
All messages will take place in Slack. There will be NO email messages, as that defeats the purpose of Slack. Therefore, all messages will be in the form of formatted webhook messages in either a channel or a private message between the ProcessMaker Bot and the user.
...
Message Title
...
Task
...
Location
...
Content
...
Notification to approver
...
Approve Time Off
...
Channel
...
Hello UserFullname,
A new request for time off has been initiated by RequestorFullname.
RequestorFullname has requested to take time off from TimeOffDateStart until . That would mean a total of TimeOffDateEndTotalTimeOff days off.
Would you like to Approve or Reject this request?
Note: To approve or reject the request, please click on the appropriate text above, or you may type either "/pm-route 253 approve" to approve the request, or "/pm-route 253 reject" to reject the request.
...
Approval notification to requestor
...
Approve Time Off
...
Private Message
...
Hello RequestorFullname,
We just wanted to let you know that you have the best boss in the world!
Your request for time off, from TimeOffDateStart until TimeOffDateEnd has been approved!
For your records, the case number is AppNumber.
Enjoy your time off!
...
Rejection notification to requestor
...
Approve Time Off
...
Private Message
...
Hello RequestorFullname,
We regret to inform you that you have a bad boss!
Your request for time off has been rejected.
For your records, the case number is AppNumber.
Better luck next time!
...
New case note
...
All
...
Private Message
...
Hello UserFullname,
We just wanted to let you know that there has been a new case note added to case number AppNumber.
See below for the full note.
"CaseNote_Content"
Getting Started with Use case
How to Launch an Instance* of ProcessMaker I/O
*ProcessMaker I/O is designed to be installed in the cloud, so in this document an instance refers to an installation of ProcessMaker in a virtual machine or a container.
If you don't have a ProcessMaker I/O instance yet, please:
- Go to the Instance page.
- Click Create an Instance and follow the instructions provided.
...
- Launch an instance of ProcessMaker I/O on the Instance page.
- Copy/remember the instance URL link, these will be required later
- Click on Form examples link
- Switch to Slack tab on the top
- Download Slack BPMN file on your computer
- Click on Import tab on the top left and upload BPMN file from your PC.
How to Set Up a Slack Bot
- Create a Slack app
- Go to https://api.slack.com/apps and click Create New App
- Fill in the App Name field
- Choose the Development Slack Team
- Click on Create App
- Enable Interactive Messages
- After creating an app, click Interactive Messages
- Click on Enable Interactive Messages
- On the next screen in the Request URL field, paste your instance link and add the process name and event action name. For example:
...
- Create a Slash Command
- On the Basic Information page of your app, go to Add features and functionality > Slash Commands
- Click Create New Command
- Command: Fill in any name for the Slack command. In our example it's "absence_request".
- Request URL: Enter the direct instance link. For example:
- https://your-instance-url/api/v1/processes/Slack
- https://your-instance-url/api/v1/processes/Requester/events/TimeOffRequest/webhook
- Usage Hint: Define some parameters for your slash command. For example:
- [fromDate m/d/Y]
- [toDate m/d/Y]
- Save all changes.
- Test the new slash command
- Click on Install App
- Click on Install App
...
- On the Basic Information page of your app, go to Add features and functionality > Bots
- Click Add a Bot User
- Fill in the Default username field, for example: @Absence Request
- Click on Add Bot User
...
How to Set Up a ProcessMaker I/O Instance to Use with Slack
When your Slack bot is created and installed to your team, get a Slack bot token via the Oauth & Permissions tab, accessed under Features in the left menu.
In the Oauth Tokens & Redirect URLs section, click on Copy in the Bot User OAuth Access Token field to copy the Slack bot token to your clipboard.
In ProcessMaker I/O, go to the "Initiate SlackBot" service task and paste the bot token (bot tokens start with "xoxb") into the DataModel 'bot_token' variable.
e.g. $aData['bot_token']='xoxb-161650023927-8rz0xMGgrwsgbGUJj5lMaWiH';
How to Set Up a Channel Name for Approvers
In the "Initiate SlackBot" service task, define the channel name in the DataModel 'channel_name' variable.
e.g. $aData['channel_name']='#testprocess';
Your channel can be private, just create the appropriate permissions in Slack in advance.
Slack Connectors
There are 2 type of connectors available for integration with Slack services:
Slack\SendMessageConnector
This connector sets up and configures communication between Slack Interactive Messages and your process.
Slack\ SlackAPI
...
| Status | ||||
|---|---|---|---|---|
|
Using Slack with ProcessMaker I/O
| Table of Contents |
|---|
Video Walk Through of This Tutorial
If you would like to see the "Leave Absence Request Use Case in Slack" in action, click this video below.
| Widget Connector | ||
|---|---|---|
|
General Description
This use case demonstrates how to use ProcessMaker I/O in combination with Slack. Both software programs provide the tools to build effective processes while satisfying a variety of business needs. One of the added benefits of using ProcessMaker I/O with Slack is the ability to work directly from the Slack bot interface. The user only needs to work in one window rather than switching between windows.
Get Started with the Use Case
Run a ProcessMaker I/O Environment*
*ProcessMaker I/O is an "always on" cloud service. In this document an Environment refers to an installation of ProcessMaker I/O in a virtual machine or a container. This environment is created, run, and managed directly through the ProcessMaker I/O web management console.
If you don't have a ProcessMaker I/O Environment yet, do the following:
- Log on to your ProcessMaker I/O account. If you do not have a free ProcessMaker I/O account, please create one.
- Click the Environment page on the top menu.
- Click the Create Environment button, and then follow the instructions provided.
If you already have a ProcessMaker I/O Environment, do the following:
- Log on to your ProcessMaker I/O account.
- Click the Environment page on the top menu, and then run a ProcessMaker I/O Environment.
- Copy the Environment URL link to remember it for later. This URL is required as your-environment-url. Example: "your-environment-url" is "MYENVIRONMENT.api.processmaker.io", where "MYENVIRONMENT" is your "Processmaker I/O Environment name".
- Click the Environment name to display information about it.
- From the Info tab, click the Example: Click to open link to display the ProcessMaker I/O Examples Portal.
- From the left menu, click the User Subscription with Mailchimp service tab.
- Click the Slack BPMN file link to download the BPMN file to your computer. You will use this BPMN file for this use case.
- From your Environment, click the Import tab, and then click the Choose File button to upload the BPMN file from your computer.
Configure a Slack Bot
Configure a Slack bot to do the following:
- enable interactive messages
- create and test a Slash command
- activate the Slack bot
Follow these steps to configure your Slack bot:
- Create a Slack app:
- Go to https://api.slack.com/apps, and then click the Create New App button.
- Enter the name of the app in the App Name field.
- Choose from the Development Slack Workspace drop-down menu the workspace in which Slack app is to function.
- Click the Create App button.
- Enable interactive messages:
- After creating an app, click Interactive Messages. Juliya Zagoruyko (Unlicensed): Should this read "Interactive Components"? It is labeled so on Slack's API site. Am I incorrect?
- Click the Enable Interactive Messages button. Juliya Zagoruyko (Unlicensed): Should this read "Enable Interactive Components"? It is labeled so on Slack's API site.
- On the next screen in the Request URL field, paste your environment link and then add the process name and event action name. Example: https://your-environment-url/api/v1/processes/Slack%20Action%20Receiver/events/Slack%20Response%20Received/webhook.
- Click the Enable Interactive Components button.
- Create a Slash command. These steps are important to create interactive buttons in Slack messages:
- Under Settings, click the Basic Information page of your app, and then go to Add features and functionality > Slash Commands.
- Click the Create New Command button.
- In the Command field, enter any name for the Slack command. In our example it's "absence_request".
- In the Request URL field, enter the direct API URL link for your ProcessMaker I/O Environment. This value can be copied from the API URL: field in your Environment, as shown below. Example: https://your-environment-url/api/v1/processes/Requester/events/Time%20Off%20Request/webhook.
- In the Usage Hint field, define usage parameters for your slash command. Example:
- [fromDate m/d/Y] to represent the beginning of the requested absence.
- [toDate m/d/Y] to represent the end of the requested absence.
- Click the Save button.
- Test the new Slash command:
- Under Settings, click Install App.
- Go to Slack and then run the command you have created.
- Activate the Slack bot:
- Under Settings, click the Basic Information page of your application, and then go to Add features and functionality > Bots.
- Click the Add a Bot User button.
- In the Default username field, enter the default user name. For example: @Absence Request.
- Click the Add Bot User button.
- Install the application to your team.
- Get a Slack bot token by following these guidelines:
- From the left menu, go to Features > Oauth & Permissions tab.
- In the Oauth Tokens & Redirect URLs section, click the Copy in the Bot User OAuth Access Token field to copy the Slack bot token to your Clipboard. The token starts with 'xoxb' string.
- In ProcessMaker I/O, go to the "Initiate SlackBot" service task and then paste the bot token into the DataModel 'bot_token' variable. For example: $aData['bot_token']='xoxb-161650023927-8rz0xMGgrwsgbGUJj5lMaWiH';
The steps described above are not required, but are useful to modify communication between Slack and your ProcessMaker I/O Environment. To follow along with our example, it is necessary to do these steps as instructed.
Set Up a Channel Name for Approvers
In the "Initiate SlackBot" service task, define the channel name in the DataModel 'channel_name' variable. For example: $aData['channel_name']='#testprocess';
Your channel can be private. Create the appropriate permissions in Slack in advance.
Slack Connectors
The following connectors integrate with Slack services.
Slack\SendMessageConnector
This connector sets up and configures communication between Slack Interactive Messages and your process. Juliya Zagoruyko (Unlicensed): Is there no more information about this connector–parameter descriptions and such?
Slack\SlackAPI
This connector implements integration between your process and the Slack Web API. Juliya Zagoruyko (Unlicensed): Is there no more information about this connector–parameter descriptions and such?
Leave Absence Request: Process Description and Scheme
This use case provides absence requests and approval actions via Slack bot.
Workflow for this use case is as follows:
- A user sends an absence request via a Slack slash command and sets the "from date" and "to date" parameters for this request.
- The user gets a message notifying them that their request is pending approval.
- The approver gets the request in the Approval channel, makes a decision, and then clicks the corresponding button.
- The user receives a message from the Slack bot about the approver's decision.
The graphic below shows the BPMN process scheme.
Process Lane Descriptions
Each process lane in this process is briefly described below.
Process Lane Name | Description |
Requester | A user initiates the process by requesting absence. |
Approver | A user or group of users who have permission to approve a leave of absence. |
Slack Action Receiver | The technical process for receiving and processing button responses from Slack. |
Process Task Descriptions
Tasks in this process are described below in the order they appear in the process scheme from left to right, top to bottom.
Task | Type | Process | Connector | Description |
Time Off Request | start event | Requester | Starts the Requester process. | |
Initiate SlackBot | script task | Requester | This technical task runs script and sets up the Slack application parameters, such as AppNumber, Dates, Slack bot token and Slack channel name. | |
Send Time Off Request | service task | Requester | Slack\APIConnector | This is where the user requests the time off. |
Slack Request Sent | intermediate message event | Requester | This message event sends the request for approval. | |
Approve Request | start message event | Approver | This start event is initiated by the Slack Request Sent message event and launches the approver process. | |
Slack Response Received | start event | Slack Action | This event launches the Slack API when the "Approve" or "Reject" button is clicked. | |
Parse Payload | script task | Slack Action | This script decodes JSON and prepares the data to send in the Slack API response to the approver. | |
Get Slack Callback | intermediate message event | Slack Action | CorrelationKeys | Gets the callback and sends the Slack response to the appropriate process instance. |
Response Confirmation | service task | Slack Action | Slack\SendMessageConnector | This connector sends the Slack WebHook. |
Get Slack Response | intermediate message event | Approver | When the approver gets the response from the Slack webhook, the approver can continue with the approval process. | |
Send Approval/Send Decline | service task | Approver | Slack\APIConnector | This is where the approver makes a decision. |
Send Confirmation Request Accepted | Service Task | Requester | Slack\SendMessageConnector | This is where the requester gets a message notifying them that their request is being reviewed. |
Decision Made | intermediate message event | Requester | CorrelationKeys | This message event sends a notification to the requester with the approver's decision. |
Forms
Since there are no forms because everything is accessed through Slack, we only need to define the fields that will house the data for each case.
Field ID | Field Label | User Filled | Field Type | Field Description |
RequesterUsername | Requester Username | N | String | The requester's username |
RequestorFullname | Requester Full Name | N | String | The full name of the requester |
RequestDate | Request Date | N | Datetime | Date of the request |
TimeOffDateStart | Time Off Start | Y | Datetime | Date the time off will start |
TimeOffDateEnd | Time Off End | Y | Datetime | Date the time off will end |
ReasonForTimeOff | Reason For Taking Time Off | Y | String | The reason why the requester is requesting time off |
Status | Status | N | String | The current status of the request. Options are: |
Messages
All messages will take place in Slack. There will be NO email messages, as that defeats the purpose of Slack. Therefore, all messages will be in the form of formatted webhook messages in either a channel or a private message between the ProcessMaker Bot and the user.
Message Title | Task | Location | Content |
Notification to approver | Approve Time Off | Channel | Hello |
Approval notification to requestor | Approve Time Off | Private Message | Hello |
Rejection notification to requestor | Approve Time Off | Private Message | Hello |
New case note | All | Private Message | Hello |