Contents
What does it do?
The BambooHR integration allows Betterworks to connect with an instance of BambooHR and use the employee data recorded there to automatically create and maintain user accounts in Betterworks.
This is a great way to enable hands-off user management for Betterworks, ensuring that employees that have left the company are deactivated and that new hires are provisioned in Betterworks as soon as they're added to BambooHR. Additionally, there's no need to track and update if users change names, email addresses, or the managers to whom they report - the integration will keep both systems in sync.
Simply create an API Key in BambooHR and enter it into the BambooHR section of the Admin > Platform Configuration > Third-Party Integrations page in Betterworks and either choose "Sync now" or wait for the scheduled process to run overnight.
How does it work?
This integration leverages the BambooHR Open API to pull these fields from the BambooHR employee record to be used as attributes on the Betterworks user account per this mapping:
|
BambooHR Employee Record |
Betterworks User Account |
| Employee # | Employee ID |
| Work Email | |
| Name (first) | First Name |
| Name (last) | Last Name |
| Job Title | Title |
| Department | Department Name |
| Reports To (supervisorID) | Manager (manager_id) |
| Work Phone | Phone Number |
| City | Location |
| Status | Active/Inactive |
| Termination Date | Deactivation Date |
| Preferred Name | Preferred Name |
The synchronization will run every day at 3am PST to ensure that records are kept up to date. Please remember that any manual changes made to users in Betterworks (via the Admin panel) will be overwritten by the data pulled from BambooHR.
If Betterworks fails to connect to the BambooHR instance three times consecutively, then the integration will enter an error state which will be displayed on the Third-Party Integrations page.
Note: If an employee record includes a department not already created in Betterworks, then the integration will create a new department of that name - BetterWorks recommends confirming that any departments which may have already created in Betterworks match exactly with those that exist in BambooHR to avoid any duplication.
How do I set it up?
1. In BambooHR, click on the profile drop-down menu and select the "API Keys" option:
2. This will lead to the API Keys page in BambooHR where a key can be added or an existing key can be selected:
3. Click on the key to display the entire string and copy this to the computer's clipboard - this will allow Betterworks to access the employee data and should be pasted into the API Key field in Betterworks.
4. The URL of the current page should look like https://companyname.bamboohr.com/
Note: The "companyname" portion is the subdomain used to direct Betterworks to the correct instance of the BambooHR API.
5. To input these values, navigate to Admin → Platform Configuration → Third-Party Integrations in Betterworks and click the "Set Up" button next on the BambooHR integration option:
6. Input the Subdomain identified in Step 4 and the API Key identified in Step 3 and click "Save":
7. The BambooHR integration should now display as Connected and clicking the "Settings" button should reveal the saved credentials as well as options for "Edit", and "Sync Now":
8. Click "Edit" and update the Activation Blocklist for those employees that should not have access to Betterworks. This is based on the "Employment Status" field, and the available values are listed below. Employee accounts will be provisioned/activated or deactivated accordingly if they fall in or out of these statuses in BambooHR.
- Contractor
- Full Time
- Intern
- LOA
- Paid LOA
- Part-Time
- Pending New Hires
- Return From LOA
- Temp Agency Contractor
- Vendor Service Provider
9. Select "Sync Now" to query the BambooHR API and pull back employee data to automatically create accounts for all the employees according to the parameters set. If you do not click Sync Now, it will sync during the regular schedule, which is 3am PST each day.
Note: In order to receive error notifications for this integration, an individual or group email distribution needs to be provided to support@betterworks.com - if "Sync Now" is selected without providing this contact information then failures for individual record creations/updates might be missed.
FAQs
Some users who should be active are being deactivated. How do if fix this?
Users will be not be activated in Betterworks if they have a blocklisted status or if they have no status in BambooHR. That is, if you are blocklisting certain employment statuses in the Betterworks UI, we deactivate any user with a blocklist status or if that user has no status at all.
How is a blocklisted status set?
A blocklisted status is something you set in the Betterworks UI.
Check Betterworks. Have a Betterworks admin user at your company go to Admin > Third-party integrations. Locate the BambooHR integration, click Settings > click Edit > and edit the Activation Blocklist if needed. Please see "Step 8" above to see a full list of the blocklist statuses.
Check BambooHR. Make sure the status is not blank. Just a note, there is a known issue where a person who sets up the integration has enough permissions to create a token and see everyone else's status, but they can't see their own status. The other thing you'll want to check is that there are not future-dated effective dates. If there are, BambooHR won't report the status because the date hasn't happened yet.
Can the profile photo be synced between BambooHR and Betterworks?
No, not at this time.