# BambooHR

Connect BambooHR to Risotto with OAuth, then use the BambooHR runbook templates for time off and home address requests

Connect BambooHR as your HRIS to power employee self-service. Once BambooHR is connected:

- The support agent can look up the requester's employee record. Turn this on with **Agent access** on the **People** tab of [Support agent > Context](https://www.tryrisotto.com/docs/dashboard/settings/support-agent/context#people).
- The BambooHR runbook templates handle time off and home address requests. See [Set up time off and home address requests](#set-up-time-off-and-home-address-requests).
- BambooHR employee events can start [automations](#automation-triggers).

## How the integration works

Risotto connects to BambooHR through BambooHR's OAuth 2.0 authorization flow. Each Risotto org installs against a single BambooHR tenant identified by your **company subdomain** (the `acme` in `acme.bamboohr.com`). After install, Risotto stores access and refresh tokens scoped to that tenant and uses them to call the BambooHR REST API on your behalf.

When an employee asks Risotto something that needs HRIS data (for example, "What's my PTO balance?"), Risotto resolves their BambooHR employee record by matching their work email, then calls only the BambooHR endpoints required to answer that request.

## Install from BambooHR

You must be a BambooHR admin to approve the install.

1. **Open the Connect BambooHR dialog**

   Go to **Settings > Integrations** and click **BambooHR**, in the **HRIS** category. On the **API access** card, click **Connect**.

2. **Enter your company subdomain**

   In the **Connect BambooHR** dialog, enter your **Company Subdomain**, the `acme` part of `acme.bamboohr.com`, and click **Continue**.

   *Product example: The Connect BambooHR dialog in the Risotto dashboard, with a company subdomain entered.*

3. **Approve the install in BambooHR**

   You'll be redirected to your BambooHR tenant (`acme.bamboohr.com`) to sign in and approve the requested OAuth scopes for the Risotto app. BambooHR redirects you back to the Risotto dashboard once the install is complete.

4. **Confirm the connection**

   Risotto opens the **BambooHR** integration page. A toast confirms "BambooHR connected successfully", and the **API access** card shows **Connected**. If the install fails, the toast starts with "BambooHR connection failed".

> **Note:** The subdomain accepts letters, numbers, and hyphens only, and cannot start or
> end with a hyphen. If you're unsure of your subdomain, check the URL you use
> to sign in to BambooHR.

## Requested OAuth scopes

During install, Risotto requests the following BambooHR OAuth scopes:

| Scope                              | Purpose                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| `offline_access`                   | Issue refresh tokens so Risotto keeps access without re-prompting your admin |
| `openid`, `email`                  | Identify the BambooHR account that approved the install                      |
| `employee`                         | Read basic employee records                                                  |
| `employee:name`                    | Read first, last, display, and preferred name                                |
| `employee:contact`                 | Read work and home email                                                     |
| `employee:job`                     | Read job title, department, division, location, hire date, and supervisor    |
| `employee:management`              | Read manager / supervisor relationships                                      |
| `sensitive_employee:address`       | Read the employee's home address                                             |
| `sensitive_employee:address.write` | Update the employee's home address                                           |
| `time_off`                         | Read PTO policy types, balances, and existing time off requests              |
| `time_off.write`                   | Submit time off requests on behalf of the requesting employee                |

## Data fields that sync

Risotto reads only the fields it needs to fulfill an active request. Risotto writes to BambooHR only when a runbook uses the **Request BambooHR Time Off** or **Update BambooHR Home Address** tool.

### Employee profile (read)

Pulled from `GET /api/v1/employees/{id}`:

| BambooHR field            | Used for                                                       |
| ------------------------- | -------------------------------------------------------------- |
| `firstName`, `lastName`   | Name resolution and personalization                            |
| `displayName`             | Preferred display name in Risotto responses                    |
| `preferredName`           | Fallback display name when `displayName` is empty              |
| `workEmail`               | Primary identifier matched against the requester's Slack email |
| `homeEmail`               | Secondary identifier when `workEmail` is missing               |
| `jobTitle`                | Employee profile lookups                                       |
| `department`              | Employee profile lookups                                       |
| `division`                | Employee profile lookups                                       |
| `location`                | Work location lookups                                          |
| `hireDate`                | Start date lookups                                             |
| `supervisor`              | "Who's my manager?" style lookups                              |
| `supervisorEmail`         | Routing requests that need manager approval                    |
| `employmentHistoryStatus` | Detecting whether the employee is currently active             |

### Home address (read and write)

Pulled from `GET /api/v1/employees/{id}` when address access is needed, and written back via `POST /api/v1/employees/{id}` by the **Update BambooHR Home Address** tool:

| BambooHR field | Used for              |
| -------------- | --------------------- |
| `address1`     | Street address line 1 |
| `address2`     | Street address line 2 |
| `city`         | City                  |
| `state`        | State or province     |
| `country`      | Country               |
| `zipcode`      | Postal / ZIP code     |

### Time off (read and write)

| BambooHR endpoint                                          | Used for                                                                                            |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `GET /api/v1/employees/{id}/time_off/calculator`           | Current balance, units (hours or days), and policy type for each plan the employee is assigned to   |
| `GET /api/v1/time_off/requests` (filtered by `employeeId`) | Recent and upcoming time off requests for the employee                                              |
| `PUT /api/v1/employees/{id}/time_off/request`              | Submit a new time off request. Requests are created with status `requested` and routed for approval |

> **Note:** Discretionary and manual BambooHR policies don't track a running balance, so
> Risotto surfaces those as "no tracked balance" rather than a literal `0`.

## Set up time off and home address requests

Time off and home address requests use the BambooHR runbook templates in **Runbooks** > **Templates**. Each template needs BambooHR tools, which you create from the template's page.

| Template                         | What the agent does                                                                                               | Tools it needs                                                   |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **BambooHR Time Off Request**    | Looks up the requester's balances and submits time off requests in BambooHR. Changes to booked time off go to HR. | **Get BambooHR Time Off Balance**, **Request BambooHR Time Off** |
| **BambooHR Time Off Balance**    | Looks up the requester's balances. Escalates every request to take, change, or cancel time off to HR.             | **Get BambooHR Time Off Balance**                                |
| **BambooHR Home Address Update** | Looks up the requester's home address, confirms the new address with them, and saves it in BambooHR.              | **Get BambooHR Home Address**, **Update BambooHR Home Address**  |
| **BambooHR Home Address Lookup** | Looks up the requester's home address. Collects a new address and escalates the change to HR.                     | **Get BambooHR Home Address**                                    |

Each pair matches the same requests, so turn on only one template of each pair. The other BambooHR template is **BambooHR Support**, which gives guidance from your knowledge base and BambooHR's documentation. If it is on, it also matches some time off and address requests. Remove those terms from its conditions, or turn it off.

1. **Find the BambooHR templates**

   Go to **Runbooks** and click **Browse templates**. Type `BambooHR` in **Search templates**. The **HR** group lists the time off and home address templates.

   *Product example: Runbook templates in the Risotto dashboard, searched for BambooHR, with the BambooHR HR templates listed.*

2. **Open a template**

   Click the template, for example **BambooHR Time Off Request**. The page shows the template's match condition, its agent instructions, the **Required tools**, and **Tips** in the side panel.

3. **Create the required tools**

   Under **Required tools**, click **Create** beside each tool that shows **Not set up**. The tool editor opens for that tool. Keep **Restrict to Requestor Only** on, so the tool works only on the requester's own record. To have a person review each time off request or address change before it reaches BambooHR, turn on **Requires Approval** on the request or update tool. Save the tool, and the dashboard returns to the template. If a tool shows **Disabled**, click **Enable**.

4. **Use the template**

   Click **Use this template**. The button is available once every required tool is ready. If your organization has more than one tool for a required tool, the **Choose tool instances** dialog asks which one to use: pick one for each and click **Continue**. The runbook editor opens with the template filled in. Save the runbook and turn it on, as in [Create a runbook](https://www.tryrisotto.com/docs/dashboard/runbooks#create-a-runbook).

   *Product example: The BambooHR Time Off Request template page in the Risotto dashboard, with the Use this template button.*

The templates act only for the requester. Before the agent submits time off or changes an address, it confirms the details with the requester and waits for their reply. For a time off type counted in days, the agent requests 1 for each full day, or a part such as 0.5 for a half day. For a type counted in hours, it asks how many hours.

## Runbook tools

You can also add BambooHR tools to your own [runbooks](https://www.tryrisotto.com/docs/dashboard/runbooks). Create them on the [Tools](https://www.tryrisotto.com/docs/dashboard/tools) page:

| Tool                              | What it does                                                          |
| --------------------------------- | --------------------------------------------------------------------- |
| **Get BambooHR Employee Info**    | Reads the employee's profile from BambooHR                            |
| **Get BambooHR Time Off Balance** | Reads the employee's balances and the time off types they can request |
| **Request BambooHR Time Off**     | Submits a time off request with status `requested`                    |
| **Get BambooHR Home Address**     | Reads the employee's home address                                     |
| **Update BambooHR Home Address**  | Changes the employee's home address in BambooHR                       |

- Each tool has a **Restrict to Requestor Only** option, which is on by default. When it is on, the tool works only for the requester of the ticket.
- **Request BambooHR Time Off** needs the employee's confirmation, given after the agent asks for it. It does not submit a request for a time off type the employee cannot use, for dates that already have time off, or for more time than the balance allows. Requests follow your BambooHR approval flow.

## Terminated employees

When the BambooHR webhook reports that an employee's status changed to **Terminated**, or that the employee was deleted, Risotto marks the employee inactive and stops looking up their BambooHR record. The BambooHR tools and the employee record lookup then find no record for them. This needs the [webhook](#configure-the-webhook). A status change back from **Terminated** makes the employee active again.

## Automation triggers

BambooHR employee events can start a Risotto [automation](https://www.tryrisotto.com/docs/dashboard/automations). The events come from a BambooHR webhook, so an admin must configure the webhook first.

### Configure the webhook

1. **Open the webhook dialog**

   On the **BambooHR** integration page (**Settings > Integrations > BambooHR**), click **Connected** on the **API access** card, then click **Configure webhook...**. Click the copy button beside the **Webhook URL** in the **Configure BambooHR webhook** dialog.

2. **Create the webhook in BambooHR**

   In BambooHR, go to **Settings > Account > Webhooks** and create a webhook with the URL. Subscribe to the `Employee Created`, `Employee Updated`, and `Employee Deleted` events, and to the fields `Employment Status`, `Employment status comments`, and `Employment status: Date`. In the Data section, select `JSON` for the data format.

3. **Save the signature key in Risotto**

   Copy the private signature key of the webhook from BambooHR. Paste it in the **Private Signature Key** field of the dialog, then click **Save**. Risotto uses the key to check that each event comes from BambooHR. The key is write-only. To replace it, paste a new key and click **Save**. To remove it, click **Remove key**.

Until the connection works and the key is saved, the trigger picker shows the BambooHR events as unavailable, with "BambooHR is not connected, needs to be reauthorized, or its webhook is not configured." Only events that BambooHR sends after you configure the webhook start runs.

### Triggers

In the trigger picker, open **BambooHR** and choose an event:

| Trigger                       | BambooHR sends it when                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------ |
| **Employee created**          | HR adds the employee in BambooHR. It comes once, when the record is saved, not on the hire date. |
| **Employment status changed** | The employee's employment status changes, including to **Terminated** or to a custom status.     |
| **Employee terminated**       | The employee's employment status changes to BambooHR's built-in **Terminated** status.           |

- A custom status such as "Resigned" starts only **Employment status changed**. A change to **Terminated** starts both status triggers.
- A rehire uses the existing record in BambooHR, so it does not send **Employee created** again.
- HR often adds the work email after the record is created. Then **Employee created** runs with an empty `employee_email`.
- A status change with an effective date in the future may not send an event on that date.
- When BambooHR deletes an employee, Risotto marks the employee inactive. No automation runs.

### What the automation receives

| Field               | What it holds                                                                   |
| ------------------- | ------------------------------------------------------------------------------- |
| `employee_email`    | The employee's BambooHR `workEmail`, empty when it is not a valid email address |
| `employee_name`     | Their display name, or their first and last name                                |
| `hris_employee_id`  | Their BambooHR employee ID                                                      |
| `event_time`        | When Risotto received the event                                                 |
| `start_date`        | **Employee created** only: the employee's hire date                             |
| `employment_status` | **Employment status changed** only: the new status                              |
| `effective_date`    | **Employment status changed** only: the date the new status takes effect        |
| `end_date`          | **Employee terminated** only: the date the **Terminated** status takes effect   |

When BambooHR has no date on file, the date Risotto received the event stands in for it. An automation runs once for each event, even if BambooHR sends it more than once.

## Disconnecting

To disconnect Risotto from BambooHR, click **Connected** on the **API access** card of the **BambooHR** integration page, then click **Disconnect...**. In the **Disconnect from BambooHR?** dialog, click **Disconnect**. Risotto deletes its stored access and refresh tokens. To fully remove the app from BambooHR, an admin should also revoke the Risotto authorization from **Account > API Keys & Installed Apps** inside BambooHR.

Source: https://www.tryrisotto.com/docs/dashboard/settings/people/connect/bamboohr
