BambooHR Setup Guide
Small Improvements and BambooHR HRIS can be integrated within a matter of minutes. The primary benefit of this connection is that you are able to import your high-level employee information, plus reporting structure, directly into your Small Improvements account.
It hugely streamlines your administrative process when you don't have to worry about making manager updates or adding new hires to your performance management process. You can also view past review and objectives information on a user profile within Bamboo, though only as a reference.
Please note: if you elect to have your users synchronized with Bamboo, many user fields are "controlled" by this sync and cannot be updated within your SI account any longer. We have a list of these fields here.
Article Quick Links
- What is BambooHR?
- How the integration works
- Setting up the integration
- Previewing the import
- Import History
- Informing staff about their accounts
- Automating the import
- Viewing Small Improvements data inside BambooHR
- Synchronizing only a subset of users
- Other Considerations
- Suspending the automatic import
- Rolling out to existing SI account
- Re-using BambooHR profile pictures
- Importing SI staff data into BambooHR
- Common Issues
What is BambooHR?
While Small Improvements lets you manage basics like name, department, and reporting structure, it's not a fully fledged employee database. BambooHR is, and by using our integration, you can use both systems together to maximize your efficiency. Some of the core features of BambooHR include employee record keeping, PTO/leave tracking, benefit tracking, reporting, and much more.
This is just a very brief overview of BambooHR. You can check out the BambooHR website for in-depth coverage of features and capabilities.
How the Integration Works
There are two sides to the integration:
- The most useful one is that you can synchronize BambooHR staff data into Small Improvements automatically.
- The other aspect is that you can also "stream" SI data into the BambooHR user interface, making performance review and objectives data easily accessible to BambooHR users.
- Both aspects are entirely independent, so you can have one without the other if you like.
Setting Up the Integration
Setting up the integration is fairly straightforward. We're assuming you already have both a BambooHR and a Small Improvements account, and are an administrator in both systems.
First, you need to give Small Improvements access to your BambooHR system. Basically you tell Small Improvements to log in on behalf of an administrator in BambooHR.
- It's vital that this administrator has full access to all the users you want to synchronize, including core fields like first name, last name, work email, active-status, gender, supervisor, and hiringDate. If available we also load the fields job title, nickname, location and id.
You connect the systems by creating an API key in BambooHR from the user you want to use, and storing that key in Small Improvements. You can generate BambooHR API keys only if you're a BambooHR administrator.
You'll find the keys and the create-button in your "User" menu in BambooHR:
Now, back in Small Improvements, go to: The Administration tab > Scroll down to "Integrations" and click the BambooHR icon > Tab over to "Configuration.
- First, enter your BambooHR ID (the subdomain) and a valid API key.
- If you want to have automatic imports every time there is a change in Bamboo, you must remember to select "Automatic Imports". This will run periodic "checks" of your Bamboo database, and sync any updates.
- You can wrap up the configuration the import here, or feel free to revisit the details later. Save the settings and you'll get taken to a preview screen that displays what the import may look like.
Previewing the Import
The preview tab will automatically display what changes will happen if you were to run the import:
- A list of users will be displayed, hinting at what has changed. The bar chart at the top shows the distribution of what kind of changes will happen, and you can click the segments to filter the list below.
- You can also preview the exact changes which will be made to a user by clicking the menu icon (bullets & lines) to the far right of a user's name in the list. This will expand the details specific to that user's data and you can scan the changes.
Once you're confident these are the intended changes, you can either manually kick off the import, or enable the automatic import in the configuration screen. If you choose manual import, a pop-up will ask you for confirmation before the import starts running in the background.
Every successful import will show up in the history tab. You can get a quick overview, but you can also drill into what exactly was changed by clicking the menu icon to the right of a user's name, much like you would when viewing a preview.
Setting up the display of SI reviews and objectives inside BambooHR
To successfully setup the display of information from employees in Small Improvements, into their profiles on BambooHR, you'll need to connect the two systems. This requires reaching out to BambooHR tech support or using the guide below to add the app.
Installing the Small Improvements APP on BambooHR
Select the Cloud icon in the top-right hand corner of your BambooHR dashboard:
This will display an app homepage:
Scroll down to locate the Small Improvements app under Performance Management:
Follow the on-screen guide and click install on the right-hand side menu:
Once installed, two new tabs will show on every user's profile page inside BambooHR, one for performance reviews and one for objectives. Below is an example.
Is this data stored in BambooHR?
Keep in mind again that the SI data is not copied to BambooHR; it stays entirely inside Small Improvements. The BambooHR tabs act more like "windows" into SI. For that reason you (or your staff) will need to log in into SI once. As an administrator you are probably already logged in, but regular BambooHR employees will initially see a login button when they access the "performance review" tab in BambooHR for the first time.
In case the tabs don't appear, please contact BambooHR support.
Synchronizing Only a Subset of Your BambooHR Users
If you only want 30 out of your 600 employees to trial Small Improvements, or if you only want to synchronize full-time workers (and not contractors) into SI, you can sync a subset of users.
In cases like these, you'll use custom access levels. Users with a custom access level can be set to view only certain users. For example based on deployment status ("no contractors") or location ("only New York staff") etc. So you can create a custom access level, assign a user that custom access level, and use that user's API key inside Small Improvements.
Step One: Create the new Access Level
Create a brand new customer access level called "SI Importer" that has limited access to specific fields
You'll need to make sure that this custom access level has access to specific fields including Status, Gender, and Location, but you can enable view access for other fields as well. If you forget this setting, then we cannot load all the fields and the synchronization will misbehave.
Below is a gif showing how to add a certain field to sync the subset:
Step Two: Add the new fake user or add an existing user to the custom access level
Add a new user in Bamboo called "SI Import User" (or something which helps you remember the purpose of this user), and then grant this user the SI Importer Access level.
Creating a new user:
You can add the user to the access level from the access level screen:
Step Three: Create an API Key for the user
Create an API Key for "SI Import User" and use that API key in Small Improvements. You'll need to login as the fake user if you've setup a fake user for this purpose. You'll do this by selecting the avatar and "API Keys" in the top right hand corner.
You'll generate the new API key using the Add a New Key button:
You'll need to click 'show' next to the new key and copy it:
Step Four: Copy and past the API key into the integration screen in Small Improvements
Visit the configuration tab in the BambooHR setup screen in Small Improvements and add the API key you generated to the required field - below is a screenshot showing where to locate this option.
We'll start syncing new staff within 2 hours with automatic syncing enabled, or you can sync right away from the Preview screen. You can preview to see the data that's being pulled in for your subset of users.
Informing staff about their accounts
If you run the import manually, we do not automatically inform staff about their accounts. After all, we don't know who should get access, and when. Click here to learn how to inform staff about how to log in.
You can auto-inform users as soon as they are automatically imported though. For more information, see the very next section.
Automating the Import
Assuming everything has worked fine, you should enable the automatic synchronization now. We will scan the BambooHR database every three hours, automatically setting up new users or applying other changes.
As mentioned above, do you also want to automatically inform new employees about Small Improvements? In some cases it makes sense, like if your team is using Small Improvements on a regular basis. But perhaps would have less impact if your team uses the tool for formal review processes that are less frequent.
Whichever works for best for you, you can adjust the setting on the configuration tab (where you entered your API key) with the checkbox "Send password emails when new users are imported"
Suspending Automatic Updates
Sometimes companies want to conduct performance reviews for a month and not see any updates inside BambooHR get applied to the SI user base. In that case, you can always disable the automatic BambooHR synchronization temporarily so new changes will not be applied.
In case some changes already were applied prematurely, you can revert manually - but only if the auto syncs have definitely been turned off.
If you run into an issue, please contact firstname.lastname@example.org
Rolling the integration out to an existing SI system
It is possible to integrate BambooHR after you've been using the account with manual user imports.
- Don't worry, we're not deleting users. We're simply comparing the data, and if we find user matches (based on the work email address), we update the new fields only. You can preview these changes easily to safeguard against any inadvertent updates. Set up the connection, click preview and don't check the "automatic sync" yet; the preview screen will tell you about all the changes the import would do (see more information about this above).
- A typical problem is that you might have mismatches in the email addresses, so you might end up with duplicate users (e.g. if you set up John Smith as "email@example.com" in SI, but as "firstname.lastname@example.org" inside BambooHR). In such a case, you should definitely edit one of the accounts, either in Small Improvements or in BambooHR, before you synchronize, or you'd have two John Smiths in SI.
- We use employee IDs to sync between Small Improvements and BambooHR. The IDs used by employees in BambooHR must match the employee IDs in Small Improvements. Recycling old user IDs can cause syncing problems with the integration.
Once fixed, you can preview the sync again, and again, until you feel the synchronization is importing users exactly right. Only then you run it and activate the automatic sync if you'd like to use that.
Re-using BambooHR employee profile pictures
You can decide to show the BambooHR employee pictures inside Small Improvements, thus avoiding having to upload all employee pictures into your Small Improvements account as well. Please note that we only display BambooHR pictures, we don't store the BambooHR pictures inside SI. If you disable the pictures options, then the SI default pictures will re-appear (which is great, because it means it's safe to try this, and you can revert back easily.)
Here are a couple of details you might want to learn about. No big surprises, just generally a good idea to be aware of:
- Small Improvements can detect and import new staff, but your new employees still need to define their own password. You can configure the synchronization to automatically send the password-creation instructions to new employees, or you can send the mail manually.
- If you disable an account in BambooHR, it gets disabled in Small Improvements as well. However, if you delete it in BambooHR, and you'd like for those delete users to be removed from Small Improvements as well, you should select the configuration option (in Small Improvements): "Deactivate all Small Improvements accounts not imported".
Fields no longer editable in Small Improvements
Once you enable connectivity, the following fields are managed by BambooHR. This effectively "takes over" these fields, meaning you can't edit them in Small Improvements any longer.
- First name
- Last name
- Work email
- Job title ("Role")
- Supervisor ("Reporting to")
Importing Small Improvements staff data into BambooHR
In case you have all your employee data in Small Improvements and want to start using BambooHR, you will have to export your Small Improvements userbase once, have it imported into BambooHR once, and then activate the import from BambooHR (making BambooHR your leading system). You can export Small Improvements staff data on the company directory page. There is an easy "Export to CSV file" option located within the "Admin" menu, in the upper right corner of the page.
We frequently get support requests along the lines of "some of my users don't update in SI although I updated them in BambooHR". Quite often the solution is very simple. So before contacting support, please make sure to check this list:
- Employee IDs: We use employee IDs to sync between Small Improvements and BambooHR. The IDs used by employees in BambooHR must match the employee IDs in Small Improvements. Recycling old user IDs can cause syncing problems with the integration.
- Synchronization didn't run: You can either kick off the syncs manually, such as every couple of weeks. Or you can set them up to run automatically all the time (in the BambooHR settings dialog). But if you do neither, then no updates to BambooHR users will flow into Small Improvements.
- Synchronization wants to lock all users: This is usually the result of using the API key of a user who does not have access to key fields like Status, Gender, or Location. The SI importer interprets the absence of the Status field from BambooHR as if the status was locked. Make sure the user you use does have access to everything.
- Too few users get imported: If too few users get imported or synchronized, this is usually due to an API key belonging to a BambooHR admin who does not have full permissions inside BambooHR. As outlined above, the BambooHR admin needs to have access to all users, and also to all their core fields like "status", "gender", "startDate" etc.
- Still too few users get imported: If you have people in BambooHR who are not showing up in Small Improvements, this can also be caused by lack of work email addresses in BambooHR. The integration requires the work email field to be filled on BambooHR, and all users who don't have an email (or just a personal email) will get ignored.
- Work Email: As referenced a few times, we pull from the work email field in BambooHR. There is a "home" email field in BambooHR available, so if the email is listed there, our syncs can't read it.
- Mismatching email addresses: The sync relies on the email address field. If a person has one email address in SI and another one in BambooHR, then things break down! We cannot know that "email@example.com" and "firstname.lastname@example.org" are the same person. Solution: Rename the email address inside SI to match the one in BambooHR, or vice versa.
- Outdated API key: The BambooHR API key always belongs to a user. This user needs to have access to all users inside BambooHR. We frequently encounter cases where the API key was fine at setup time, but then the employee left the company and her account got locked down. Her API key was still being used though, which of course didn't work. The solution is to create a new API key in BambooHR, paste it into SI, and re-run the synchronization. When you push the "Test Connection" button we will display how many BambooHR users the current API key has access to. If this is a lower number than your staff in BambooHR, then there's a problem with that key.
- Loops in the reporting structure: Small Improvements does not support loops in the reporting structure. You can report to one person, and the CEO can report to nobody. This is different in BambooHR, where you can have two CEOs who report to each other.
- Someone disabled the automatic synchronization While you may have enabled the automatic syncs six months ago, some other administrator might have disabled it last week. This would explain why your recent changes to BambooHR user data don't get reflected inside Small Improvements.
- Patience: The automatic synchronization runs every three hours on average. Occasionally, this job can time out and we'll retry it after another three hours. If you need the update instantly, run the manual import.
- The SI tabs in BambooHR always shows "Please log in...": Third-party cookies for "*.small-improvements.com" must be enabled to view SI content in BambooHR. It's typically an advanced privacy setting in in the browser. (E.g. in Chrome it's under Settings-> Advanced -> "Content settings..."). Please check with your admin if you're not sure.
The best way to figure out a problem is to preview the synchronization manually, and analyze what users are being displayed as changed, ignored or (very important) don't show up in the list at all. Look at what exactly has changed by expanding the details field. Also, try refreshing the API key. If a problem persists, please contact Small Improvements support at email@example.com (don't ask the BambooHR support team - they will pass you on to us anyway).
Although this document looks long, it's actually a matter of less than 10 minutes to hook up Small Improvements with BambooHR HRIS, and not having to worry about data synchronization. We do advise that you check back every now and then, just to see what data gets ignored. After all, it is still possible to set up users in Small Improvements manually (for good reason!), so you may have more user accounts in SI than in BambooHR some day, and may want to create them in BambooHR as well. The synchronization screen lets you find out about these differences easily.