How to integrate with HiBob

Step by Step Instructions

Step 1 - Create a Service User

Log in to Hibob, and navigate to Integrations within System Settings (this is accessed through the tile in the top left of the screen). Then go to ‘Manage’ on the Service Users tile.

Step 2 - Generate Service User ID and Token

Create a new Service User, and then save the Service User ID and Token.

🚨 Make sure you copy the User ID and Token, as once you click done, there will be no way to see the details again.

Step 3 - Create a Permission Group & Add Service User

Staying in ‘System Settings’, navigate to Permission groups from the “Account” menu.

Select “+ Create Permission Group” in the top left. A dropdown will appear indicating the type of permission group you want to create. Make sure you select ‘Service user’ here.

Name the permission group (e.g. Ravio), and then in the “Members” section at the bottom of the pop up box, choose the service user we just created.

🚨 A common area to go wrong is creating an ‘Employee’ or ‘Admin’ permission group instead of a ‘Service User’ group. This will cause the integration to fail to make sure this is created correctly!

Step 4 - Assign access to the correct employees

Select the “People’s Data” tab from the Permissions Group editor, and then “Edit” the permissions.

Under Access rights, choose “Select people by condition”, then make the condition ‘Lifecycle status exists’ if this is not already the default.

❓ Why does Ravio need access to terminated employees? Whilst this might seem counterproductive, Ravio needs access to terminated employees to know when someone has left your organisation! If Ravio does not have access to non-active employees we don’t get a notification when their status changes to ‘terminated’ (or another inactive status) which leads to lots of ex-employees appearing in your company view in Ravio!

Step 5 - Assign the correct permissions

Within the People section, choose the permissions from the table below.

Basic Info and/or Personal categories requires ‘Edit’ Access for Ravio as for some instances due to the restrictions on the HiBob API. To have read access on specific data fields (e.g. date of birth) HiBob requires you to have ‘Edit’ access.

*(optional based on data availability in Hibob. This equity data can also be uploaded into Ravio separately).

*(*optional for diversity analysis.)

*(**not required if integrating anonymously)

Optional fields can be disabled via the onboarding flow in Ravio, see steps at bottom of page

Step 6 - Enter the connection details in Ravio

Navigate back to Ravio, and use the Hibob Token and User ID and Token that you saved earlier to finish the setup on the Ravio platform. Click Submit.

Troubleshooting

If your data is not pulling through correctly, check the following:

The ‘Home’ permission is missing

A very common issue is the below error message.

The ‘Home’ category is used to share the ‘Gender’ and ‘Date of Birth’ fields with Ravio. If your company uses custom fields for these categories, or you are not sharing these data fields with Ravio you need to make sure these fields are unselected on the previous screen (you will need to open the ‘Read Employees’ dropdown.

Otherwise these permissions are ‘required’ for these fields and the integration will be rejected until these permissions are added.

‘General Errors’

If you are seeing the message ‘General Errors’ with a long list of fields indicated there is no access, this is likely an error with the Service User / Permission Group. Some common areas to check here are:

1. Making sure that the Service User you just created is assigned to the Permission Group and not any other user.
2. Making sure that the Client ID / Client Secret is correct on the page prior to this (e.g. if the Client Secret has been reset).

How do I find missing or custom fields in HiBob?

Finding missing fields or custom fields in Hibob is a bit more involved than for most tools. This guide will give a step-by-step process to identify and expose these fields in Hibob. The process is the same for custom fields and default fields that are being flagged as ‘missing’ in the integration workflow.

Step 1: Identify the field

To get started, first find the field you want to expose on an employee. Fields can be exposed in one of two ways:

1. In an existing category.

For example, here this employee has an additional property called ‘JA Test Field’ in the Payroll category.

1. In a completely custom category.

This employee has a custom Benefits category that includes the field ‘benefits eligible’.

Step 2: Add the category to the permission group.

After identifying the field, it needs to be exposed on the permission group that is being used to connect the Hibob account to Ravio (steps 3 to 5 above).

1. In the Permission Group go to People's data at the top and open the People tab.
2. We need to make sure the category that the missing field is in is enabled.

   1. In the first example above, where the custom field was on the Payroll category we need to make sure the View and View Histories pemissions are enabled.

      

   2. In the second example the field is in the Benefits (Custom) catgegory, we have to make sure the same permissions are enabled.

      

Please note: For fields that are sensitive (that are not shown as clear text in the UI) you have to enable the edit permissions for that category. Edit permissions in Hibob are just elevated permissions and not exclusively reserved for editing access, but also sensitive fields.