File: Standard import of staff (unique file)

Voir la version française

Object of the interface

This interface has been designed to allow import of staff files from any third system and at any selected level. Some of them relate for example to staff data, contract type, structures, calendar, badge group or qualification/level assignment. 

Learn more about setting up this import.

Processing imported information

For each import file, the file contains one line per Identification number.

Employee that does not exist in the database

If the identification number in the file does not exist in Timesquare®, the import allows the addition of
new employees. These are then automatically assigned to the selected structure from the date of import
until 31/12/2099.

Employee that already exists in the database

If an import is launched for an employee who already exists in the database, the import allows updating
the database by deleting and replacing the existing information. There are several scenarios depending
on the type of field, mandatory or not, empty or entered.

Importing an entered data into a field already valued in

If I import new data in a field that is already valued in Timesquare, the new data contained in the imported
file overwrites the existing values in the database. History is not kept.

Example concerning the contract:

• In Timesquare, a person has a temporary 28H contract from 01/03/20 until 31/03/20. Then he has a
  temporary 35H contract from 01/04/20 until 03/05/20. Finally, he has a permanent contract from
  04/05/20.
• The import contains only the permanent contract from 04/05/20.

The import is executed. In Timesquare, I now only view the permanent contract from 04/05/20.

Importing an empty data into an optional field

If I import an empty data into an optional field in Timesquare, the line corresponding to this data is:

• ignored and any data entered in Timesquare is not modified or
• imported empty and overwrites any data entered in Timesquare

Example concerning the administrative information:

In Timesquare, an employee whose Address field is filled in with "1 rue de Paris".

I import a file for which the Address field is empty.

If the Empty fields are ignored option is selected, the import is executed and the address entered in the
database is not modified.

If the Empty fields cancel and replace existing values option is selected, the import is executed and the
address entered in the empty wind database.

Importing empty data into an optional "drop-down list" type field

If I import empty or erroneous data, namely a value that does not exist in an optional Timesquare drop-
down list type field, the line is imported and the empty field is replaced by the first data from the drop-
down list. For example, concerning the Gender field, the line would be imported with the value "Not filled
in".

Example concerning administrative information:

In Timesquare, a person whose Gender field is set to "Female".

I am importing a file for which the Gender field is empty.

The import is executed and replaces the value of the field with the first value from the drop-down list: for

Gender, the value becomes "0" (for Not specified).

Importing an empty data into a mandatory free field

If I import an empty data into a mandatory free field in Timesquare, the line corresponding to this data
is not imported. The other error-free lines in the file are imported correctly. A notification indicates that
the import has completed with an error. If I display the result, a message indicates which field in which
line is in error.

Example concerning the administrative information:

I import a file containing a line for which the First name field is empty.

The import is executed and indicates an error for the line whose first name is not filled in.

Import of contract or structure assignments

By default, the processing of contract or structure assignments provides that the existing assignments
are deleted from the database and the new assignments are imported.

However, it is also possible in the settings not to delete the existing assignments and to add the new
assignments.

In this case, the management rules are as follows depending on the case.

Case 1: the imported assignment does not have a common period with the present assignments

It is simply added.

Same contract / same structure

Note: Cases 1-3 and 1-4 are special cases where the start date of the new assignment coincides with the day after the end date of the already present assignment.

The operation will be the same in the case of a condition whose end date coincides with the day before the start date of an assignment already present.

Different contract / different structure

Case 2: the imported assignment has a common period (but not all) with one of the assignments present

Same contract / same structure

The new assignment is combined with the one already present.

Different contract / different structure

The new assignment is integrated, the one that is already present is shortened at the beginning or at the end depending on the common period.

Note: Please note that case 2.3 is a variant of case 2.2 where the end date of the assignment modification is identical to the end date of the initial assignment.

Case 3: the imported assignment is included in one of the assignments already present

Same contract / same structure

The new assignment is combined with the one already present.

Different contract / different structure

Case 3.1, if End B> Start B then the new assignment is inserted, the one which is already present is transformed into two assignments, one which ends one day before the start of the new assignment and one which begins one day after the end of the new assignment (3.1).

Case 3.2, if End B = Start B then it is an end of contract. The new assignment is inserted and the existing one is ended.

Case 4: the imported assignment includes one of the assignments already present

