Resources

Flat-file Integration

Synchronise your data between Biings and your HR systems.

Welcome to our Flat-file documentation. If you are looking to synchronise your HR data with Biings you've come to the right place. Flat-File Integration (FFI) is based around completing an integration through the exchange of CSV text files. This documentation will help you format your data so that Biings can sychronize with your system. Depending on the products enabled for your account (Pilot and/or Notify), a set of up to 6 files can be synchronised with Biings. Files are linked together either through Persons ID or Org Units ID.

Synchronisation, history and initial import

Let's start with past data. The initial import, or first synchronisation, is used to setup your Biings account and populate it with the history of your HR data. This allows users to immediately recognise their team when they first log into Biings, and remove the need of having to duplicate things from your current HR system. We recommand the first set of CSV files to include the last 3 years of Absences, Persons, Assignments and Salaries data. A different history range is possible depending on your needs and data availability.

Once the initial set of data is imported, Biings uses daily synchronisation to keep data (absences, persons, salaries, etc) in sync with your HR system. Biings checks daily for new CSV files uploaded to your dedicated SFTP folder. If the file contains new or updated information, Biings will synchronise its database with it. Daily synchronisation uses the same CSV files, however the history should be limited in time (e.g. the last 3 months), depending on how far in the past you allow Absences (or other data) to be modified on your HR system.

N.B. Org Units and Occupations files should not include any history and simply reflect the current situation.

Example files

An example is worth a thousand words. Download our example files to quickly understand how files should be formated and how to relate them to one another.

We also support a single-file format limited to Persons and their job assignements.

Example pack

Download an example pack of 6 CSV files correctly related to one another.

Example pack | 6 files

Single-file example

Download a single-file example. To be used when absence data synchronisation is not necessary.

Single CSV example

Files structure

Fields marked with a red "*" are required for the file to be accepted.
The entire record (CSV line) will be ignored if one of the required fields is empty or has the wrong format.

Fields marked with a yellow "*" are recommended for the use of Biings NOTIFY.
Recommended fields are mainly used to auto-fill insurance claim reports.

Absences file

Employees' absences including planned absences such as holidays and maternity leaves. An absence is defined as a period of time someone is away from work or unable to work.

Automatic Absence Consolidation
After each synchronisation Biings runs a consolidation algorithm on newly synchronised absences. This insures all absence-related analytics are accurate in regards to the original absence events. Please refer to our consolidation rules page to understand how and when Biings merges absences together.

Absence consolidation rules

Column Name	Description	Type	Format
id *	Unique absence identifier • can be omitted for a single data import	Int/String
person_id *	Person identifier • must match with an `Id` in the Person file	Int/String
case_id	Case identifier, grouping multiple absence together.	Int
from *	Date at which the work incapacity starts (e.g. 2021-10-27 07:30:00). • date must be earlier or same date as `end_date` • the "hh:mm" value is optional	String	`yyyy-mm-dd hh:mm`
until *	Date at which the work incapacity ends. • date must be later or same date as `start_date` • an Empty value means the absence is still ongoing • the "hh:mm" value is optional	String	`yyyy-mm-dd hh:mm`
time_due	Minutes of work due, or missed, during the absence (e.g. 120). • any kind of rates or time rules should already calculated (Biings will not apply any treatment to it and use the value as is) • when provided, acts as a replacement to the standard calendar duration of the absence • recommended for a more accurate absence rate computation	Int
rate *	Incapacity rate (rate at which the person is not at work). • 1 means completly absent, 0.5 means 50% absent, etc. • defaults to 1 if not provided	Float	Between `0` and `1`
reason_id	Unique identifier of the absence cause / reason of absence	String / Int
reason *	Absence reason/cause label (e.g. Sickness or Accident)	String
planned	Whether the absence is planned or not. • NB: Sick-leaves are generally unplanned. Holidays are usually planned.	Int	`0`: unplanned `1`: planned
comment	Any notes available about that particular absence (e.g. "Prefers to be contacted on his mobile phone.")	String

Persons file

All persons/employees in your organisation with their personal details.

Column Name	Description	Type	Format
id *	Unique person identifier	Int/String
lastname *	Person's last name	String
firstname *	Person's first name	String
gender *	Gender of the person	String	`F`: Female `M`: Male `N`: Neutral
email *	Professional email address	String	Email format
sso_account	SSO account username	String
avs_number *	Swiss AVS number	String	`756.XXXX.XXXX.XY`
phone_pro	Professional phone number	String	Max 100 characters
phone_private *	Private phone number	String	Max 100 characters
mobile_pro	Professional mobile number	String	Max 100 characters
mobile_private	Private mobile number	String	Max 100 characters
address_type	Type of address (aka "address label")	Int	`2`: Home `4`: Office
address_note	Note or complement to the address	String
address_line1 *	Address line 1	String
address_line2	Address line 2, if any	String
address_line3	Address line 3, if any	String
address_zip *	Postal code	String
address_city *	City of residence	String
address_country *	Country code	String	ISO 3166-1 (alpha-2 or alpha-3)
birthdate *	Date of birth	Date	`yyyy-mm-dd`
start_working_date	Date the person first joined the company, or the hiring date	Date	`yyyy-mm-dd`
marital_status	Current marital status	Int	`1`: Single `2`: Married `3`: Divorced `4`: Widow `5`: Separated `6`: Registered partnership `7`: Dissolved partnership `9`: Unknown
nb_children	Number of dependent children	Int
language *	Communication language	String	ISO 639-1
nationality *	Country code	String	ISO 3166-1 (alpha-2 or alpha-3)
zemis	ZEMIS/SIMIC number (for non-Swiss citizens)	String
special_cases	Special case of insurance	Int	`0`: No particular case `1`: Family member, partner `3`: Optional insurance
with_holding_tax	Whether subjected to holding-tax from the income source.	Int	`0`: No `1`: Yes, is subjected to holding-tax

