Video Walk through of this Tutorial

If you would like to see this Leave Absence Request Use Case in Slack in action, click this video below.

General Description

This example shows the user how to use ProcessMaker I/O in combination with Slack. Both software programs provide the tools that allow the user 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, meaning that the user only needs to work in one window rather than switching between windows.

Getting Started with Use case

How to Launch an Environment* of ProcessMaker I/O

*ProcessMaker I/O is designed to be installed in the cloud, so in this document an Environment refers to an installation of ProcessMaker I/O in a virtual machine or a container.

If you don't have a ProcessMaker I/O environment yet, please:

  1. Go to the Environment page.
  2. Click Create an Environment and follow the instructions provided.

If you already have a ProcessMaker I/O environment, please:

  1. Launch an environment of ProcessMaker I/O on the Environment page.
  2. Copy/remember the environment URL link, these will be required later as your-environment-url, (as example "your-environment-url" is "MYENVIRONMENT.api.processmaker.io", where "MYENVIRONMENT" is your "Processmaker I/O environment name")
  3. Click on Form examples link
  4. Switch to Slack tab on the top
  5. Download Slack BPMN file on your computer
  6. 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 environment link and add the process name and event action name. For example:

The next step is important for creating interactive buttons in Slack Messages:

  • 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-environment-url/api/v1/processes/Requester/events/Time%20Off%20Request/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 Go to Slack and run the command you've created: Alt text here
  • Activate the Slack Bot

    • 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

The steps listed above are not required, but are useful for modifying communication between Slack and your ProcessMaker I/O environment. To follow along with our example, it is necessary to do these steps as listed.

How to Set Up a ProcessMaker I/O Environment 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

This connector implements integration between your process and the Slack Web API.

Leave Absence Request Use case

This example covers absence requests and approval actions via Slack bot.

Process Description

  1. A user sends an absence request via a Slack slash command and sets the parameters of this request: from date and to date
  2. The user gets a message notifying them that their request is pending approval
  3. The approver gets the request in the Approval channel, makes a decision and clicks the corresponding button
  4. The user receives a message notifying them about the approver's decision from the Slack bot

Process Scheme

Alt text here

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 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 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 APIConnector This is where the approver makes a decision
Send Confirmation Request Accepted Service Task Requester 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 TimeOffDateEnd. That would mean a total of TotalTimeOff 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"