# Rippling

Install the Risotto app from the Rippling App Shop to sync your employee roster, then use the Rippling runbook templates for time off and home address requests

Connect Rippling as your HRIS so Risotto can answer employee HR questions directly in Slack instead of routing them to your People team. Once Rippling is connected:

- Risotto syncs your employee roster from Rippling.
- 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 Rippling 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).
- Rippling employee events can start [automations](#automation-triggers).

## Why connect Rippling

- **Deflect repetitive HR tickets**: "How much PTO do I have left?" and "can I take next Friday off?" are among the most common requests People teams receive. Risotto answers them from live Rippling data.
- **Keep your roster current**: Risotto syncs your employee roster from Rippling, so it knows who works there without you maintaining a separate user list.
- **Stop serving former employees**: When someone is terminated in Rippling, Risotto stops looking up their Rippling record.
- **No new surface for employees**: Employees stay in Slack. They don't need to remember where Rippling lives or how to navigate it.

## Prerequisites

Have these in place before you start:

- **A Rippling admin account.** Only Rippling admins can install App Shop apps.
- **A Risotto admin account.** Installing, syncing, and disconnecting all require permission to manage the org.
- **Account provisioning configured for Risotto in Rippling.** Rippling's provisioning rules determine which employees are in scope for Risotto. These rules populate the `PROVISIONING` group that Risotto's roster sync reads; without it, the sync has nothing to reconcile and reports a failure.
- **The Rippling company is not connected to another Risotto org.** One Rippling company maps to exactly one Risotto org.

## Install from the Rippling App Shop

Risotto connects to Rippling through the Rippling App Shop. The App Shop handles authentication and Risotto persists OAuth tokens automatically.

1. **Start the install**

   Find the Risotto app in the [Rippling App Shop](https://app.rippling.com/apps) and click **Install**, or start from the Risotto dashboard: go to **Settings > Integrations**, click **Rippling** in the **HRIS** category, and click **Install** on the **Rippling app** card.

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

2. **Approve the install in Rippling**

   Sign in to Rippling as an admin if prompted, then approve the requested
   permissions for the Risotto app.

3. **Confirm the connection**

   If Rippling asks you to sign in to Risotto, sign in. Risotto finishes the
   install and sends you back to Rippling. To check the result, go to **Settings >
   Integrations** and click the **Rippling** card. The header shows **Connected**,
   and the **Rippling app** card shows the **Employee sync** row. If the install
   fails, Risotto opens this page with an error message.

4. **Turn on what the agent can do**

   Installing the integration syncs your roster, but does not let the agent act in Rippling. To let the agent look up the employee record, turn on **Agent access** on the **People** tab of [Support agent > Context](https://www.tryrisotto.com/docs/dashboard/settings/support-agent/context#people). For time off and home address requests, set up the [Rippling runbook templates](#set-up-time-off-and-home-address-requests).

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

> **Warning:** A Rippling company can only be connected to one Risotto org at a time. If the
> same Rippling company is already connected to another Risotto org, the install
> fails with "Please disconnect Rippling from your other Risotto org."
> Disconnect from the other org first, then retry the install.

## Requested permissions

During install, Risotto requests access to the following Rippling data through the App Shop integration:

| Access           | Purpose                                                                        |
| ---------------- | ------------------------------------------------------------------------------ |
| Employee profile | Look up name, work email, job title, department, work location, and start date |
| Home address     | Read the home address on file for the requesting employee                      |
| Leave balances   | Read PTO policy types and balances for each plan the employee is assigned to   |
| Leave requests   | Read existing time off requests and submit new ones on the employee's behalf   |
| Groups           | Read the provisioning group that defines which employees are in scope          |

> **Note:** Rippling negotiates the exact permission scopes through the App Shop
> integration during approval. Risotto reads only the fields it needs to fulfill
> an active request.

## Data flows

The integration runs four distinct flows. Two keep your roster current in the background; two run only when an employee asks for something.

| Flow                  | Direction          | Trigger                                     |
| --------------------- | ------------------ | ------------------------------------------- |
| Employee roster sync  | Rippling → Risotto | On install, daily, or on demand             |
| Provisioning webhooks | Rippling → Risotto | Rippling sends the event (\~5 minute delay) |
| Employee data lookup  | Rippling → Risotto | An employee asks; read live, nothing stored |
| Time off request      | Risotto → Rippling | An employee asks and confirms               |

### Employee roster sync

Risotto reads the `PROVISIONING` group from Rippling and reconciles its own roster against it. Employees in the group are added or updated; Rippling-sourced identities no longer in the group are marked inactive with an audit entry.

This flow runs at three moments:

- **Once on install**, so a new connection is populated immediately.
- **Once a day**, in an overnight sweep (around 08:20 UTC).
- **On demand**, when an admin clicks **Sync now**.

The sync is idempotent. Re-running it with no upstream change writes nothing. It's also locked per org, so overlapping triggers collapse into the single run already in flight rather than stacking up.

> **Note:** The sync deliberately skips deactivating employees when the picture from
> Rippling looks incomplete such as an empty provisioning group, or a roster too large
> to read in one pass. A misconfigured group won't silently deactivate your
> whole company.

### Provisioning webhooks

Rippling notifies Risotto of employee lifecycle changes as they happen, so terminations don't wait for the overnight sync:

| Event                 | Effect in Risotto                                   |
| --------------------- | --------------------------------------------------- |
| `employee.created`    | Adds the employee to the roster                     |
| `employee.updated`    | Refreshes the stored details for a tracked employee |
| `employee.terminated` | Marks the employee inactive                         |
| `employee.deleted`    | Marks the employee inactive                         |
| `company.deleted`     | Removes the connection and tears down the roster    |

Webhooks are configured on the Risotto app itself, and your Rippling provisioning rules control which employees generate events.

> **Note:** Rippling delivers webhooks with a delay of roughly five minutes.

### Employee data lookup

When an employee asks Risotto for their own HR data, Risotto calls Rippling live and reads only the fields that request needs.

To find the employee, Risotto matches their email against Rippling's `work_email`. The resolved Rippling worker ID is stored on the employee's Risotto identity so later requests skip the lookup.

### Time off request

The only flow that writes to Rippling. When an employee asks for time off, Risotto confirms the details with them first, then creates the request in Rippling with status `pending`, where it enters your normal approval flow. Risotto never approves anything.

### Trigger a sync manually

To force an immediate roster sync without waiting for the overnight run, go to **Settings > Integrations** and click the **Rippling** card. Click **Connected** on the **Rippling app** card, then click **Sync now**.

The **Employee sync** row on the **Rippling app** card shows the result:

| Status line                           | Meaning                                           |
| ------------------------------------- | ------------------------------------------------- |
| `Employee sync in progress...`        | A sync is running now                             |
| `Employees last synced <time>`        | The last sync succeeded                           |
| `Last employee sync failed (<cause>)` | The last sync failed; the cause is in parentheses |

> **Note:** The other three flows can't be triggered by hand, and don't need to be.
> Webhooks are sent by Rippling, and employee lookups and time off requests only
> ever run in response to an employee asking.

## Data fields that sync

Risotto resolves the requesting employee's Rippling worker record by matching their work email, then reads only the fields required to answer that request.

### Employee profile (read)

Pulled from the Rippling `workers` endpoint:

| Rippling field   | Used for                                                           |
| ---------------- | ------------------------------------------------------------------ |
| `work_email`     | Primary identifier matched against the requester's email           |
| `personal_email` | Fallback key when a synced worker has no work email on file        |
| `display_name`   | Preferred display name in Risotto responses                        |
| `title`          | Employee profile lookups                                           |
| `department`     | Employee profile lookups                                           |
| `location`       | Work location lookups                                              |
| `start_date`     | Start date lookups                                                 |
| `status`         | Detecting terminated workers                                       |
| `user.number`    | Rehire-stable employee number used to re-link a returning employee |

> **Note:** Live lookups match on `work_email` only. `personal_email` is used as a
> fallback when the roster sync encounters a worker with no work email — so an
> employee whose Slack email matches neither field won't resolve.

### Home address (read only)

Read from the worker's `HOME`-typed address record:

| Rippling field   | Used for             |
| ---------------- | -------------------- |
| `street_address` | Street address lines |
| `locality`       | City                 |
| `region`         | State or province    |
| `postal_code`    | Postal / ZIP code    |
| `country`        | Country              |

### Time off (read and write)

Rippling stores leave amounts in minutes; Risotto surfaces them in hours.

| Rippling endpoint | Used for                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `leave-balances`  | Current balance and policy type for each plan the employee is assigned to                  |
| `leave-requests`  | Read recent and upcoming time off requests, and submit a new request with status `pending` |

> **Note:** Unlimited PTO policies don't track a running balance, so Risotto surfaces
> those as unlimited rather than a literal number.

## Set up time off and home address requests

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

| Template                         | What the agent does                                                                                               | Tools it needs                                                 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Rippling Time Off Request**    | Looks up the requester's balances and submits time off requests in Rippling. Changes to booked time off go to HR. | **Get Rippling Leave Balances**, **Request Rippling Time Off** |
| **Rippling Time Off Balance**    | Looks up the requester's balances. Escalates every request to take, change, or cancel time off to HR.             | **Get Rippling Leave Balances**                                |
| **Rippling Home Address Lookup** | Looks up the requester's home address. Collects a new address and escalates the change to HR.                     | **Get Rippling 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 Rippling API cannot write addresses. The other Rippling template is **Rippling Support**, which gives guidance from your knowledge base and Rippling'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 Rippling templates**

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

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

2. **Open a template**

   Click the template, for example **Rippling 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 Rippling, turn on **Requires Approval** on **Request Rippling 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 Rippling 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 hours for each day with the requester and waits for their reply.

## Runbook tools

You can also add Rippling 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 Rippling Employee Details** | Reads the employee's profile from Rippling                                                  |
| **Get Rippling Leave Balances**   | Reads the employee's time off balances                                                      |
| **Get Rippling Time Off Entries** | Reads the employee's recent and upcoming time off                                           |
| **Get Rippling Home Address**     | Reads the `HOME` address on the employee's Rippling record                                  |
| **Request Rippling Time Off**     | Submits a time off request with status `pending`, so it follows your Rippling approval flow |

- 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 Rippling 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 in Rippling.
- No tool can change a home address, because the Rippling API cannot write addresses. A runbook can read the current address and tell the employee to edit it in Rippling.

## Terminated employees and rehires

When Rippling marks an employee as terminated or deleted, Risotto receives a webhook, marks the employee inactive, and stops looking up their Rippling record. The Rippling tools and the employee record lookup then find no record for them. The daily roster sync catches anyone a missed webhook left behind.

Rehires are handled automatically. Rippling issues a new worker ID when someone returns, so Risotto re-resolves them on their next request or on the next roster sync and reactivates their record.

## Automation triggers

Rippling employee events can start a Risotto [automation](https://www.tryrisotto.com/docs/dashboard/automations). In the trigger picker, open **Rippling** and choose **Employee created**, **Employee hired**, or **Employee terminated**. After you pick one, the header of the **Trigger** card shows Rippling's own event name. The table uses those names.

To see one onboarding from start to finish, watch [Example: onboard a new hire](https://www.tryrisotto.com/docs/guides/examples/onboarding-video).

| Trigger               | Rippling sends it when                                                                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `employee.created`    | An employee gains access to Risotto in Rippling. All new hires send it, including same-day hires. Existing employees can send it too when access rules change. |
| `employee.hired`      | An employee moves to the **Accepted** status: they accepted their offer or agreements. Same-day hires do not send it.                                          |
| `employee.terminated` | Rippling turns off a terminated employee's access, or an employee is deleted.                                                                                  |

Rippling decides when it sends each event, not Risotto:

- Use `employee.created` to start onboarding. It is the one event every new hire sends. Use `employee.hired` only for a step between offer acceptance and the start date.
- `employee.hired` is not sent when you mark someone **Hired**, or on their start date. A hire you add on their start date goes straight to Active and gets only `employee.created`.
- `employee.created` also comes for an existing employee when an access rule change gives them access to Risotto. A rule change that adds many employees at once starts a run for each one.
- `employee.terminated` comes at the termination's **turn off app access** time. With no time set, that is the day after the last day of work. Saving the last day does not send it, so the event can come days after HR enters the termination.
- Rippling sends events only for employees with access to Risotto within Rippling. An employee your access rules leave out starts no run. `employee.terminated` is the exception: it still comes for an employee the termination itself removes from access.

The triggers need a working Rippling connection. If Rippling is not connected, or its connection needs to be reauthorized, the picker lists the events as unavailable with an **Open Rippling** link. The link opens the Rippling integration page in a new tab.

### What the automation receives

All three triggers record the same fields about the person, which you can pin into instructions:

| Field              | What it holds                                                          |
| ------------------ | ---------------------------------------------------------------------- |
| `employee_email`   | The employee's Rippling `work_email`                                   |
| `employee_name`    | Their display name, empty when Rippling has none                       |
| `hris_employee_id` | Their Rippling worker ID, for looking the record up                    |
| `event_time`       | When Risotto received the event                                        |
| `start_date`       | `employee.created` and `employee.hired` only: the employee's first day |
| `end_date`         | `employee.terminated` only: the employee's last day                    |

When Rippling has no start or end date on file, the date Risotto received the event stands in for it.

> **Note:** Risotto skips an event for a worker with no valid work email, because it
> cannot resolve the event to a person. An automation runs once per employee and
> date for `employee.hired` and `employee.terminated`, and once per employee in
> 24 hours for `employee.created`, even if Rippling delivers an event more than
> once.

## Disconnecting

Rippling stays installed on your org until an admin removes it in Rippling. To start, click **Connected** on the **Rippling app** card of the **Rippling** integration page, then click **Disconnect...**. In the **Disconnect from Rippling?** dialog, click **Continue to Rippling** to uninstall Risotto in the Rippling App Shop.

Uninstalling in Rippling triggers a `company.deleted` webhook, and Risotto then deletes its stored access and refresh tokens and marks every Rippling-sourced employee record inactive.

> **Warning:** Removing the app only in the Risotto dashboard is not enough. Until it's
> uninstalled in Rippling, the connection remains live on Rippling's side.

## FAQs

### Is the provisioning group for the people Risotto helps, or for my IT team?

It is for the people Risotto helps. Your Rippling provisioning rules decide
which employees Risotto knows about. Risotto matches each employee to their
chat account by work email. Your IT team members are not added here. To add
them, [invite them](https://www.tryrisotto.com/docs/guides/invite-users) to the dashboard and to a
department.

### Does Risotto send a message to people when I add them to the provisioning group?

No. The roster sync and the Rippling webhooks only update the records in
Risotto. Risotto does not send an email or a direct message to anyone.
Rippling sends an `employee.created` event for each employee that you add.
If you have an [automation](https://www.tryrisotto.com/docs/dashboard/automations) on the Rippling
**Employee created** trigger, it starts one run for each of those employees.
Check that automation before you add many people at once.

### Can employees look up other people's information?

Not with the Rippling templates. They tell the agent to act only for the
requester, and each Rippling tool has **Restrict to Requestor Only** on by
default, so the tool works only on the requester's own record. An employee
can retrieve their own PTO balance or home address, but cannot ask Risotto
for a colleague's. If you turn **Restrict to Requestor Only** off on a tool,
a runbook that uses it can act for other employees.

### Can a new hire in Rippling open a ticket in Risotto?

Not by itself, but an automation can do it. A Rippling event updates the
roster and does not create a ticket. Create an
[automation](https://www.tryrisotto.com/docs/dashboard/automations) on the Rippling `employee.hired`
trigger and tell it to create the ticket. Rippling sends `employee.hired`
when the hire accepts their offer or agreements, and only for employees in
the Risotto app's provisioning scope. A hire you add on their start date
gets no `employee.hired`, so no run starts. For those hires, or to start
from a step in your Rippling onboarding workflow, create an automation with
a [Webhook trigger](https://www.tryrisotto.com/docs/dashboard/automations#webhook-trigger) and call its URL
from that step.

### Can Risotto approve time off, or change anything else in Rippling?

No. The only write this integration performs is creating a time off request
with status `pending`, which then follows your existing Rippling approval
flow. Risotto cannot approve requests, edit profiles, change addresses, or
modify payroll.

### Does the employee get asked before Risotto submits a PTO request?

Yes. Submitting time off requires an explicit confirmation from the employee
that is separate from their original message, so a casual mention of time
off never creates a request on its own.

### Should we use the Rippling Home Address Lookup template?

That's a judgment call about PII. The template only ever returns the
requesting employee's own address, and it's read-only. It does mean home
addresses flow through your ticket source and any external ticket sync. If
your policy restricts where address data may appear, don't use it. Each
template is a separate runbook, so you can use the time off templates
without it.

### How fresh is the data Risotto reports?

PTO balances, job details, and addresses are read live from Rippling at the
moment of the request.

### How long after a termination does Risotto stop looking up the employee?

Rippling sends the termination webhook with a delay of roughly five minutes.
For an immediate cutoff, click **Sync now**.

### Can we connect Rippling to more than one Risotto org?

No. A Rippling company maps to exactly one Risotto org, so that webhooks
route unambiguously. To move the connection, disconnect from the first org
before installing in the second.

### What about contractors and international workers?

Scope is set by your Rippling provisioning rules, not by worker type. Anyone
those rules place in the provisioning group is in scope; anyone they exclude
is not. If contractors should be able to self-serve, confirm your Rippling
provisioning rules include them.

### Are half-days and part-time schedules supported?

Yes, with one limit. For a full day, Risotto sends no hours, and Rippling
uses the work schedule of the employee. So part-time schedules work. For a
partial day, Risotto sends the hours with the request, but only for a
request of one day. To take part of several days off, the employee submits
each partial day as its own request.

### Is there an audit trail?

Yes. Risotto records org events for manual sync triggers, employee
provisioning and deactivation, and the app uninstall.

## Troubleshooting

### Install fails: “Please disconnect Rippling from your other Risotto org”

This Rippling company is already connected to a different Risotto org.
Disconnect it there first, then retry.

### Install fails: “The Rippling install session expired”

The install is time-limited, and a slow sign-in during the handoff can let
it lapse. Retry the install from the Risotto app page in Rippling.

### Install fails: “Could not complete the Rippling install”

Rippling rejected the credential exchange. Retry the install. If it keeps
failing, confirm you're signed in as a Rippling admin and contact Risotto
support.

### Sync failed: no PROVISIONING supergroup found in Rippling

Rippling has no provisioning group for Risotto to read, which almost always
means account provisioning hasn't been configured for the Risotto app yet.
Set up provisioning rules in Rippling, then click **Sync now**.

### Sync failed: Rippling connection needs to be reconnected

Risotto's stored credentials can no longer be refreshed and Rippling data is
unavailable until an admin reconnects. Risotto notifies org admins when this
happens. Reinstall from **Settings > Integrations > Rippling**. Syncing is blocked
until you do.

### Sync failed: Rippling API request failed, or timed out

A transient Rippling API problem — a rate limit, a temporary outage, or a
roster large enough to exceed the time limit. The next daily sync retries
automatically; **Sync now** retries immediately.

### An employee is told they aren't found in the HR system

Risotto couldn't match them to a Rippling worker. Check, in order:

1. Their Slack email matches their Rippling `work_email`.
2. Rippling's provisioning rules include them, so they're in the group Risotto reads.
3. They aren't marked terminated in Rippling.
4. A roster sync has run since they were added — click **Sync now**.

### Risotto isn't taking any HR actions at all

Installing the integration does not turn on any HR actions by itself. Check, in order:

1. A Rippling runbook template is published as a runbook, and the runbook is on. See [Set up time off and home address requests](#set-up-time-off-and-home-address-requests).
2. The runbook's Rippling tools are on.
3. To let the agent look up the employee record, **Agent access** is on, on the **People** tab of [Support agent > Context](https://www.tryrisotto.com/docs/dashboard/settings/support-agent/context#people).

### An employee's PTO request was rejected by Rippling

Rippling validates requests against its own rules such as insufficient balance,
blackout dates, policy restrictions, or overlapping requests. Risotto relays
the reason Rippling gives. The employee can submit in Rippling directly if
the rule needs an exception.

### An automation did not run on a Rippling event

Check, in order:

1. The employee has access to Risotto within Rippling.
2. Rippling sent the event you expect. A same-day hire gets only
   `employee.created`, so use that trigger to catch every hire.
   `employee.terminated` waits for the access turn-off time.
3. The employee has a valid `work_email` in Rippling.
4. The Rippling connection does not need to be reauthorized.

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