Employee synchronization¶

Description¶

In order to create a profile, an employee folder, and any personal vaults for employees of the company, they must be registered. The purpose of this registration is to provide a unique identifier for the employee, define their contact data (particularly e-mail and postal address), and to associate them with one or more organizations (predefined during the synchronization of the organizations: see Organization synchronization ). This registration is also used to define the employee number or numbers of each employee to provide unique employee identifiers on UKG HR Service Delivery.

../../_images/organisation-tree-with-employee.png

Import file¶

Format¶

The synchronization of the employee directory is done through the import of a UTF-8-encoded CSV file. This import may be done manually through the administration web interface, or automatically using SFTP.

In the transfer is done via SFTP, the file must be uploaded to the in/sal directory.

Employee import can be defined as:

incremental: Only new and updated employees are in the CSV file. New employees are created. Existing employees mentioned in the file are updated with its content. Existing employees not in the file are left unchanged.

or complete: All employees are in the CSV file. New employees are created. Existing employees are updated with its content only if changes are detected.

Employee synchronization should be done regularly to keep the directory up to date. Employees can also be added manually anytime from UKG HR Service Delivery interface.

Note

Text type values can be single quoted ' if you need to declare the delimeter char ; in your text. It is also important to escape apostrophes if your text contains such characters. For example the text John's ID becomes 'John''s ID'

Structure¶

The first row of the CSV file must comply with the following rules:

Mandatory attributes: Can be named as you wish, but must be present and in the order described in the present documentation. Their values, however, can be optional (see the description for each mandatory attribute below). The CSV file for Employee import must contain 41 mandatory attributes.
The first row can therefore look like this:
1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24;25;26;27;28;29;30;31;32;33;34;35;36;37;38;39;40;41
Optional attribute: Has to follow the mandatory attributes, its presence is optional, and its name must be as described in the present documentation. The first row can therefore look like this:
1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24;25;26;27;28;29;30;31;32;33;34;35;36;37;38;39;40;41;saml_token
Custom fields: Have to follow the optional attribute if it is present, and their names must be as described in the present documentation. Their presence in the employee import file is mandatory, their order does not matter. For two custom fields defined, the first row can therefore look like this:
1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24;25;26;27;28;29;30;31;32;33;34;35;36;37;38;39;40;41;saml_token;contract-type;department
Or like this:
1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24;25;26;27;28;29;30;31;32;33;34;35;36;37;38;39;40;41;department;contract-type

Mandatory attributes¶

organization_code: VARCHAR(64) / mandatory value

Code of the organization with which the employee number is associated
registration_reference: VARCHAR(255) / mandatory value

Employee number within the organization
technical_id: VARCHAR(50) / optional value

Technical identifier corresponding to the employee’s unique identifier in the IS of the Client

It is recommended to specify a unique employee identifier if such an identifier exists in the HRIS. This identifier is not (typically) the employee number. But if it is absolutely certain, even in the case of a transfer or in the case of a departure followed by a reassignment, that this identifier is unique, this identifier may then be used as the employee number. If no unique employee identifier exists in the HRIS, leave the value empty for each row.
lastname: VARCHAR(70) / mandatory value

Last name of the employee
maiden_name (optional): VARCHAR(70) / optional value

Employee maiden name
firstname: VARCHAR(30) / mandatory value

First name of the employee
professional_email: VARCHAR(80) / optional value

Professional e-mail of the employee

If your company intends to use our electronic vault feature, the email is used to send the personal vault activation codes to employees and is strongly recommended. If not provided and if your company still wants to use our electronic vault feature, the same invitation can be sent by mail (see address1, city, zip_code and country fields below). Note: We do not currently support email addresses containing non-ASCII characters (RFC 6532 - Internationalized Email Headers).
mark_inactive_former_registration_references: VARCHAR(1) / optional value

The registration reference previously set for the employee is the only active one.

The former registration references if any are marked as inactive and the departure date of the employee from those organizations is the date of the import. This behaviour is applied as soon as a character is entered into this field (e.g.: ‘X’). Note that a space is not considered as a character.
leave_empty_1: deprecated

