HRIS Integration

by Fred Pukay

Table of Contents

Overview of the BetterWorks HRIS Connector

The BetterWorks HRIS Connector allows you to import data from a Human Resources Information System (HRIS) into BetterWorks on a regular schedule. You can see updates from your HRIS in BetterWorks without manual intervention such as:

  • Creation of new users
  • Updates to user information for changes to department or manager
  • Deactivations of users who have left your organization

If you import data for a user who is not in a BetterWorks Department yet, the HRIS Connector will create that department for you. For example, if you import data for the Finance department, but don’t have a department established for them in BetterWorks yet, the department will be created based on the “department_name” value specified in the report.

Requirements to integrate with BetterWorks HRIS Connector:

  1. Create file with user information in CSV or JSON format
  2. Schedule regular file exports to a SFTP server

Approved vendors for the BetterWorks HRIS Connector:

  • Workday
  • Oracle
  • UltimateSoftware (Ultipro)
  • SuccessFactors
  • ADP
  • BambooHR
  • Zenefits

Some vendors may charge a fee for custom report creation, script building, or automation services.

Basic setup for the BetterWorks HRIS Connector

  1. Build a JSON or CSV report encoded in standard UTF-8 format and with the following columns:

    “deactivation_date” (This value should be blank/empty for current employees)

    Please include .csv or .json in the file name. Each file should also be uniquely identifiable.

    By default, the "email" value will be used as the primary identifier for an account. However, "employee_id" and "manager_id" fields can be included in order to use Employee ID as the primary identifier (instead of email) for an account. This will allow for changes to the email address with which an account is associated and will prevent the creation of a new account when an updated email address is imported.

    If you’re using Workday, read their documentation on the Workday Integration Cloud for more information on configuring this report.

  2. Schedule the report to be sent to the BetterWorks SFTP server regularly. The HRIS Connector uses industry standard SFTP cryptography to protect your data and your Customer Success representative will provide you with unique credentials to access the server.

    Note: You can set the interval at which the report is sent to whatever frequency you like, but we recommend once a day. Once your file arrives, the HRIS Connector will sync the data automatically each hour.

  3. Once you’ve uploaded the report, the BetterWorks HRIS Connector will collect the information and use it to create and update user data in BetterWorks. For any issues, please contact to confirm your HRIS Connector is configured and running correctly.

Advanced setup (list of additional fields)

In certain cases, BetterWorks administrators prefer to send additional fields in the HRIS file to keep account management tidy or create more powerful reports in the Admin panel. Please download the CSV attachment at the end of this article to see the template file.

If unique identification numbers are assigned to each person in your company, you may want to consider adding them to the file to ensure BetterWorks accounts stay intact even if someone changes their name, email, or other attribute. We strongly recommend providing both the employee ID and manager ID with each record (with the CEO or leader of the company having a blank manager ID since they're at the top of the organizational chart).


As of 7/1/2017, the following fields will only appear in the Admin panel for reporting purposes:

“custom_01” through “custom_05”

These fields are not visible on a person's profile, the objective filtering list, or in the org chart.

Note: If your system is unable to utilize the "deactivation_date" field, please contact to discuss alternative fields for your file.


1) If a user is omitted from an upload file, what will happen?

If a user is omitted from a file, this will not cause any change or removal of that user’s account in BetterWorks.

2) If I leave a field blank for a user in the file to be uploaded and the content in the corresponding field in BetterWorks has data, what will happen? 

This will depend.  If it’s the email field, the email field is required.  If it’s for a field like custom_01 to custom_05 for example, this will result in an update meaning that the data in the corresponding field in BetterWorks will be removed.  If you are unsure how this works for a specific field, please contact

3) Can I include column headers that are not listed in the HRIS Connector & CSV User Upload Template and if I do, what will happen? 

Including column headers such as ‘employee id’ instead of ‘employee_id’ or column headers that you make up will not be processed by our HRIS connector and will be ignored by it.

CSV Templates




Article is closed for comments.