Assignments file

Employees' job assignments, sometimes refered as "Work contracts". An assignment defines a moment in time (start and end) where the person has worked in your organisation, where (in which Org Unit) and at what percentage (rate).

A person can have more than one assignment at the same time provided that the total contract_rate does not exceeds "1" (100%).

Column Name	Description	Type	Format
id *	Unique Assignment identifier (recommended if available). • if unavailable, Biings can generate the `Id` based on the combination of `person_id` + `start_date` + `ou_id`	Int/String
person_id *	Person identifier • must match with an `Id` in the Person file	Int/String
ou_id *	Organisational Unit identifier • must match with an `Id` in the Org Units file	Int/String
start_date *	Assignment start date • date must be earlier or same date as `end_date`	String	`yyyy-mm-dd`
end_date *	Assignment end date • date must be later or same date as `start_date` • an Empty value means the contract length is indeterminate	String	`yyyy-mm-dd`
rate *	Work rate for this particular assignment	Float	Greater than `0`, Max `1`
contract_rate	Overall/Total work rate In most situations a person is hired to fill only one position. In that case `contract_rate` and `rate` have the same value. When an employee fills more than one position (aka assignments), the `contract_rate` is the sum total of each of his/her assignment `rates`.	Float	Greater than `0`, Max `1`
contract_status *	Employment contract status.	Int	`0`: Permanent `1`: Fixed-term
job_id *	Unique job/position identifier	Int
job_function	Job function or profession (e.g. project manager, nurse)	String
job_custom_filter1	Additional job category (e.g. job family, career ladder).	String
job_custom_filter2	Additional job category, if any.	String
job_custom_filter3	Additional job category, if any.	String
position *	Person's professional position for this assignment.	Int	`1`: Senior `2`: Middle `3`: Employee `6`: Apprentice `7`: Trainee `9`: Unknown
regular_workplace	Person's usual place of work for this assignment (e.g. office, shop).	String
weekly_hours	Expected working hours per week. • if not provided, Biings will use the global weekly hours setting	Float
frequency *	Working frequency for this assignment.	Int	`0`: Regular `1`: Irregular `2`: Short time `9`: Unknown
vacation_days	Number of days of vacation allowance per year. • should be in relation to a 100% work rate (not pro-rated) • if not provided, Biings will use the global vacation allowance setting	Float

Salaries file *

Employees' salaries. One line defines the salary (or salary component) of a person for a given period of time.

Column Name	Description	Type	Format
id *	Unique Salary record identifier • if unavailable, Biings can generate the `Id` based on the combination of `person_id` + `amount` + `start_date`	Int/String
person_id *	Person identifier • must match with an `Id` in the Person file	Int/String
code *	Type of salary or benefit	Int	`100`: basic/gross salary `101`: LAA salary `102`: LAAC salary `103`: PGM salary `200`: childs and family benefits `300`: bonus or 13th salary `400`: vacation and public holiday compensation `500`: other supplements
amount *	Salary amount	Float
period *	Frequency period at which the salary is paid.	Int	`1`: hourly `2`: daily `3`: monthly `4`: yearly `5`: percentage `6`: one time
start_date *	Date at which the salary starts being effective. • date must be earlier or same date as `end_date`	String
end_date *	Date at which the salary stops being effective. • date must be later or same date as `start_date` • an Empty value means the salary is always in effect. An end_date is required as soon as a new salary is in effect for that person.	String
currency	Currency used for the salary.	String	ISO 4217 e.g. `CHF`, `EUR`

Org Units file

All current Organisational Units (departments, services, teams, etc). This file is used to represent the organisational structure of your company. An Org Unit can be of any size or importance, either an entire department or a small team, it depends on the level of granularity you need.

This file should only include current Org Units, history should not be included.

Org Units with no parent_id will be considered as "top level" Org Units.
Biings supports multiple parallel organisational structures.

Column Name	Description	Type
id *	Unique unit identifier	Int/String
parent_id *	Parent Unit identifier • must match with the `Id` of another Org Unit in that same file	Int/String
name *	Org Unit name (e.g. Marketing, Human Resources, Production)	String

Occupations file

All persons having a specific occupation or management role towards another person or group of persons. This file is used to describe the type of relations existing between every person (i.e. managers, HRBP, chiefs, substitute managers, etc).

Occupations are necessary to enable specific notification workflows and access controls.
This file should only include current Occupations, history should not be included.

You can choose to describe occupations by: A) specifing each individual Person-to-Person relation ; B) grouping a person's relations to all the persons within a specific Org Unit.

A) Person to Person:

Column Name	Description	Type	Format
person_id *	Person Id of the person the occupation is targeted to. • must match with an `Id` in the Person file	Int/String
to_person_id *	Person Id of the person towards who the relation is (e.g. ID of the person's Manager). • must match with an `Id` in the Person file	Int/String
kind *	Kind of relation	Int	`1`: Substitute manager `2`: Manager `4`: RH

B) Person to Org Unit:

Column Name	Description	Type	Format
person_id *	Person Id of the person the occupation is targeted to. • must match with an `Id` in the Person file	Int/String
ou_id *	The Org Unit ID with all the person towards who the relation is. • must match with an `Id` in the Org Units file • the person's occupation will be the same for all the persons inside that Org Unit	Int/String
kind *	Kind of relation	Int	`1`: Substitute manager `2`: Manager `4`: RH