The CSV user management integration allows customers to automate the process of syncing user information between the customer’s system of record (HRIS) and WorkTango. Customers are responsible for uploading the HRIS files with complete employee data, either internally or with the help of their HRIS provider.

Regardless of data changes, our integration runs as a nightly process that reads a CSV file from an SFTP host and uses the data to create, update, and archive users within WorkTango.

FTP Information and Automation

Overview

The content of this file will be derived from an export of your existing HRIS provider. To simplify the process, we recommend working with your HRIS provider to automate sending files.

Note: Please keep in mind HRIS providers may charge for the creation and transfer of the user data report. It can also take them time to generate this report, as it’s based on their queue. Be sure to check with your HRIS contact to see how much it would cost and the timeframe in which they can deliver the report.

FTP upload process

To share HRIS files, your WorkTango Implementation Manager (IM) will create a folder on a secured file transfer protocol (SFTP) portal. You will be provided with credentials and connection information to input into your FTP site. This will connect your folder to WorkTango’s in order to transfer the HRIS file. Your IM will provide you with the following information:

  • Host
  • Username
  • Password
  • File Path: This is the name of the file itself. It must remain static with every file upload.

You’ll also be given a template with the necessary fields to structure employee data. Before making the connection, WorkTango suggests sending a completed user file to your CSM for review. Once approved, upload your file to the FTP site everyday by 3:00AM UTC in order for data changes to be processed overnight.

To get started, you’ll need to decide on the following:

  • Protocol: SFTP or FTPS. SFTP preferred.
  • Host: WorkTango or the customer. WorkTango preferred to assist in troubleshooting, if needed.
  • Encryption: None or PGP, if desired. While it’s not always necessary, we can facilitate the extra security. We’ll send you our public key so you can encrypt the file before uploading it.

The following are the standard column headers for this integration. These headers are case sensitive and must match exactly as they appear below.

Field Name More info Required
first_name Yes
last_name Yes
preferred_name If included, this value will overwrite the value used in the first_name field. Optional
employee_id Employee ID is recommended. Otherwise, include email. More details below in the Additional Information Section. Note: We do not attempt to strip leading zeros from employee IDs during import. Therefore an ID of 123 is considered different than 000123. Please ensure that you are sending IDs consistently in order for our system to match user properly. Yes
login_email The email address the user will use to login. Work email, preferred. Yes
notification_email The email address where the user will receive notification emails. Typically a duplicate of login_email field. Optional
username Most commonly used for companies with Single-Sign On. This should match the identifier used for logging into SSO Otherwise, include email. Yes
job_title Optional
birth_date Formatted mm/dd/yyyy Note: Spreadsheet programs append /yyyy to most dates. If the year is not included, these programs will include the current year Optional
start_date Formatted mm/dd/yyyyNote: WorkTango only accepts one date. Decide whether to use the original date of hire OR re-hire date Optional
manager_id The unique identifier of the employee’s manager. This must match the format used in the employee_id field - either Manager’s employee ID or email Optional
custom_point_rule The name of an existing Point Rule to assign. Your CSM will share more details about how this works. Optional
(group_type)Department Yes
(group_type)Location Yes
(group_type)Country We can accept the following to satisfy Country: Yes

*More groups can be added using the same format (group_type)GROUP NAME.

(group_type)Country Details

To ease implementation, we recommend using alpha-2 or alpha-3 codes for countries because English Short Name lists can have slight inconsistencies in formatting, particularly with articles. For a complete list of the expected English Short Names, please see this table of all countries that we accept and the expected formatting for English Short Name.

Generally speaking, we do not recommend using English Short Names due to variances in what text is expected.

Additional Optional Columns

Field Name More info
status Can be ‘active’, ‘paused’, or ‘terminated’. More on how we recommend using Status below.
termination_date If specified, will mark the user as terminated on date saved; can be of any date format accepted by chronic
remote_image_url The image URL for a user’s profile image. Must be a public-facing URL.
giving Adjusts the user’s giving balance
received Adjusts the user's redemption balance

Additional Information

Group Columns

WorkTango allows our customers to organize their data through what we call Group Types. There is no cap on how many groups a customer can bring over, and most commonly, these align with the data fields saved within your HRIS.

For example, “Location” could be a group type containing the groups “Austin” and “New York”. To specify a group type column, the header must match the name of the group type prefixed by (group_type). The column header for this group would be (group_type)Location.

Status and Archiving Employees

To automatically archive employees who have been terminated or voluntarily left the organization, WorkTango recommends bringing only active employees onto the file. Employees whose data isn’t on the file, will be automatically archived and therefore, unable to log into the platform or send/receive recognition. Archived employees will maintain both their Giving and Earned Points; these will not be zeroed out or refresh (quarterly or monthly).

Unique Identifiers

Our integration works by building a profile for each user based on a static Unique Identifier, like Employee ID. This Unique Identifier allows the system to update any other data points that might change relative to the user.

While we recommend using Employee ID, we recognize that sometimes our customers don’t have this data point. For those who don’t, we can use an Email address, but it must remain constant or duplicate users could be created in the system.