How-To: Setup the BambooHR Integration

NEW: Changes to the BambooHR Integration Setup

In August of 2019, the setup process for the BambooHR-TimeWorksPlus integration changed. This article refers to the new process and should be used by those setting up the integration for the first time. If you already had the integration prior to the update, see the attached legacy instructions here.

For TimeWorksPlus Accounts with Existing Employee Data

Once integrated, BambooHR will be the system of record and overwrite any synced employee fields in TimeWorksPlus. This can cause problems if there are any rules or scripts in your timekeeping account that rely on Employee Setup fields. Make sure your employee data matches between the two systems before implementation.

Employee numbers in BambooHR should match Employee Codes in TimeWorksPlus. If there is a discrepancy between these two values, changing the employee numbers in BambooHR might be preferable since Employee Codes in TimeWorksPlus also need to match an employee ID in payroll.

Registration of the Integration

Registration of the integration can be done by any TimeWorksPlus user with access to Integration Management. This includes users with a client-level login or higher.

To register the integration, you will need your:
  • Full BambooHR Company Domain. This is contained in your BambooHR web address.
  • BambooHR Administrator Credentials The integration requires an administrative login; a different level of user account will not work. Also, since this login will be used to integrate the systems, we suggest creating a dedicated BambooHR login solely for the integration. Otherwise, if the user associated with the integration has their login deleted or changes their password, the integration will break.

    Note for SwipeClock Channel Partners: You will likely not have administrator access to your client's BambooHR site. If that is the case, your client can perform most of the setup themselves. However, they may need your assistance with certain Processing Rules, like Punch Categories, to which they don't have access.
     
  • All employees in BambooHR should have an Employee Number. This is required as employees without a number won't be synced.

To register the integration:

  1. Login to TimeWorksPlus. If you are a SwipeClock Partner, choose your client from the Client List.
  2. Click Settings Menu ⇒Integration Management.
  1. Select "BambooHR" from the listed integrations. It may be the only integration you see.
  2. Click Settings under the Client Lookup section.
  1. In the resulting window, provide the required values to connect to your BambooHR account:
    1. Your full BambooHR domain name. This is entered in the ”Subdomain" field and should be entirely lowercase. You cannot register the integration without the domain.
      Example: companydomain.bamboohr.com
    2. The BambooHR administrator username and password you have chosen for the integration.
      TIP: Use a dedicated set of credentials, not an actual user's login and password. That way, the integration won't break if the password is changed or the user's account is deactivated.
  1. Click Save.
After saving, the connection between TimeWorksPlus and BambooHR will be validated. If successful, you'll see a "Settings saved" pop-up and the company name will appear in the Client Lookup section. You can proceed with configuring the employee sync.

If the connection is unsuccessful, make sure you have correctly entered your domain and password.

Employee Sync

