SFTP - Instructions for HR feeds

Modified on Thu, 17 Oct at 5:13 PM

SFTP - Instructions for HR feeds

TABLE OF CONTENTS

SFTP - Instructions for HR feeds

Overview

For general SFTP guidelines and information, see SFTP - Setup instructions.

Your Spotnana users (travelers, arrangers, approvers, etc.) must have profiles within the Spotnana Online Booking Tool (OBT) before they can begin booking their travel. To ensure that these users are given the correct access to the system (new hires granted access, access revoked for departing employees), the currency of these profiles must be maintained (via record creation, updating, and deletion). Spotnana also uses HR data, such as reporting hierarchy and legal entities, to define various policies, approvals, and other travel and payment settings.

To ensure we have the correct information, you upload your HR feed as a CSV file to the Spotnana server. You can schedule this upload to occur as frequently as you like. Spotnana will process the file as soon as we receive it.

Note: Spotnana also offers direct connections to several common HR systems (Bamboo HR, ADP Workforce Now, and Workday).

Architecture and workflow

This diagram shows a scenario in which several clients are uploading their HR data to Spotnana using SFTP.

Instructions

This section contains helpful information to ensure your file uploads are successful.

HR Feed file processing logic

The primary field used to identify the user is the Employee ID.

Note: In certain cases, Spotnana can use the Business Email as the employee identifier. However, this does come with certain limitations. For example, if the user’s Business Email changes (name changes, domain changes due to relocation, etc.), our system will deactivate the original account and create a new account for that employee.

The logic used to process the contents of your CSV file is as follows:

If the ACTION column for the user row is set to CREATE and the Employee ID or Business Email are not found in the Spotnana database, a new profile will be created for that user in Spotnana.
If the ACTION column for the user row is set to UPDATE and either the Employee ID or Business Email match an existing value in the Spotnana database, the Spotnana profile for that user will be updated with any new information that is in your file.
- Note: If a user had optional fields in their profile from a previous upload and those fields are missing within a subsequent update, those values will be removed from the profile.
If the ACTION column for the user row is set to DELETE and either the Employee ID or Business Email match an existing value in the Spotnana database, the user profile will be deactivated. If no record in the Spotnana database matches the Employee ID or Business Email, the row will be skipped and no action will be taken.

Note: Each user profile created must be associated with a legal entity. These legal entities must already exist in Spotnana before you attempt to upload user profiles. Offices are optional. However, if your user CSV file refers to an office association for any of the users being uploaded, those office definitions must already exist within Spotnana.

File format and naming conventions

The .CSV HR feed file name must use this format:

hr_feed.*.csv

where the * (wildcard) represents any characters you wish to add to the name. Note that the “.” after “feed” and the “.” before “csv” must be present. The file name is not case sensitive. We recommend including the date and time in the name of the file (to ease troubleshooting in the future). For example:

hr_feed.spotnana_integration_<DateTime>.csv

The .CSV feed file must also be in a specific format. The column names must exactly match the defined format (see HR file format section below). More details on file formatting can be found in Appendix 1.

We require certain data level validations to be followed (see HR file format section below for details).

Frequency and scheduling

For general information on frequency and scheduling, see the Frequency and scheduling section of SFTP - Setup instructions.

We recommend you upload a file at least once a day to be sure to notify Spotnana of any additions/updates/deletions that may have occurred. If this practice is followed:

new users will be provisioned with a Spotnana profile the day their employment begins and be able to book travel immediately. This assumes you add the employee names from the file you upload on their start date.
departing employees will have their access revoked on their last day. This assumes you remove the employee names from the file you upload on their end date.

HR file format

Use this information to help you ensure the data in your HR feed upload is correctly formatted and prepared.

Note: You must ensure that you have sent Spotnana your public SSH key and that we have configured an SFTP folder for you before any of your files can be processed.

Column name	Required / Optional	Notes
Action	Required	This field must be set to “CREATE”, “UPDATE”, or” DELETE” for each row. That defines the action that must be taken with the information in the row.
Employee ID	Optional	Employee ID is preferred. Business Email will be used if no Employee ID is provided. The Employee ID should only be used for a maximum of one user profile. It must be unique for each user.
First Name	Required
Middle Name	Optional
Family Name 1	Required
Family Name 2	Optional
Business Email	Required
Business Phone ISO Country Code	Conditional	Two-letter ISO country code ("US" or "IN").
Business Phone Country Code	Conditional	Numeric country code. Must not include any special characters ('+'). A sample value might be “91”.
Business Phone Extension	Optional
Business Phone Number	Conditional	This field is not required. However, if it is provided, both an ISO country code and country code must also be provided (those fields are listed as conditional above). This field can only contain numeric digits and must be between 4-10 digits. No special characters may be used (no hyphens, etc.).
Office Name	Optional	The value of the Office Name field in your HR feed must exactly match the name of that office in the Spotnana Online Booking Tool UI (including any special characters such as periods, commas, as well as spaces). For example, if your office was named “Paris, France (main office)” in the Spotnana Online Booking Tool, the value of the Office Namefield in your HR feed must match that exactly. In this scenario, “Paris, France” or “Paris (main office)” would cause a failure. Note: All offices must exist in the Spotnana Online Booking Tool before including them in your HR feed upload. For details, see Upload office records.
Manager's Employee ID	Optional	Manager's Email Address is required. If managers also have an Employee ID (if your company uses Employee IDs), then both Manager's Email Address and Manager's Employee ID are required.
Manager's Email Address	Required	Manager's Email Address is required. If managers also have an Employee ID (if your company uses Employee IDs), then both Manager's Email Address and Manager's Employee ID are required.
Department	Optional
Position Title / Designation	Optional	Sample values are: “ VP”, “CEO”, “CFO”.
Cost Center	Optional
Legal Entity Name	Required	The value of the Legal Entity Name field in your HR feed must exactly match the name of that legal entity in the Spotnana Online Booking Tool UI (including any special characters such as periods, commas, as well as spaces). For example, if your legal entity was named “Spotnana Technology, LLC” in the Spotnana Online Booking Tool, the value of the Legal Entity Namefield in your HR feed must match that exactly. In this scenario, “Spotnana Technology LLC” or “Spotnana Technology” would cause a failure. Note: All legal entities must exist in the Spotnana Online Booking Tool before including them in your HR feed upload. For details, see Upload legal entity records.
Grade	Optional
Country Code	Optional	Two- or Three-letter ISO Country Code ("US" or "USA")
Worker Type	Optional	Sample values are: “Employee”, “Contingent”, “Intern”, “Seasonal”
Accounting Code	Optional