Documentation

Flat-File Integration

How to synchronise data between your HRIS and Biings.


Overview


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.


Example pack

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

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, Assignements and Salaries data. A different history range is possible depending on your needs and data availability.

Daily synchronisation

Daily synchronisation is used to keep the data in your Biings account (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.


Files structure


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

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.


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 (ex: 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 (ex: 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 (ex: 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 (ex: "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

Assignements file

Employees' job assignements, sometimes refered as "Work contracts". An assignement 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 assignement 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 that 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
weekly_hours Expected working hours per week.
• if not provided, Biings will use the global weekly hours setting
Float
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
job_id * Unique job/position identifier Int
job_function Job function or profession (ex: "Project manager", "Nurse",..) String
job_custom_filter1 Additional job category (could be the job familly or career ladder, etc). String
job_custom_filter2 Additional job category, if any. String
job_custom_filter3 Additional job category, if any. String

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: 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
ex: 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 Format
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 (ex: "Marketing", "Human Resources", "Production", etc.) 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 (ex: 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