This field is no longer used, leave blank
dob: YYYY-MM-DD / optional value

Date of birth of the employee

Duplication checks are performed on this field. It is therefore recommended to fill it in
address1: VARCHAR(255) / optional value

The employee address, “No. and street”

If your company intends to use our electronic vault feature, this information is required if the field professional_email is not filled
address2: VARCHAR(255) / optional value

Additional address (Floor, Stairwell, Appartment…)
address3: VARCHAR(255) / optional value

Additional address fields (Residence, Housing Development, Building, Apartment Building, Subdivision, etc.)
zip_code: VARCHAR(30) / optional value

Postal code

If your company intends to use our electronic vault feature, this information is required if the field professional_email is not filled
city: VARCHAR(100) / optional value

City where the employee resides

If your company intends to use our electronic vault feature, this information is required if the field professional_email is not filled
country: VARCHAR(2) / optional value

ISO 3166-1 alpha-2 country code (FR, EN, ES…)

If your company intends to use our electronic vault feature, this information is required if the field professional_email is not filled. If country is set to US or CA, then the state field is mandatory.
phone_number: VARCHAR(50) / optional value

Phone number of the employee. Format using International prefix format; e.g. 0018005550111.
mobile_phone_number: VARCHAR(50) / optional value

Mobile phone number of the employee. Format using International prefix format; e.g. 0018005550123.

Used for signature operations (number used by default, and used if no other number is specified in the Web Service calls)
middle_name: VARCHAR(70) / optional value

Employee middle name
legal_firstname: VARCHAR(70) / mandatory value if activated

Employee legal first name.

This attribute is only used if the setting Preferred and Legal first name is activated and is ignored otherwise. If the setting is activated, any data received as a value is taken into account, even an empty value: if an empty value is given, the legal_firstname for the employee is cleared.
disable_vault: VARCHAR(1) / optional value

Disable the vault for the employee

Employee’s vault is considered as disabled as soon as a character is entered into this field (e.g.: ‘X’). Note that a space is not considered as a character. If the vault is disabled, the employee doesn’t receive any invitations and is not able to open a vault either.
state: VARCHAR(2) / mandatory value for US and Canada, not available for other countries

ISO 3166-2 alpha-2 subdivision code for Canada or US (AL, AK, AZ, ON…)
language: VARCHAR / optional value

Language used by the employee

