How can I automatically import profile data via a CSV file?

Modified on Thu, 21 May at 5:50 PM

Please note that setting up an automated HR feed or profile data import may be subject to charges. Final costs will be agreed before implementation.

TABLE OF CONTENTS

Purpose of the HR feed
Important distinction
How the setup works
1. Sample file from the customer
2. Required information before setup
3. Field mapping and mandatory fields
Control logic for creation, updates and deletion
Provision of sFTP credentials
Important notes
Summary

Purpose of the HR feed

An HR feed allows traveller profile data to be transferred regularly from your HR or master data system into our profile system. The feed can be used to create new profiles, update existing profiles and deactivate or delete profiles that are no longer required.

This process is not a simple standard CSV upload where an sFTP account is provided first and the customer then creates a file independently. Before the technical setup can begin, we first require a sample file and an agreed mapping.

Important distinction

Please distinguish between two processes:

One-time or manual profile import: technical processing of prepared profile data.
Automated HR feed: regular processing of HR data including mapping, test setup, production setup and ongoing processing.

This article describes the automated HR feed.

How the setup works

You provide us with a realistic sample file in the target format that will later be used, e.g. CSV or XLSX.
Together, we review the file type, frequency, data volume, target systems, company assignment and desired go-live date.
The columns in your file are mapped to the corresponding profile fields.
It is defined which fields are mandatory and which fields may be overwritten when updates are processed.
After approval of the setup, the HR feed is first configured in a test environment.
After successful testing, the setup is transferred to the production environment.
Only then are the sFTP credentials for productive transmission provided.
The first production file is reviewed. If it matches the agreed structure, processing is automated.

1. Sample file from the customer

An HR feed cannot be set up without a sample file. The sample file must match the format that will later be used in production.

Important: If, for example, an XLSX file is agreed first but a CSV file is later delivered in production, the technical setup may need to be adjusted. For this reason, we require a sample file in advance that reflects the later target process.

2. Required information before setup

The following information is required for setup:

Information	Description
File type	CSV or XLSX
Frequency	Daily, weekly or monthly
Time of file drop	Desired time of delivery. If possible, avoid the time between 07:00 and 08:30 GMT.
Go-live timeline	Desired start date for production use
Delta file	A delta feed is required. The file must contain the changes that need to be processed.
Single or multiple files	If separate files are used for creation, updates or deletion, the file structure must be identical.
Profile count	Expected number of profiles to be processed
Server region	Usually EU
Company / companies	Name, shortname and UUID of the relevant Umbrella Faces companies. If several companies are involved, it must be clear which column determines the company assignment.
Connected systems	For example Atriis, Sabre or other connected systems
Notifications	Email addresses for production notifications: always, on error only or never
Client primary contact	Name and email address of the person to whom the sFTP credentials may be sent
Email credentials upon new profile creation	Indication whether new users should automatically receive login credentials by email

3. Field mapping and mandatory fields

The columns in your file must be mapped to the corresponding fields in the profile system. For this, we require a mapping overview.

Customer column	Target field in profile system	Mandatory?	Overwrite?	Notes
`Action`	n/a	n/a	n/a	For example `SAVE` or `DELETE`
`username`	Username	Yes	Create only	Can be used as unique identifier
`email`	email	Yes	Always	Valid email address
`greeting.commonTitle`	greeting.commonTitle	Yes	Always	Salutation / title according to mapping
`sex`	sex	Yes	Always	Value according to agreed field logic
`name`	name	Yes	Create only	Last name as shown in travel document
`firstname`	firstname	Yes	Create only	First name as shown in travel document
`birthdate`	birthdate	Yes	Always	Format according to the agreed file structure
`location`	`company.uuid`	Yes	According to mapping	Determines which company / entity the profile is assigned to
`Costcentre`	genInternalCostcentre	Yes	Always	Cost centre
`Department`	genInternalDepartment	Yes	Always	Department
Arranger 1 email address	Arranger 1	To be agreed	To be agreed	Assignment of an arranger / assistant
Arranger 2 email address	Arranger 2	To be agreed	To be agreed	Additional arranger / assistant

Mandatory fields: If a field is defined as mandatory and the value is missing from the file, the respective row cannot be processed.

Overwrite logic: For each field, it must be defined whether the HR feed always overwrites the existing value or only populates the field when a profile is created for the first time.

Control logic for creation, updates and deletion

The feed must contain a clear action, for example:

SAVE for creation or update
DELETE for deletion or deactivation

Important: Profiles cannot be deleted if they are not included in the HR feed. Deletions must therefore be actively delivered via the feed.

Provision of sFTP credentials

The sFTP credentials are not provided at the beginning of the project. They are generated and sent to the nominated client contact only after the functional alignment, mapping, test setup and transfer to the production environment have been completed.

After the first production file has been received, it is checked against the agreed structure. Only then is the HR feed processed fully automatically.

Important notes

The sample file must match the later production format.
CSV and XLSX are different file types. A later change may require technical adjustments.
If several companies or entities are involved, it must be clear which traveller is assigned to which company.
company.uuid is used for company assignment.
The unique identification of a traveller is based on the agreed identifier, e.g. username or another agreed unique column.
Mandatory fields without a value will cause the respective row to fail.
Separate files for creation, updates and deletion are possible, but they must use the same structure.
Automatic processing only starts after the first production file has been successfully reviewed.

Summary

For an automated HR feed, we first require a realistic sample file and all relevant processing information. Mapping, mandatory fields, overwrite logic, company assignment and deletion logic are then agreed. Only after successful test setup and transfer to the production environment are the sFTP credentials provided. The first file is then reviewed and, if the structure is correct, the feed is activated for automated processing.