Getting Started with Goodwings
      Back to home
      1. Help Center
      2. Getting Started with Goodwings

      SFTP - Overview for HR Feeds

      Technical overview for configuring Goodwings to connect to your HR feed

      Overview

      Your Goodwings users (travelers, arrangers, approvers, etc.) must have profiles within the Goodwings 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). Goodwings 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 Goodwings 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: Goodwings 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 Goodwings 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, Goodwings 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 Goodwings database, a new profile will be created for that user in Goodwings.

      • 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 Goodwings 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 Goodwings database, the user profile will be deactivated. If no record in the Goodwings 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 Goodwings 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 Goodwings. 

      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). 

      Hosting and authentication

      Goodwings hosts your SFTP folder on its own SFTP server (via AWS). Each client will have a unique user account with direct access to their specific SFTP folder. We support key-based authentication. As a result, you will need to create a public-private key pair and share the public key with Goodwings. The key must be in openSSH format. Steps to help you create the keys are in Appendix 2.

      Frequency and scheduling

      You determine the scheduling and frequency of file uploads. Goodwings uses the file object creation trigger to initiate the HR feed upload. This means that as soon as you push a file to your folder on the Goodwings SFTP server, the Goodwings application will begin processing the upload. We recommend you upload a file at least once a day to be sure to notify Goodwings of any additions/updates/deletions that may have occurred. If this practice is followed: 

      • new users will be provisioned with a Goodwings 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. 

      Reporting and error-handling

      We collect data on your file uploads and use it to create an internal report after each file upload. This report is sent to the email address(es) you provided in the SFTP email notification field during setup. For each file uploaded, the report will contain: 

      • any reasons why a file upload failed (wrong format, missing column names, etc.).

      • any reasons why a row within a file was unable to be uploaded. We do not do partial updates and will fail the row if an error occurs in a specific column or a required field is missing for that row. 

      • the status of the upload (pending, successful, failed).

      You can use the contents of this file to troubleshoot any errors. If you are unable to correct the error, contact technical support. 

      FAQs

      1. Do we accept an incremental file that only contains those user records that need to be either updated or added?

        • Yes

      2. Does the file you upload (whether sent via SFTP or manual upload) need to include optional columns even if you are not using those columns?

        • No

      Appendices

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

      Appendix 1: HR file format

      Note: You must ensure that you have sent Goodwings 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

      		  

      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

      		  

      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

      		  

      Appendix 2: How to create a public SSH key for the SFTP server

      Use the instructions below to create the public SSH that you will provide to Goodwings.

       

      Format:

      • Type: String

      • Length Constraints: Maximum length of 2048.

      Pattern:

       ^ssh-rsa\s+[A-Za-z0-9+/]+[=]{0,3}(\s+.+)?\s*$

      Creating SSH Keys on Microsoft Windows

      Run this command on the command line(cmd):

      ssh-keygen -m PEM -f key_name 

      Where

      • -m is Format

      • -f is Keyname

      Creating SSH Keys on macOS, Linux, or UNIX

      Run this command on terminal:

      ssh-keygen -P "" -m PEM -f key_name

      Sample Key:

       

      ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDDJB9oBRPrBegMDPEQo+HmNDb/jKUJL6q2kQpNNMDjNps9mhhwJ1dP/lOavMitBPAndeXlwaNEm2XbGaSrZtD/tbQTX1HQjP6pacy+Alf8kYBm5QFfl/Z6lGC8qHys10fpRXgYE7UhdSv6VyRqt1gELGFQwVBZ2kJJuBGJF1IRywwvG/h68B8iWU1+6KEWYQoUcT45r3j3otnx4NhhzpTiNgDbMk0ix+kar4/IstobRLcb7rt7FoUerTLNrVDi69DqbsGY5LN+NM8jVx0sPQLRC/ruil8pTHP3k4rDCc7a80+sH4sUTW+mHc7MTqbi/CcyyFAD8h7p6WqxEydOaJjMnvqAbE17BOj0TSxv3HMohTf3skzE7PbzVcjIfHTpFPGxmJkghAYAMi5l9VvAs91IpVylxjqPss3xQQJIZEmQdG2k7zk/UpsUFlmaOj6lCHRicFKCixKekzzm3nFuJvDEklurtydOQjZ8WkPzTSJfZBdKMuMUi0SQ9m9ZAw99t0=