Language code (2-3 chars) with locale variant (2+ chars) as per [IETF BCP 47](https://tools.ietf.org/html/bcp47), separated by a hyphen (-), e.g.: en-us. Using 2 characters language codes (ex: fr, en) is still supported but deprecated.

-Supported languages (all products): en-us, en-gb, fr-fr, fr-ca, de-de, pl-pl, zh-hans, zh-hant, cs-cz, da-dk, nl-nl, fi-fi, el-gr, hu-hu, it-it, ja-jp, nb-no, pt-pt, pt-br, ro-ro, ru-ru, sr-rs, sk-sk, sl-si, es-es, es-419, sv-se, tr-tr, vi-vn

-Additionally supported for the employee side of Document Manager (Employee Folder) and the employee’s vault: ar-001, bg-bg, he-il, ko-kr, th-th, uk-ua

-Additionally supported for the employee’s vault: ms-my

-Deprecated and not supported languages: sr, sr-sr

Only a subset of the languages supported by UKG HR Service Delivery might be available on the platform depending on its configuration.
starting_date: YYYY-MM-DD / optional value

Starting date of the employee in your company
opt_out_from_electronic_payslips: VARCHAR(1) / optional value

If the value in this field is set to Y, the choice of the employee to opt-out from receiving payslips electronically is recorded. As a result UKG HR Service Delivery no longer sends digital payslips to this employee. On the other hand, if this field contains N, we consider that the employee did choose to not opt out (or canceled his former decision to opt out) from receiving payslips electronically. If any other value is set, it is ignored.
leave_empty_3: deprecated

This field is no longer used, leave blank
leave_empty_4: deprecated

This field is no longer used, leave blank
leave_empty_5: deprecated

This field is no longer used, leave blank
leave_empty_6: deprecated

This field is no longer used, leave blank
leave_empty_7: deprecated

This field is no longer used, leave blank
leave_empty_8: deprecated

This field is no longer used; leave blank
leave_empty_9: deprecated

This field is no longer used, leave blank
leave_empty_10: deprecated

This field is no longer used, leave blank
leave_empty_11: deprecated

This field is no longer used, leave blank
leave_empty_12: deprecated

This field is no longer used, leave blank
leave_empty_13: deprecated

This field is no longer used, leave blank
leave_empty_14: deprecated

This field is no longer used, leave blank
leave_empty_15: deprecated

This field is no longer used, leave blank
leave_empty_16: deprecated

This field is no longer used; leave blank
disable_distribution: VARCHAR(1) / optional value
Prevent documents to be sent to the employee (whatever the employee’s choice, their electonic vault status and the distribution rules settings)

Only applies to distributions (not mass mailing). Can be one of:
- X: Neither paper nor electronic copies are sent to the employee
- E: Electronic documents are not distributed to the employee’s electronic vault
- P: Paper documents are not sent to the employee
departure_date: YYYY-MM-DD or boolean / optional value

Used to report the employee’s departure date

When any other character than a date is entered, the employee is considered as a former employee of the organization starting on the date of the import. Note that a space is not considered as a character. If the date entered is in the future, the employee is also considered as a former employee on the date of the import.

Optional attribute¶

To use the SAMLv2 authentication method, you need to provide a saml authentication identifier for each employee. This identifier should be inserted as the value for the attribute saml_token to be transfered in the SAML Assertion by your Idendity Provider during the authentication phase.

See Single sign-on with SAMLv2 for more information on the SAML authentication method.

Warning

If this attribute is present but the value is empty, it is ignored: the value of the SAML token for the employee is not removed. To remove a SAML token from an employee, you can use our APIs. See UKG HR Service Delivery REST API - Employees endpoints.

Custom fields¶

Custom fields may be defined for employees. These are defined during the platform setup phase and must then be added to the import file. The file must therefore contain as many additional attributes as custom fields.

Warning

The name must be the attribute code
For each row (i.e. each employee), the corresponding values of the attributes must be filled

Note

These attributes can be used as “filters”: In which case roles define access restrictions based on those attributes.

For example: Contract type (code = contract_type), possible values = [Permanent / Fixed-term / Part-time / Freelance / Casual]. The role ‘’HR Assistant’’ could have access to all employees directory except the ones that have a contract of type: Freelance.

Note: The following types of attributes are available:

integer (whole numbers)
boolean (‘X’ or empty)
list (choice among a list of available values)
character string (free format)

Example of a complete CSV file¶

'Org code';'Employee number';'Tech ID';'Last name';'Maiden name';'First name';'professional email';'Former ref inactive';'Leave empty';'Date of birth';'Address 1';'Address 2';'Address 3';'ZIP code';'City';'Country code';'Phone';'Cell phone';'Middle name';'Legal first name';'Disable vault';'State US and CA';'Language';'Start date';'Opt out from e-payslips';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Leave empty';'Disable distributions';'Gone'
'FSUD1';2150002;;'ADAM';;'PHILIP';;;;;'900 Chelmsford St';'Suite 101';;01851;'LOWELL';'US';;;;;;;;;;;;;;;;;;;;;;;;;
'FSUD2';2150009;;'LEROY';;'JEFF';;;;;'2000 Ultimate Way';;;33326;'WESTON';'US';;;;;;;;;;;;;;;;;;;;;;;;;
'FSUD1';'2150309';;'ADAM';;'AMY';;;;;'900 Chelmsford St';'Suite 101';;01851;'LOWELL';'US';;;;;;;;;;;;;;;;;;;;;;;;;

Download a sample employee import file

Warning

You have to modify the sample values before you import this file on your platform.

Report file¶

Format¶

The report file is produced in XML format. The fields are the following:

JOB_REFERENCE: Internal processing reference, corresponding to the name of the import file renamed on UKG HR Service Delivery.
JOB_REPORT_TIMESTAMP: Date in ISO format (YYYY-MM-DDThh:mm:ss±hh:mm) on which the report was generated.
JOB_DESCRIPTION: Import title
JOB_TYPE: sal for the employee import report
COUNT_ROWS: Number of total lines processed
MESSAGE: Feedback corresponding to one line
- ENTITY_ID: UKG HR Service Delivery identifier of the created employee
- ENTITY_TYPE: “Employee” in this report
- RESULT_CODE: 0 (employee created), 1 (employee updated), != 1 (error)
- RESULT_MESSAGE: Message describing the action performed or the error encountered. When it is an error, the line number is present at the beginning of the error message.

Example¶

<EMPLOYEE_REPORT version="1.0">
    <JOB_REFERENCE>cmpx0pfLB.csv</JOB_REFERENCE>
    <JOB_REPORT_TIMESTAMP>2021-03-19T13:05:50.648461+00:00</JOB_REPORT_TIMESTAMP>
    <JOB_DESCRIPTION>Employees import DEMO</JOB_DESCRIPTION>
    <JOB_TYPE>sal</JOB_TYPE>
    <COUNT_ROWS>3</COUNT_ROWS>
    <MESSAGE ENTITY_NAME="Novapost Ref">
        <ENTITY_ID>193930</ENTITY_ID>
        <ENTITY_TYPE>Employee</ENTITY_TYPE>
        <RESULT_CODE>0</RESULT_CODE>
        <RESULT_MESSAGE>Employee Cyrille CHAPELLE Created</RESULT_MESSAGE>
    </MESSAGE>
    <MESSAGE ENTITY_NAME="Novapost Ref">
        <ENTITY_ID>pk:193930 Cyrille CHAPELLE</ENTITY_ID>
        <ENTITY_TYPE>Employee</ENTITY_TYPE>
        <RESULT_CODE>1</RESULT_CODE>
        <RESULT_MESSAGE>Employee Updated</RESULT_MESSAGE>
    </MESSAGE>
    <MESSAGE ENTITY_NAME="Novapost Ref">
        <ENTITY_ID>pk:193930 Cyrille CHAPELLE</ENTITY_ID>
        <ENTITY_TYPE>Employee</ENTITY_TYPE>
        <RESULT_CODE>1</RESULT_CODE>
        <RESULT_MESSAGE>Employee Updated</RESULT_MESSAGE>
    </MESSAGE>
</EMPLOYEE_REPORT>

Registration report¶

Warning

The following report is not available by default in the application. It can, however, as an option and from a specific setting be made available regularly. If you need this report please contact your Project Manager or Customer Success Manager at UKG HR Service Delivery.

The content of this file is an export of all of the employees registered on UKG HR Service Delivery, specifying for each employee if they have selected the paperless option from their employee vault for a given document type (for example, payslip).

Format¶

This file is in XML format and contains the following information:

client_code: mandatory

Client domain. For example: acme.safe-access.com
client_document_type_code: mandatory

Document type code. The choice of the employees to receive their documents digitally or by mail applies to this document type only. For example: payslip (this value is defined during the setup)
client_name: mandatory

Name of the client as displayed in UKG HR Service Delivery
date_start: mandatory

If specified, only the registrations recorded after this date are added to the report. Format: ISO format. Example: 2017-02-04T14:53:14.277464+00:00
date_end: mandatory

Only the registrations that were recorded before this date are returned in the report. Format: ISO format. Example: 2017-02-04T14:53:14.277464+00:00
demat_subscriptions_count: mandatory

Number of employees who have chosen the paperless option for this type of document by opening their electronic vault and choosing digital. If the type of document is marked as a payslip, it includes the employees who opted in in to receive their payslips digitally
paper_subscriptions_count: mandatory

Number of employees who have chosen the paper format for this type of document by opening their electronic vault and choosing paper. If the type of document is marked as a payslip, it includes the employees who opted out to receive their payslips digitally
undecided_subscriptions_count: mandatory

Number of employees who have not yet made a choice regarding the format in which they want to receive this type of document
subscription: details of a registration
- user_node: Information regarding the Employee
  first_name: mandatory
  
  Firstname of the Employee
  
  last_name: mandatory
  
  Lastname of the Employee
  
  technical_id: optional
  
  External ID of the Employee, if provided
  
  registration_references: List of the employee’s employee numbers and organizations
  
  registration_reference:
  
  organization_code: mandatory
  
  The code of the organization with which the Employee is associated, via the associated employee number
  
  registration_number: mandatory
  
  Employee number of the employee associated with this Organization
- is_demat: mandatory
  Employee registration status. Possible values:
  
  1 => The Employee has chosen the paperless option for this type of document,
  
  0 => The Employee has chosen the paper format for this type of document
  
  (empty) => The employee has not yet chosen (includes the employees who have not yet opened their vault)
- modification_date: optional
  
  Date of the employee choice (if a choice has been made). Format: ISO format. Example: 2017-02-04T14:53:14.277464+00:00
electronic_payslips_choice: provides additional information regarding the choice of the Employee to receive their payslip digitally. Despite the document type may not refered to a payslip, this information is returned for every document type. A change introduced in March 2017 in our product added a new option for the Employee to opt in or opt out to the digital payslip. If an employee opens their electronic vault after this date, their choice are set to “opt int” and the employees receive their payslips digitally. For employees who opened their electronic vault before the update, the employees aren’t considered as “opt in” even though the employees chose to receive their payslips digitally at the time. However in both cases, after the update, if an employee makes a choice from their electronic vault (choosing digital or paper), the employee either “opts in” or “opts out” and the is_demat value for the registration updated
- opt_out_from_electronic_payslips: can be one of:
  1 => the Employee chose to not receive their payslips digitally, the Employee opted out
  
  0 => the Employee did not communicate their choice for receiving their payslips digitally or the Employee accepted to receive their payslips digitally, the Employee opted in
- opt_out_updated_at: if the Employee opted in or opted out, date of the last update regarding the choice of the Employee
- opt_out_origin: origin of the Employee choice if the Employee opted in or out. Can be one of:
  mypeopledoc: the Employee did their choice from their electronic vault
  
  peopledoc: the choice has been made for the Employee in UKG HR Service Delivery

Example:¶

<subscriptions_report version="1.2">
  <client_code>acme.people-doc.fr</client_code>
  <client_document_type_code>bulsal</client_document_type_code>
  <client_name>Acme</client_name>
  <date_start/>
  <date_end>2017-01-04T14:53:14.277464+00:00</date_end>
  <demat_subscriptions_count>1</demat_subscriptions_count>
  <paper_subscriptions_count>117</paper_subscriptions_count>
  <undecided_subscriptions_count>0</undecided_subscriptions_count>
  <subscription>
    <user_node>
      <first_name>jean</first_name>
      <last_name>martin</last_name>
      <technical_id>TH123456789</technical_id>
      <registration_references>
        <registration_reference>
          <organisation_code>ORG1234</organisation_code>
          <registration_number>MAT12341234</registration_number>
        </registration_reference>
      </registration_references>
    </user_node>
    <is_demat>1</is_demat>
    <modification_date></modification_date>
            <electronic_payslips_choice>
                    <opt_out_from_electronic_payslips>0</opt_out_from_electronic_payslips>
                    <opt_out_origin>mypeopledoc</opt_out_origin>
                    <opt_out_updated_at>2017-02-10T16:28:42.949148+00:00</opt_out_updated_at>
            </electronic_payslips_choice>
  </subscription>
  <subscription>
    <user_node>
      <first_name>cedric</first_name>
      <last_name>dupont</last_name>
      <technical_id></technical_id>
      <registration_references>
        <registration_reference>
          <organisation_code>ORG4321</organisation_code>
          <registration_number>MAT43214321</registration_number>
        </registration_reference>
      </registration_references>
    </user_node>
    <is_demat>0</is_demat>
    <modification_date></modification_date>
            <electronic_payslips_choice>
                    <opt_out_from_electronic_payslips>1</opt_out_from_electronic_payslips>
                    <opt_out_origin>
                    <opt_out_updated_at />
            <electronic_payslips_choice>
  </subscription>
</subscriptions_report>

Download a sample registration report file