The BambooHR-TimeWorksPlus integration allows you to define which employees are synced between the two systems. BambooHR is the system of record for employee data and will overwrite any synced fields in TimeWorksPlus. Employees are matched between the two systems using the Employee # in BambooHR and Employee Code in TimeWorksPlus. Employees must have a BambooHR Employee Number to be synced.
  1. Select Integrations Management from the Settings Menu. If you just completed registering the integration, you will already be on this page.
  2. Select Settings under the Employee section
  1. Set the Employee Filter according to which employees you want imported from BambooHR. Please note that the filters look for "Overtime" in the BambooHR Compensation settings to determine to determine non-exempt status.
  • All Employees will import all active and inactive employees.
  • All Active Employees Only imports employees active within the last 45 days.
  • All Employees where Overtime has a value* imports Exempt and Non-exempt employees. 
  • Active Employees where Overtime has a value* imports Exempt and Non-exempt employees active within the last 45 days.
  • Non-exempt Hourly Employees* imports Non-exempt employees only.
  • Non-exempt Active Hourly Employees* imports Non-exempt employees active within the last 45 days.
  1. By default, the employee integration syncs a set of predetermined fields. You can add/remove additional mapping using the "Add Field Mapping" button.
  1. Click Save to return to the main integration setup page.
  2. Perform a full sync of all employees by clicking the Sync button under the Employee section.
  1. After initiating the sync, the Last Sync Run label updates with the date and time of the last run. You can click View Logs to see the results of the sync. If there are any errors (usually due to a missing Employee # in BambooHR), they will be detailed in the logs. The employee sync can take up to 5 minutes to complete.
  1. Turn on the Recurring Sync with the slider at the left of the Employee section. It will update with changes and adds from BambooHR every few hours.
 
*Previously, BambooHR used the FLSA Code for determining Non-exempt status, but that field has been deprecated by BambooHR. However, if you previously used BambooHR's FLSA Code for tracking Exempt/Non-exempt status, you should transfer that data to the new Overtime field so the filters work correctly. You may need to contact BambooHR to enable the Overtime field. 

Synced Employee Fields

The table below lists which fields will be synced. Please note, all employees in BambooHR must have a unique Employee #. 
 
BambooHR TimeWorksPlus Notes
Employee # Employee Code IMPORTANT: If the Employee Code differs from the Employee # in BambooHR, the integration will create duplicate employees.
First Name First Name  
Middle Name Middle Name  
Last Name Last Name  
Email Email  
Hire Date Start Date  
Termination Date End Date  
Overtime Employee Type  
Dynamic Fields - Can be mapped using field mapping 1
Supervisor Name    
Job Title    
Department    
Location    
Pay Rate   The Pay Rate Processing rule must be enabled in TimeWorksPlus. You may need to contact your timekeeping provider for this to be enabled. If you have just activated the rule, wait 10 minutes before running the integration.
Pay Group    
Pay Group ID    
 

1- Each of these fields in TimeWorksPlus has an Effective Date that will be populated with the Job Info/Date field in BambooHR.

Additional Employee Sync Notes

Employees will need Card/Clock Numbers. BambooHR does not have a field for assigning the numbers an employee uses for clocking in and out. Because of that, you will need to add clock numbers in Employee Setup after running the integration. 

This can be done manually or through a bulk employee update which can be performed by SwipeClock partners.

Employees should be terminated in BambooHR, not TimeWorksPlus. Terminated employees will be synced to TimeWorksPlus. If an employee is terminated, the Separation Date will be updated in Employee Setup and on that date, they will be set to inactive in TimeWorksPlus.

IMPORTANT: If the employee filter is set to an "Active Only" filter, then termination dates will not be synced. In this case, you will need to manually terminate the employee in TimeWorksPlus.
If an employee is rehired in Bamboo, their rehire date will populate the Start Date in TWP and their Separation Date will be cleared out.

BambooHR doesn't have an effective date for the Overtime field. The integration maps the Overtime field from BambooHR to the Employee Type field in TimeWorksPlus. After you run the integration, you might notice the Overtime code from Bamboo does not appear in Employee Type. This is likely due to an issue with effective dates on pre-existing data in the Employee Type field.
Suppose, prior to running the integration, an employee had a value of Null in their Employee Type field. And the effective date of that field was "April 24, 2015" (their date of hire). Currently, the integration imports the Overtime code with an effective date of "1/1/1970", which obviously pre-dates the existing value in the field. This will result in the Overtime code being hidden from Employee Setup because the pre-existing value is more recent than 1/1/1970. At this time, the only work around is to manually delete the existing Employee Type value. However, if you are not using the Employee Type/Overtime field in TimeWorksPlus, you can likely leave this "as is".

Employee Single Sign-on

Employees can access their timekeeping Employee Portal through a single sign-on link in BambooHR. By setting up the single sign-on, there is no need for a login and password in the employee's TimeWorksPlus record. However, if they are using a physical clock, they will need a clock number/login in Employee Setup.
 
To add the SSO link to the Bamboo portal:
  1. From TimeWorksPlus, click Settings Menu Integration Management to access the BambooHR configuration page. If you just finished any other steps in the setup, you should already be on this page.
  2. At the bottom of the page, look for your unique Custom SSO Link and copy that URL.
  1. Log in to BambooHR as an administrator.
  2. Hover your cursor over the Company Links (located in the sidebar) and select Manage.

 
  1. Click Add Category.
  1. Name the category "SwipeClock"
  2. Click Save.
  3. Click Add Link. 
  1. Name the link "Employee Self Service Portal".
  2. Paste the URL from step 2 into the space provided.
  3. Click Save
The link to single sign-on into the TimeWorksPlus Employee Portal will now appear to the employee in Bamboo.

Time Off Sync

TimeWorksPlus imports Approved, Cancelled and Superceded time off requests from BambooHR through the integration. The hours will be added to the time card. It will only sync time off that is approved in BambooHR—unapproved requests are not synced to timekeeping.
This is a one-way sync with BambooHR being the system of record. There is no sync of native time off requests from TimeWorksPlus to BambooHR. If you have already been using TimeWorksPlus for time off requests, please see the section titled Disabling TimeWorksPlus Time Off.

Punch Category Setup in TimeWorksPlus

In order to sync time off requests from BambooHR, each time off category must have a corresponding punch category in TimeWorksPlus. These categories must match exactly and should be checked prior to integrating the systems. Also, the categories need to be set to "Time Off Requestable" in TimeWorksPlus.

If you make any changes to the punch categories, it can take up to 10 minutes for the change to be recognized by the integration.

Clients do not have access to the Punch Categories rule in TimeWorksPlus. Contact your provider for assistance with Punch Categories.

Time Off Integration Setup

  1. From within TimeWorksPlus, select Settings Menu Integration Management. If you have just finished running the Employee Sync, you will already be on this page.
  2. Turn on the Recurring Sync under the Time Off Requests section.
  1. Click Sync for an initial import of approved time off from BambooHR.
Once the integration runs, it reports any errors through a log file that can be viewed by clicking View Logs. See the following section for solutions to some common time off related errors.
 

Time Off Errors and Solutions

The following are some common errors related to time off and their suggested solutions.
Unable to add ToR: Invalid Category, valid categories are…
CAUSE: There is a mismatched or missing category in TimeWorksPlus.

SOLUTION: In the error file, there is a column labeled Category which identifies the time off category in BambooHR that is having problems.
SwipeClock partners can go to the Punch Categories rule in TimeWorksPlus and either add the missing category or make sure that it is spelled exactly the same as it appears in BambooHR. Once the changes are saved, wait 10 minutes and re-run the integration.
Unable to add ToR: Could not find employee with id [number]
CAUSE: The integration found a time off record in BambooHR for the specified employee number however, it could not find a corresponding Employee Code in TimeWorksPlus. Either the employee doesn't exist in TimeWorksPlus or, the employee exists, but Employee Code doesn't match the Employee Number in BambooHR.

SOLUTION: Find the employee in BambooHR. Then, check if that employee exists in TimeWorksPlus, as either an active or inactive employee. If you don't find the employee, it's likely because you are using a filter on the employee sync that is only bringing of certain employees. For example, if only non-exempt employees are synced, and the time off request is for a salaried employee, then the time off sync returns this error. At this time, there is no fix for this error, but it should not affect requests for synced employees.
An Error Has Occurred
CAUSE: The employee is terminated in TWP.

SOLUTION: In TimeWorksPlus, go to Employee Setup and choose All Employees (including inactive) on the Employee Selector (make sure you also click Apply) and look for employees, highlighted in yellow, that have an Employee Code matching the value in the error log. That will confirm that the request is for a terminated employee. You should cancel the request in BambooHR so that you no longer get the error.

Additional Time Off Sync Notes

The integration will run every few minutes and up to 21 days in the past. It will also sync up to a year into the future. This means that time off approved after the actual date of the request will still sync to TimeWorksPlus provided it's in that 21 day window and falls within an unfinalized pay period.
TimeWorksPlus only recognizes time off in hours. BambooHR does have an option to make requests in both hours and days. Make sure the default day in BambooHR is set to 8 hours. This is found in the Time Off page. Click the gear icon on the top right to check the default day setting. Contact SwipeClock if you want to adjust how many hours are associated with a day.


Time off requests can be viewed on the Time Off Request page in TimeWorksPlus. In addition to adding the approved time off to the time card, the requests will also appear in TimeWorksPlus's native time off management page. However, only requests approved in BambooHR will appear on this page and you can not use this page to alter or unapprove time off requests in BambooHR.

Cancelled and Superceded requests in BambooHR will be removed from TimeWorksPlus. This will happen once the integration runs.

Disabling TimeWorksPlus Time Off

If you have been using SwipeClock to manage time off requests and/or accruals, and are now transitioning to BambooHR, you should turn off the time off functionality in TimeWorksPlus. It is also suggested that you export the Time Off Request Report from TimeWorksPlus so you have a record of existing requests that have already been approved and added to the time cards. BambooHR will not import existing time off requests or accrual balances from TimeWorksPlus.

To disable time off in TimeWorksPlus, you will need an accountant-level login. Client's should contact their SwipeClock provider for assistance with these steps:
  1. Click Settings Menu⇒Processing Rules.
  2. Select the Processing category radio button.
  3. Choose ESSRule from the list of results.
  4. Deselect time off requests and accruals report.

Any accruals scripts that you might have in place should also be disabled, but not necessarily deleted. Contact SwipeClock Tech Support for assistance on disabling accruals while retaining historical data.
 

Did you find this article helpful?