Advanced employee synchronization

Introduction

Advanced employee synchronization is designed to provide finer control over employee management in UKG HR Service Delivery, particularly for complex HRIS landscapes where employees may have multiple identifiers, belong to multiple organizations, or require advanced status tracking. This mode complements the standard employee synchronization process by allowing advanced handling of edge cases and offering additional optional attributes.

Use cases

• Multiple employee numbers: Some employees may have multiple references in different organizational units; advanced synchronization allows linking them coherently.
• Former employees: Manage departure dates more precisely, including future-dated departures.
• SAML integration: Configure SAML tokens during synchronization for single sign-on.
• Custom field enrichment: Enrich profiles with extended employee attributes, usable in access control and automation.

Import file

Format

Like standard synchronization, advanced synchronization uses a UTF‑8 encoded CSV file, which can be uploaded via the admin interface or SFTP. It supports both incremental and complete imports.

• Incremental: Processes only new or changed employees.
• Complete: Refreshes all employees, updating differences.

Structure

The file must start with all mandatory columns, followed by optional columns, and finally any custom fields configured for your tenant.

Mandatory attributes include:

• organization_code
• registration_reference
• lastname, firstname
• At least one contact field (professional_email, or postal address if email unavailable)

Advanced attributes include:

• technical_id — Unique technical identifier for mapping to external HRIS.
• departure_date — Supports precise or future departure dates.
• saml_token — Used for SAML-based single sign-on.
• disable_vault — To prevent vault creation for specific employees.
• disable_distribution — To suppress delivery of certain documents (paper, electronic, or both).

Custom fields can extend the schema as needed; each must match a configured code in your environment.

Example (simplified)

organization_code;registration_reference;technical_id;lastname;firstname;professional_email;saml_token;departure_date
ORG001;12345;A123;DOE;JOHN;[email protected];jd123token;2025-12-31

Advanced behaviors

Multiple registrations

Employees can be linked across multiple organizations using different registration_reference values. UKG HR Service Delivery reconciles them into a single employee profile as long as they share the same technical_id.

Departure dates

If departure_date is set to a future date, the employee remains active until that date, after which the status switches to former employee. If the value is non-date (e.g., X), the employee is immediately marked as a former employee as of the import date.

SAML token handling

The saml_token column links employees to their SAML identifier.

• If present and populated: the SAML ID is set/updated.
• If present but empty: the token is not cleared (must be removed via API if needed).

Vault and distribution options

• disable_vault: blocks creation of an employee’s vault (no invitations).
• disable_distribution: prevents document delivery according to flag (X, P, or E).

Report file

Each advanced employee import generates a report in XML, stored in the out/sal SFTP directory.

Report elements:

• JOB_REFERENCE — Identifier of the job.
• JOB_REPORT_TIMESTAMP — Time of report generation.
• JOB_DESCRIPTION — Import job description.
• JOB_TYPE — Always sal for employee imports.
• COUNT_ROWS — Number of processed lines.
• MESSAGE elements with:
  • ENTITY_ID (employee reference)
  • RESULT_CODE (0 = created, 1 = updated, other = error)
  • RESULT_MESSAGE (success or error description)

Example (excerpt)

<EMPLOYEE_REPORT version="1.0">
  <JOB_REFERENCE>cmpABC123.csv</JOB_REFERENCE>
  <JOB_REPORT_TIMESTAMP>2025-01-10T14:20:00+00:00</JOB_REPORT_TIMESTAMP>
  <JOB_DESCRIPTION>Advanced Employees import</JOB_DESCRIPTION>
  <JOB_TYPE>sal</JOB_TYPE>
  <COUNT_ROWS>2</COUNT_ROWS>
  <MESSAGE ENTITY_NAME="Advanced Sync">
    <ENTITY_ID>12345</ENTITY_ID>
    <ENTITY_TYPE>Employee</ENTITY_TYPE>
    <RESULT_CODE>0</RESULT_CODE>
    <RESULT_MESSAGE>Employee JOHN DOE Created</RESULT_MESSAGE>
  </MESSAGE>
</EMPLOYEE_REPORT>

Best practices

• Always include technical_id to ensure stable identity mapping across systems.
• Use incremental imports for day-to-day operations; reserve complete imports for clean refreshes.
• Use saml_token consistently for employees requiring SSO.
• Keep departure_date aligned with HRIS offboarding processes to ensure compliance.