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 or badges assignation.
- Staff Data: The import is used to add new employee’s details into Timesquare®.
- Staff Contract Assignment: Relates contract types to employees once imported through Staff Data file.
- Employees-Structure Assignment: Allocates employees once imported to related structures.
- Employees-Calendar Assignment: Allocates calendars to employees.
- Employees-Badges Assignment: Allocates calendars to employees.
- Employees-Qualifications-Level Assignment: Allocates qualification/level to employees.
Learn more about setting up this import.
Processing imported information
For each import file, the file contains one line per employee ID.
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 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.
The import is executed. In Timesquare, the value of the Address field is now empty.
Importing an empty data into an optional drop-down list field
If I import an empty or erroneous data, meaning a value that does not exist into an optional drop-down list field in Timesquare, I must define in the import settings if:
- The line is not imported: the line corresponding to this data is not imported, the rest of the file is imported.
- The line is imported with the first value in Timesquare: the line is imported, and the empty field is replaced by the first data item from the drop-down list.
Example concerning the administrative information:
In Timesquare, an employee whose Gender field is filled in with "Female".
I import a file containing a line for which the Gender field is empty.
If the option The line is not imported is checked, the import is executed and indicates an error for the line for which the Gender is not completed.
The import is executed and replaces the value of the field with the first value in the drop-down list: for the Gender, the value is "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
Staff data
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.
Unique file
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
admistrative.txt.
Example 2: the Label field in the configuration and the import file are both named
admistrative_Timesquare.001.
Multiple files
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 admistrative_JJMMAA.txt and the three import files are named admistrative_040520.txt, admistrative_050520.txt and admistrative_060520.txt.
Example 2: the Label field in the configuration is named admistrativeAAAAMMJJ.001 and the three import
files are named admistrative20200504.001, admistrative20200505.001 and admistrative20200506.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 is a semicolon.
Description of the file content
| Field name | Type | Length | Note | Mandatory |
|---|---|---|---|---|
| Name | Alphanumerical | 255 | Yes | |
| First name | Alphanumerical | 255 | Yes | |
| Employee Id | Alphanumerical | 255 | Must be unique | Yes |
| Payroll Id | Alphanumerical | 255 | ||
| Birth date | Date | DD/MM/YYYY | ||
| Address 1 | Alphanumerical | 255 | ||
| Address 2 | Alphanumerical | 255 | ||
| Address 3 | Alphanumerical | 255 | ||
| Address 4 | Alphanumerical | 255 | ||
| Postal code | Alphanumerical | 8 | ||
| City | Alphanumerical | 255 | ||
| Country | Alphanumerical | 255 | ||
| Telephone | Alphanumerical | 15 | ||
| Mobile Phone | Alphanumerical | 15 | ||
| Technical field | This field must be empty | |||
| Alphanumerical | 255 | The "local" part (everything before the @) is limited to 64 characters. | ||
| Gender | F (female), M (male) or empty (not specified) | 1 | ||
| Family situation code | Alphanumerical | 38 | * | |
| Number of children | Numerical | Integer | ||
| Team code | Alphanumerical | 38 | * | |
| Identifier | Alphanumerical | 255 | ||
| Grouping | Alphanumerical | 20 | * | |
| Diverse 1 | Alphanumerical | 255 | * | |
| Diverse 2 | Alphanumerical | 255 | * | |
| Diverse 3 | Alphanumerical | 255 | * | |
| Diverse 4 | Alphanumerical | 255 | * | |
| Hiring date | Date | DD/MM/YYYY | ||
| T&A active | Alphanumerical | 1 |
1 if active 0 if not |
|
| Self-planned | Alphanumerical | 1 | 1 if self-planned, 0 if not | |
| Seniority date | Date | DD/MM/YYYY |
Example of content
Olivier;Durant;000141;MKTP0001;29/12/1960;14 rue de Mantes;le Charlebourg;ZI de la gare;bp500;92700;Colombes;France; 0155668989;0610121212;;contact@holydis.com;M;C;3;Equipe A;olivierd;A;;;;;01/10/2018;1
Staff - Contract assignment
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.
Unique file
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
contract.txt.
Example 2: the Label field in the configuration and the import file are both named
contract_Timesquare.001.
Multiple files
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 or LabelAAMMJJ.EXT are the supported wordings in which:
- "Label" is made of a string of alphanumerical characters that can be personalized
- "JJ" stands for the day (DD), "MM" stands for the month, "AA" and "AAAA" stands for the year (YY or YYYY), 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 contract_JJMMAA.txt and the three import files are named contract_040520.txt, contract_050520.txt and contract_060520.txt.
Example 2: the Label field in the configuration is named contractAAAAMMJJ.001 and the three import
files are named contract20200504.001, contract20200505.001 and contract20200506.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 is a semicolon.
Description of the file content
| Field name | Type | Length | Note | Mandatory |
|---|---|---|---|---|
| Employee ID | Alphanumerical | 38 | Yes | |
| Contract code | Alphanumerical | 12 | Yes | |
| Type of contract | Alphanumerical | 38 | * | Yes |
| Contract start date | Date | DD/MM/YYYY | Yes | |
| Contract end date | Date | DD/MM/YYYY | Yes | |
| Annualized contract | Alphanumerical | 1 |
1 if annualized 0 if not |
|
| Contract assignment external code | Alphanumerical | |||
| Contract variation code | Alphanumerical | 12 | ||
| Contract variation start date | Date | DD/MM/YYYY | ||
| Contract variation end date | Date | DD/MM/YYYY | ||
| Annualized Contract variation | Alphanumerical | 1 |
1 if annualized 0 if not |
|
| End of contract termination | Alphanumerical | 1 | 1 if termination, 0 if not | |
| End of contract variation termination | Alphanumerical | 1 | 1 if termination, 0 if not |
* Formats are specified in the Configuration module.
Contracts must have been previously created in Timesquare®.
All fields – including void ones – must be present in the file.
If the import file does not contain all the information, I must define in my configuration what the interface should do: the line is not imported or the line is imported with the first value existing in Timesquare if the missing data are of the drop-down list type (example: contract code, contract type, annualized contract). For example, in the case of an annualized contract, the line would be imported with the value "0" for no.
To add a contract variation, I must enter the information related to the contract associated with the contract variation. I add only one contract variation per person per file. The contract variation start and end dates must be within the associated contract assignment. A contract variation cannot straddle two contract assignment periods. Several contract variations can be assigned to the same contract period. Two contract variations cannot overlap (for a given date, just like the contract assignment, the contract variation is unique).
Example of content
000141;0001;CDI;01/01/2019;31/12/2099;0;SAP01;002;01/08/2023;31/12/2099;0
000156;0001;CDD;01/02/2019;31/03/2009;0;SAP02
000135;0001;CDI;01/02/2019;31/12/2099;0;SAP03
Staff - structure assignment
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.
Unique file
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
structure.txt.
Example 2: the Label field in the configuration and the import file are both named
structure_Timesquare.001.
Multiple files
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 or LabelAAMMJJ.EXT are the supported wordings in which:
- "Label" is made of a string of alphanumerical characters that can be personalized
- "JJ" stands for the day (DD), "MM" stands for the month, "AA" and "AAAA" stands for the year (YY or YYYY), 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 structure_JJMMAA.txt and the three import files are named structure_040520.txt, structure_050520.txt and structure_060520.txt.
Example 2: the Label field in the configuration is named structureAAAAMMJJ.001 and the three import
files are named structure20200504.001, structure20200505.001 and structure20200506.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 is a semicolon.
Description of the file content
| Field name | Type | Length | Note | Mandatory |
|---|---|---|---|---|
| Employee ID | Alphanumerical | 38 | Must be unique | Yes |
| Structure code | Alphanumerical | 40 | Yes | |
| Structure start date | Date | DD/MM/YYYY | Yes | |
| Structure end date | Date | DD/MM/YYYY | Yes |
Example of content
000141;PLA;01/01/2019;31/12/2099
000156;PLB;01/02/2019;31/03/2009
000135;PLC;01/02/2019;31/12/2099
Staff - calendar assignment
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.
Unique file
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
calendar.txt.
Example 2: the Label field in the configuration and the import file are both named
calendar_Timesquare.001.
Multiple files
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 or LabelAAMMJJ.EXT are the supported wordings in which:
- "Label" is made of a string of alphanumerical characters that can be personalized
- "JJ" stands for the day (DD), "MM" stands for the month, "AA" and "AAAA" stands for the year (YY or YYYY), 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 calendar_JJMMAA.txt and the three import files are named calendar_040520.txt, calendar_050520.txt and calendar_060520.txt.
Example 2: the Label field in the configuration is named calendarAAAAMMJJ.001 and the three import
files are named calendar20200504.001, calendar20200505.001 and calendar20200506.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 is a semicolon.
Description of the file content
| Field name | Type | Length | Note | Mandatory |
|---|---|---|---|---|
| Employee ID | Alphanumerical | 38 | Must be unique | Yes |
| Calendar code | Alphanumerical | 38 | Yes | |
| Calendar start date | Date | DD/MM/YYYY | Yes | |
| Calendar end date | Date | DD/MM/YYYY | Yes |
Example of content
000141;Fra;01/01/2019;31/12/2099
000156;Fra;01/02/2019;31/03/2009
000135;Als;01/02/2019;31/12/2099
Staff - badges assignment
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.
Unique file
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
badges.txt.
Example 2: the Label field in the configuration and the import file are both named
badges_Timesquare.001.
Multiple files
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 or LabelAAMMJJ.EXT are the supported wordings in which:
- "Label" is made of a string of alphanumerical characters that can be personalized
- "JJ" stands for the day (DD), "MM" stands for the month, "AA" and "AAAA" stands for the year (YY or YYYY), 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 badges_JJMMAA.txt and the three import files are named badges_040520.txt, badges_050520.txt and badges_060520.txt.
Example 2: the Label field in the configuration is named badgesAAAAMMJJ.001 and the three import
files are named badges20200504.001, badges20200505.001 and badges20200506.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 is a semicolon.
Description of the file content
| Field name | Type | Length | Note | Mandatory |
|---|---|---|---|---|
| Employee ID | Alphanumerical | 38 | Must be unique | Yes |
| Badge code | Alphanumerical | 20 | Yes | |
| Badge start date | Date | DD/MM/YYYY | Yes | |
| Badge end date | Date | DD/MM/YYYY | Yes |
All fields – including void ones – must be present in the file.
If the import file does not contain all the information, I must define in my configuration what the interface should do: the line is not imported or the line is imported with the first value existing in Timesquare if the missing data are of the drop-down list type (example: badge code).
Example of content
AIN01;0000000000001;23/09/2020;31/12/2099
AISNE02;0000000000002;21/09/2020;31/12/2099
ALLIER03;0000000000003;01/09/2020;30/09/2020
Staff - qualification/level assignment
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.
Unique file
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
badges.txt.
Example 2: the Label field in the configuration and the import file are both named
badges_Timesquare.001.
Multiple files
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 or LabelAAMMJJ.EXT are the supported wordings in which:
- "Label" is made of a string of alphanumerical characters that can be personalized
- "JJ" stands for the day (DD), "MM" stands for the month, "AA" and "AAAA" stands for the year (YY or YYYY), 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 badges_JJMMAA.txt and the three import files are named qualif_040520.txt, qualif_050520.txt and qualif_060520.txt.
Example 2: the Label field in the configuration is named badgesAAAAMMJJ.001 and the three import
files are named qualif20200504.001, qualif20200505.001 and qualif20200506.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 is a semicolon.
Description of the file content
| Field name | Type | Length | Note | Mandatory |
|---|---|---|---|---|
| Employee ID | Alphanumerical | 38 | Must be unique | Yes |
| Qualification code | Alphanumerical | 38 | Yes | |
| Level code | Alphanumerical | 38 | ||
| Individual rate | Numerical | Empty or positive or zero real value | ||
| Qualification/level assignment start date | Date | DD/MM/YYYY | Yes | |
| Qualification/level assignment end date | Date | DD/MM/YYYY | Yes |
All fields – including void ones – must be present in the file.
If the import file does not contain all the information, I must define in my configuration what the interface should do: the line is not imported or the line is imported with the first value existing in Timesquare if the missing data are of the drop-down list type (example: qualification code).
Example of content
AIN01;QUALIF1;ECHELON1;;01/01/2022/31/12/2099
AISNE02;QUALIF2;ECHELON2;;01/01/2022/31/12/2099
ALLIER03;QUALIF3;ECHELON1;;01/01/2022/31/12/2099
Comments
0 comments
Please sign in to leave a comment.