Connecting your bot to an HR system

Knowledge Level: Advanced

Purpose

In this tutorial, we will connect our bot to BambooHR, an HR system to manage employee records.

By the end of the tutorial, the bot will pull holiday information for an employee from BambooHR and post it back to the user in a message. We will use Make(formerly Integromat) as our middleware to trigger a webhook and post the response to the bot user.

Prerequisite

• A bot
• A Make account
• A BambooHR account (you can sign up for a free trial)
• Your favorite beverage

Setting up the bot

The bot setup is fairly simple and will only include two message parts.

• A welcome message with a button
• A confirmation message where the user will be informed that information is being pulled, we will also include our webhook url in this message part to trigger the webhook in Make(formerly Integromat).

Setting up Make(formerly Integromat) scenario

We will use the following modules in our scenario:

• Custom webhook
• BambooHR (List Employees)
• BambooHR (Get an Employee)
• BambooHR (Get summary of Who's out)
• Webhook response

Setup Webhook

First add a custom webhook module. Add a new webhook and give it a suitable name. Now you need to copy the webhook URL and paste it into the webhook message within the last message part of the bot.

Now click the 'Run once' button on your Make(formerly Integromat) scenario and test your bot by going through the message flow and triggering the webhook.

Once the webhook data is received, we should be able to continue building the rest of our Make(formerly Integromat) scenario.

Setup BambooHR List employees module

In this step, we will setup the first BambooHR module to search for employees in the organization. We do this to match the employee id of the bot user to BambooHR, this will let us look for their booked time off in the next steps. We will use email address from the incoming webhook to match the email address of the employee in BambooHR to find their employee id.

Start by adding a new module and look for BambooHR. When setting this up the first time, we will need to authenticate our account with Make(formerly Integromat). Follow the steps by clicking here to complete the authentication.

Once this is done, add the module 'List employees'. In the 'limit' section, set the limit to the number of employees in the organization. For this example, we have set it to 20.

After saving the changes in your scenario, click on 'Run Once' on the BambooHR module. If done correctly, the module will output employee information of your organization. We will need this output to be used in the rest of the scenario.

Setup BambooHR (Get an Employee)

Now, we will add the module 'BambooHR - Get an employee'. This module will provide us with the employee id. Here, we will use the email address received from the webhook to filter out all the employees in the BambooHR system, leaving only the bot user employee id.

In the module configuration, add the 'Employee ID' output from the previous module in the 'Employee ID' section. Under frields, check all the fields you would like to receive information for. In this example, we have only used:

• First name
• Last name
• email address

The fields can vary depending on your use case.

Add a filter between modules

You will notice that the BambooHR get an employee filter does not allow us to filter our data to only find information relative to the bot user. To get around this limitation, we will setup a filter between the 'List Employees' module and the 'Get an Employee' module. We will use the email address in our webhook as the filtering criteria.

Setup BambooHR (Get Summary of Who's Out)

This is our last module before we configure the webhook response to the user. Add the module 'BambooHR - Get Summary of who's out'.

While configuring the module, in the start section we will need the current date to only search for latest records. We can also configure the end date to search for time off within a specific time period. If you leave the end field empty, it will default to 14 days from the start date. In the 'Limit' section, we will limit this with the number of employees in your organisation. For this example, we have set it to 20.

Save the scenario and click on run once. The module should output time off information (start and end dates) along with employee id, name etc.

*Webhook response

Webhook response is our last module in this flow. We use this module to send our response back to the bot user. Here, we will use the outputs from previous modules to compose our message.

Start by adding the module 'Webhook response'. We will use a simple text response to send information back to the user. From the previous modules, we will use the outputs obtained from 'Get Summary of Who's out' module.

Insert the following webhook response JSON in the module:

{
  "recipient": {
    "id": "USER_ID"
  },
  "message": {
    "text": "Hello world"
  }
}

We will modify the above code to fit our response. For the 'id', use the 'FBID' value from the incoming webhook.

For the text, you can use the following: "You are currently booked for time off from (start date) to (end date)". Use the output of dates from the previous module for start and end date. If the output dates of the time-off are not in your preferred date format, you can use the date formatter function in Make(formerly Integromat) to format these.

For our use case, we have formatted the dates to DD/MM/YYYY format. The final webhook response code will look as follows:

{
  "recipient": {
    "id": "{{5.fbuser.fbid}}"
  },
  "message": {
    "text": "You are currently booked for time off from {{formatDate(11.start; "DD/MM/YYYY")}} to {{formatDate(11.end; "DD/MM/YYYY")}}"
  }
}

Filter output to webhook response

Similar to the step above, we need to filter our output from the previous module as we cannot natively filter employees within the module settings. We will use employee ID generated from the 'Get an Employee' module with the id generated from 'Get Summary of Who's Out'.

Make sure to save all the changes. Now, go back to the bot and go through the bot conversation to trigger the webhook. If everything was setup correctly, the bot will respond with the requested information.

If you have booked time-off and it's approved, Happy Holidays! and don't forget to take some pictures of the trip.