# HiBob

Install the Risotto app from the HiBob Marketplace, then use the HiBob runbook templates for time off and home address requests

Connect HiBob as your HRIS to power employee self-service. Once HiBob 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 HiBob runbook templates handle time off requests and home address lookups. See [Set up time off and home address requests](#set-up-time-off-and-home-address-requests).
- HiBob employee events can start [automations](#automation-triggers).

## Install from the HiBob Marketplace

Risotto connects to HiBob through the HiBob Marketplace, which handles authentication. Risotto stores the OAuth tokens automatically. You can start the install from Risotto, as below, or from the Risotto app in the HiBob Marketplace.

1. **Start the install from Risotto**

   Go to **Settings > Integrations** and click **HiBob**, in the **HRIS** category. On the **HiBob app** card, click **Install**. Risotto sends you to HiBob.

   *Product example: The HiBob integration page in the Risotto dashboard, with the Install button on the HiBob app card.*

2. **Approve the install in HiBob**

   Sign in to HiBob as an admin if prompted, then approve the requested permissions for the Risotto app. HiBob redirects you back to the dashboard once the install is complete.

3. **Confirm the connection**

   Risotto opens the **HiBob** integration page. A toast confirms "HiBob connected successfully", and the **HiBob app** card shows **Connected**.

> **Note:** Only HiBob admins can install marketplace apps. If the **Install** button
> redirects you to HiBob without an approval screen, ask an admin in your
> workspace to complete the install.

> **Warning:** A HiBob tenant can only be connected to one Risotto org at a time. If the same
> HiBob tenant is already connected to another Risotto org, the install fails
> with "Please disconnect HiBob from your other Risotto org." Disconnect from
> the other org first, then retry the install. If Risotto cannot verify an
> install that you started in the HiBob Marketplace, it shows "Could not verify
> HiBob install. Please try again."

## Requested permissions

Risotto requests the following HiBob OAuth scopes during install:

| Scope                | Purpose                                                        |
| -------------------- | -------------------------------------------------------------- |
| `employee_data:read` | Look up employees and retrieve home addresses                  |
| `timeoff:read`       | Read PTO policy types, balances, and existing time off entries |
| `timeoff:write`      | Submit time off requests on behalf of the requesting employee  |

## Set up time off and home address requests

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

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

The two time off templates match the same requests, so turn on only one of them. There is no template that changes a home address, because the HiBob public API cannot write addresses. HiBob time off requests are for full days: when the requester wants part of a day off, the agent escalates to HR instead of submitting.

1. **Find the HiBob templates**

   Go to **Runbooks** and click **Browse templates**. Type `HiBob` in **Search templates**. The **HR** group lists the HiBob templates.

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

2. **Open a template**

   Click the template, for example **HiBob 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 before it reaches HiBob, turn on **Requires Approval** on **Request HiBob Time Off**. 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 HiBob 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, it confirms the dates, the time off type, and the amount with the requester and waits for their reply.

## Runbook tools

You can also add HiBob 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 HiBob Employee Information** | Reads the employee's profile from HiBob               |
| **Get HiBob Time Off Balances**    | Reads the employee's time off balances                |
| **Request HiBob Time Off**         | Submits a time off request in HiBob                   |
| **Get HiBob Home Address**         | Reads the home address on the employee's HiBob record |

- 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 HiBob 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, or for dates that already have time off.
- No tool can change a home address, because the HiBob public API cannot write addresses. A runbook can read the current address and tell the employee to edit it in Bob.
- If the connection cannot view the **Address** category in Bob, **Get HiBob Home Address** replies that no home address was found. Check the permission group of the connection in Bob.

## Terminated employees

When HiBob sends the **Employee left** event for an employee, Risotto marks the employee inactive and stops looking up their HiBob record. The HiBob tools and the employee record lookup then find no record for them.

## Automation triggers

HiBob employee events can start a Risotto [automation](https://www.tryrisotto.com/docs/dashboard/automations). HiBob sends the events to the Risotto app that you installed from the HiBob Marketplace, so you do not configure a webhook. If the connection is missing or needs a new install, the trigger picker shows the HiBob events as unavailable, with "HiBob is not connected, or needs to be reinstalled."

### Triggers

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

| Trigger              | HiBob sends it                                                                                                               |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Employee created** | Once, when HR adds the employee in HiBob. This is usually before the start date.                                             |
| **Employee joined**  | At midnight on the employee's start date, in the time zone of their site.                                                    |
| **Employee left**    | At midnight on the employee's termination date or garden leave start, whichever comes first, in the time zone of their site. |

- **Employee joined** and **Employee left** arrive on the effective date, not when HR enters the change in HiBob.
- A rehire sends **Employee joined** again with the new start date, and the automation runs again.
- If HiBob sends the same event again for the same date, Risotto runs the automation only once.
- If the employee has no valid work email, the automation still runs, with an empty `employee_email`. Risotto never uses the personal email.

### What the automation receives

| Field              | What it holds                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `employee_email`   | The employee's HiBob work email, empty when it is not a valid email address                               |
| `employee_name`    | Their display name, or their first name and surname                                                       |
| `hris_employee_id` | Their HiBob employee ID                                                                                   |
| `event_time`       | When Risotto received the event                                                                           |
| `start_date`       | **Employee created** and **Employee joined** only: the employee's start date in HiBob                     |
| `end_date`         | **Employee left** only: the employee's termination date in HiBob, which can be after a garden leave start |

## Troubleshooting

HiBob does not always fail loudly. With valid credentials but missing grants, a people search comes back empty and a profile comes back with fields removed, while the connection still shows as connected. Risotto names the cause in the tool result and, for the sticky cases, sends one admin alert until the grant is fixed.

### Risotto finds no employee, or finds one with only an email

If the connection cannot see any employee at all, Risotto says so: "The HiBob connection is authenticated but cannot see any employees at all." In Bob, add the connection's service user to a permission group whose viewing scope covers employees.

If HiBob returns the employee but the name and other profile fields are missing, Risotto reports that HiBob withheld them. In Bob, grant the connection's permission group view access on the People's data categories (**Basic info** and **Work**).

### Time off requests fail with a permission error

HiBob accepted the credentials but refused the time off read (HTTP 403). In
Bob, grant the connection's permission group view access on the **Time Off**
category.

### Risotto says HiBob rejected the connection's credentials

HiBob answered with HTTP 401. An org admin must reconnect HiBob on the
**HiBob** integration page (**Settings > Integrations > HiBob**).

## Disconnecting

To disconnect Risotto from HiBob, click **Connected** on the **HiBob app** card of the **HiBob** integration page, then click **Disconnect...**. In the **Disconnect from HiBob?** dialog, click **Disconnect**. Risotto deletes its stored tokens and opens the [HiBob Marketplace](https://app.hibob.com/marketplace/manage-apps) in a new tab. Remove the Risotto app there to finish uninstalling it from your workspace.

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