Import additional attributes from BambooHR (Custom API Connector)

A custom API integration can be used to import and update attributes that are not currently available to sync using the JumpCloud app in BambooHR, e.g., manager, alternate email, and employee type, to create more complete user profiles and use those attributes for access and permission control and automation.

The current BambooHR integration is configured in BambooHR using the JumpCloud app. It is a one-way sync. The employee data is sent from BambooHR to JumpCloud in real-time or on a configured schedule.

This integration is configured in JumpCloud and should be considered as a complement to an existing BambooHR SCIM integration, not a replacement.

Prerequisites

• A JumpCloud administrator account
• JumpCloud SSO Package or higher or SSO à la carte option
• A BambooHR user account with full administrator permissions
• An existing BambooHR integration:
  • If you are using both SSO and SCIM, you can use the existing BambooHR connector
  • If you are only using SCIM, you must create a new JumpCloud application connector

Considerations

• The /report endpoint generates a custom report and can manage the user lifecycle.
• Configuring JumpCloud SSO for BambooHR is recommended, but not required.

Configuring the BambooHR API Authentication

To generate the BambooHR API token

1. Sign in to your BambooHR instance with administrator permissions.
2. Click your user icon in the left bar navigation menu
3. Click API Keys
4. Click + Add New Key
5. Enter a name for the API key in the API Key Name field and click Generate Key.
6. Click COPY KEY to copy the key to your clipboard.
7. Click Done.

To encode the BambooHR credentials

1. Access the API Key.
2. You will need to encode a string that consists of <BambooHR API key>:<random string with 1 or more characters>
   • Example: 1208934bba29wa123492879873:x
3. Use a tool or commands to base64 encode the credentials:
   • Command in a mac terminal:
     base64 <<< 1208934bba29wa123492879873:x
4. Securely store the encoded credentials, like in the JumpCloud Password Manager.

Configuring the Integration

To create a custom report in BambooHR

Create a custom report in BambooHR with the attributes you want for the integration, including status and supervisor email. You will need the report id found in the URL shown when viewing the report in BambooHR. 

1. Log in to BambooHR.
2. Click the Reports tab from the top navigation bar.
3. Click New Custom Reports.

4. Click the +New Report and then the pencil icon to enter a name.
5. Add the attributes you want to sync to JumpCloud:
   • Be sure to include status
   • If you want to import manager, be sure to include supervisor email
6. Under Filters, for status select all to include both active and inactive records.
7. Click Save.
8. Note the id from the URL once the report loads.

To configure the Custom API integration in JumpCloud

To learn more about the JumpCloud Custom API integration connector, see Import Users with a Custom API Integration.

1. From the Identity Management tab of your BambooHR application connector (either prebuilt or custom), select or enter the following under Service Provider Configuration:
   • API Type - Custom API Import
   • Authentication method - API key
   • Base URL - https://<your BambooHR company subdomain>.bamboohr.com/api/v1/custom-reports
   • Header name - Authorization
   • Header value - Basic <base64 encoded credentials>
     • Example: Basic Ym2aWILcluwej4xou28==

2. Select or enter the following in the Endpoint Configuration section:
   • Resource Location - employees
   • Endpoint path - /<report id from URL in BambooHR>
   • Pagination - Page-Based
   • Page parameter - page
   • Page size parameter - page_size
   • Total Count
     • Response Parameter Location - Body
     • Response Body JSON Path - pagination.total_pages

3. Click Test Connection to verify the credentials and configuration.
4. If successful, enter the following in the User Schema Attribute Mapping section:
   • Unique ID - id
   • User Status - status

• Inactive Status Values - Inactive

5. Complete all required and desired optional mappings.

6. Click Preview Mappings.

7. If the attributes are mapping correctly, click Activate.
8. If successful, you will receive a message saying the Identity Management has been successfully verified.
9. Perform your initial manual import.
10. If the initial import is correct, enable a scheduled sync.

Using Expressions

Some expressions that may be useful are:

Preferred Name

Syncs preferred name if it is populated in BambooHR. If it isn’t populated, it syncs the user’s legal first name. 

{{or .preferredName .firstName}}

Display Name

Creates a display name that uses the user’s preferred name, if it is populated, as the first name and the last name. If preferred name is not populated, the display name will be the user’s legal first and last name.

{{or .preferredName .firstName}} {{.lastName}}

See Use Expressions with Identity Management for more information.