The imported assignment cancels and replaces the one already present.

Same contract / same structure

Different contract / different structure

Group assignment import

Cancel and replace imported group assignments for affected common periods check box unchecked

If the Cancel and replace imported group assignments for the affected common periods check box is not checked, it is not allowed to import overlapping assignments for the same group.

If I try to import the assignment of an existing group in the database and over overlapping periods (the same group), then the import fails and the information is available.

If an assignment from a group that does not exist in the database is imported, the existing assignments are not deleted.

Cancel and replace imported group assignments for affected common periods check box checked

If the Cancel and replace imported group assignments for common periods box is checked, the deletion and replacement of existing assignments only concerns cases where assignments of the same group overlap (overlap between the existing assignment in base and the 'imported assignment).

If an assignment from a group that does not exist in the database is imported, the existing assignments are not deleted.

If an assignment from a group that exists in the database but whose periods do not overlap is imported, the existing assignments are not deleted.

Self-planning group

In case of a self-planning group import:

• The assignment start date must be the first day of the week. If it isn't, the group assignment is rejected and a trace is present in the logs.
• The assignment end date must be the last day of the week. If it isn't, the group assignment is rejected and a trace is present in the logs.
• The group assignment must not overlap with an existing self-scheduling group assignment. If it doesn't, the group assignment is rejected and a trace is present in the logs.

File name

The file can be named in two ways depending on whether the third-party system making it available generates a different file for each day or a single file containing multiple days. The file contains one line per employee ID.

Undated file (custom label)

The name of the import file is free (label + extension) but once defined in the configuration of
import, it must not change.

Example 1: the Label field in the configuration and the import file are both named
Staff.txt.

Example 2: the Label field in the configuration and the import file are both named
staff_Timesquare.001.

Dated files (with date pattern)

The file name must comply with a specific syntax including the date of the data provided. The Label field must define the naming chosen. Thus, LabelJJMMAAAA.EXT, LabelJJMMAA.EXT, LabelAAAAMMJJ.EXT,  LabelAAMMJJ.EXT or LabelYYYYMMDD.EXT are the supported wordings in which:

• "Label" is made of a string of alphanumerical characters that can be personalized
• "JJ" and "DD" stand for the day, "MM" stands for the month, "AA", "AAAA" and "YYYY" stand for the year, that can be indifferently written with 2 or 4 characters
• "EXT" is an alphanumerical string with 3 characters maximum that can be personalized

Example 1: the Label field in the configuration is named staff_JJMMAA.txt and the three import files are
named staff_040520.txt, staff_050520.txt and staff_060520.txt.

Example 2: the Label field in the configuration is named staffAAAAMMJJ.001 and the three import
files are named staff20200504.001, staff20200505.001 and staff20200506.001.

Example 3: the Label field in the configuration is named AAMMJJ.txt and the three import files are
named 040520.txt, 050520.txt et 060520.txt.

Format

Text. UTF-8 encoding.

Separator between two information

The separator between two items can be a semicolon, a comma, a tab or a vertical bar.

Description of the file content

#	Field name	Type	Length	Note	Mandatory
1	Name	Alphanumerical	255		Yes
2	First name	Alphanumerical	255		Yes
3	Employee Id	Alphanumerical	255	Must be unique	Yes
4	Payroll Id	Alphanumerical	255
5	Birth date	Date		DD/MM/YYYY
6	Address 1	Alphanumerical	255
7	Address 2	Alphanumerical	255
8	Address 3	Alphanumerical	255
9	Address 4	Alphanumerical	255
10	Postal code	Alphanumerical	8
11	City	Alphanumerical	255
12	Country	Alphanumerical	255
13	Telephone	Alphanumerical	15
14	Mobile Phone	Alphanumerical	15
15	E-mail	Alphanumerical	255	The "local" part (everything before the @) is limited to 64 characters.
16	Gender	F (female), M (male) or empty (not specified)	1
17	Family situation code	Alphanumerical	38
18	Number of children	Numerical		Integer
19	Team code	Alphanumerical	38
20	Identifier	Alphanumerical	255
21	Grouping	Alphanumerical	20
22	Diverse 1	Alphanumerical	255
23	Diverse 2	Alphanumerical	255
24	Diverse 3	Alphanumerical	255
25	Diverse 4	Alphanumerical	255
26	Hiring date	Date		DD/MM/YYYY
27	Departure date	Date		DD/MM/YYYY
28	Structure code	Alphanumerical	40		Yes*
29	Structure start date	Date		DD/MM/YYYY	Yes*
30	Structure end date	Date		DD/MM/YYYY	Yes*
31	Contract code	Alphanumerical	12		Yes*
32	Type of contract	Alphanumerical	38		Yes*
33	Contract start date	Date		DD/MM/YYYY	Yes*
34	Contract end date	Date		DD/MM/YYYY	Yes*
35	Annualized contract	Alphanumerical	1	1 if annualized 0 if not
36	Calendar code	Alphanumerical	38		Yes*
37	Calendar start date	Date		DD/MM/YYYY	Yes*
38	Calendar end date	Date		DD/MM/YYYY	Yes*
39	Badge code	Alphanumerical	20		Yes*
40	Badge start date	Date		DD/MM/YYYY	Yes*
41	Badge end date	Date		DD/MM/YYYY	Yes*
42	Group code	Alphanumerical	10		Yes*
43	Group start date	Date		DD/MM/YYYY	Yes*
44	Group end date	Date		DD/MM/YYYY	Yes*
45	Contract assignment external code	Alphanumerical	255
46	Qualification code	Alphanumerical	38		Yes*
47	Level code	Alphanumerical	38
48	Individual rate	Numerical		Empty or positive or zero real value
49	Qualification/level assignment start date	Date		DD/MM/YYYY	Yes*
50	Qualification/level assignment end date	Date		DD/MM/YYYY	Yes*
51	T&A active	Alphanumerical		1 if active 0 if not
52	Contract variation code	Alphanumerical	12		Yes*
53	Contract variation start date	Date		DD/MM/YYYY	Yes*
54	Contract variation end date	Date		DD/MM/YYYY	Yes*
55	Annualized Contract variation	Alphanumerical	1	1 if annualized 0 if not
56	Self-planned	Alphanumerical	1	1 if self-planned, 0 if not
57	End of contract termination	Alphanumerical	1	1 if termination, 0 if not
58	End of contract variation termination	Alphanumerical	1	1 if termination, 0 if not
59	Seniority date	Date		DD/MM/YYYY
60	Mandates code	Alphanumerical	6
61	Mandates category	Alphanumerical	6
62	Mandate start date	Date		DD/MM/YYYY
63	Mandate end date	Date		DD/MM/YYYY

* the fields related to the assignment of structure, contract, calendar, badge, group, qualification/level, contract variation are only mandatory if I add or modify one of these assignments.

Example of content

Example of file

Jerez;Pedro;BRZ33;BRZ33P;01/01/1985;32 Rue de Mantes;Batiment A;1er etage;Open Space;92711;Colombes;France;01 55 66 89 89;06 55 66 89 89;[e-mail];M;M;1;BRZ;Identifiant;Regroupement;Divers 1;Divers 2;Divers 3;Divers 4;01/10/2019;;BRZ-AND;01/10/2019;31/12/2099;BRZ35H;CDI;01/10/2019;31/12/2099;0;CALBRZ;01/01/2019;31/12/2099;BDG1;01/01/2019;31/12/2099;CADRES;01/10/2019;31/12/2099;CODEEXT;BRZQA;BRZE1;;01/01/2025;31/12/2099;0;;;;0;0;0;0;01/01/2019;DPTI;DP;01/01/2026;31/12/2026
Adra;Lorena;BRZ33;BRZ33P;01/01/1985;32 Rue de Mantes;Batiment A;1er etage;Open Space;92711;Colombes;France;01 55 66 89 89;06 55 66 89 89;[e-mail];M;M;1;BRZ;Identifiant;Regroupement;Divers 1;Divers 2;Divers 3;Divers 4;01/10/2019;;BRZ-AND;01/10/2019;31/12/2099;BRZ35H;CDI;01/10/2019;31/12/2099;0;CALBRZ;01/01/2019;31/12/2099;BDG2;01/01/2019;31/12/2099;CADRES;01/10/2019;31/12/2099;CODEEXT;BRZQA;BRZE1;;01/01/2025;31/12/2099;0;;;;0;0;0;0;01/01/2019;DPSU;DP;01/01/2026;31/12/2026