Exchange protocol via SFTP file transfer

This section describes the data exchanges between UKG HR Service Delivery and the Information System (IS) client in terms of protocols, procedures, and naming conventions. All CSV files transmitted as part of data synchronization must respect this protocol.

Exchange protocol

The protocol used for file exchanges is SFTP (SSH File Transfer Protocol) using SSH-2. Sessions must be established from the client to UKG HR Service Delivery for both sending and receiving data. The company uses a single SFTP account for identification, authenticated with an encryption key provided by the company.

SFTP server address

UKG HR Service Delivery provides different SFTP servers based on hosting location:

European Platform

Clients on the European platform use separate staging and production servers:

• Servers: sftp.staging.eu.people-doc.com, sftp-9d87a130f70b.eu.people-doc.com
• Port: 9030
• Ingress IPs: 34.32.159.211, 35.204.166.142
• Host keys:
  • ED25519, RSA-SHA2-512, RSA-SHA2-256, RSA — with corresponding fingerprints (SHA256, MD5)
• PGP Encryption Public Keys: staging and production versions
• Egress IPs: 34.32.164.235, 34.141.192.120
• Egress public keys: staging and production versions

United States Platform

Clients on the US platform use similar staging and production servers:

• Servers: sftp.staging.us.people-doc.com, sftp.us.people-doc.com
• Port: 9030
• Ingress IPs: 35.196.72.40, 35.237.171.21
• Host keys: ED25519, RSA-SHA2-512, RSA-SHA2-256, RSA — with fingerprints
• PGP Encryption Public Keys: staging and production versions
• Egress IPs: 34.148.105.170, 34.139.96.192
• Egress public keys: same as above

UKG Pro and Ready Suite Platforms

Clients on these platforms may connect to Atlanta or Toronto servers:

• Servers: sftp-a5g0wchkaeb5.hrsd.ultipro.com, sftp-h2ohy6ogo7ew.hrsd.ultipro.ca
• Port: 9030
• Ingress IPs: 34.74.120.53, 34.47.29.153
• Host keys: ED25519, RSA-SHA2-512, RSA-SHA2-256, RSA — with fingerprints
• PGP Encryption Public Keys: corresponding production versions
• Egress IPs: 34.148.105.170, 34.139.96.192, 35.203.90.233, 35.203.17.129

SFTP account

Authorization (Firewall filtering)

• Ensure outbound connections to the SFTP server’s port are permitted.
• Provide UKG with your public IP addresses (up to 254) to whitelist.
• Network recommendation: Use a unique IP address for the connection to UKG; suspicious activity may lead to IP bans.

Authentication (SSH key access)

• Preferred method: Public SSH keys (default; modern and secure).
• Deprecated: Password-based access—only for fallback when SSH keys are not possible (deprecated since 2022).

SSH key specifications

Accepted key types, formats, and minimum sizes:

SSH key best practices

• Add a comment to differentiate keys for easier revocation.

• Secure keys with a passphrase.

• Never share your private key—UKG will only request public keys.

• Compatible SFTP software includes (but is not limited to):

  • OpenSSH ≥ 6.6
  • FileZilla ≥ 3.13.0
  • AsyncSSH ≥ 1.18
  • J2SSH Maverick ≥ 1.7.14
  • libssh ≥ 0.9.1
  • Paramiko ≥ 2.5.0
  • SSHJ ≥ 0.27.0
  • WinSCP ≥ 5.9.4

SFTP Security

Supported Algorithms

• Key exchange: [email protected], curve25519-sha256, diffie-hellman-group18-sha512, diffie-hellman-group16-sha512, diffie-hellman-group14-sha256, diffie-hellman-group-exchange-sha256
• Host key algorithms: [email protected], rsa-sha2-512, rsa-sha2-256, [email protected], [email protected], [email protected], ssh-ed25519, ssh-rsa
• Ciphers: [email protected], aes256-ctr, aes128-ctr, [email protected], [email protected]
• MACs: [email protected], [email protected], hmac-sha2-512, hmac-sha2-256
• Compression: none, [email protected]
• Modulus size: 2048 bits or greater

Details of the algorithms

Kex Algorithms

Server Host Key Algorithms

Encryption Algorithms (Ciphers)

MAC Algorithms

Compression Algorithms

Moduli File

SFTP retention

• Inactive SFTP accounts or firewall rules are disabled after 12 months; reactivation is possible for an additional 6 months.

• Key validity:

  • RSA keys (3072–4095 bits): valid for 2 years
  • RSA key ≥ 4096 bits or ED25519: valid for 5 years

• Customer data - documents (storage retention):

  • Subscription reports: 15 days
  • Other reports: 90 days
  • Processed files: retained 45 days, then deleted
  • Unprocessed files: deleted 90 days after date of creation

File deposit and withdrawal

Folder tree

The company has input/output directories on the UKG HR Service Delivery server by document type and by data type.

• The input directory (in) and the output directory (out) are symmetrical.
  • The documents sent by the IS client are deposited in the in directory.
  • The processing reports associated with the input files are made available in the out directory (error report).
• Some other specific purpose directories are not symmetrical.

Warning: Report files related to data synchronization and document distribution.
The provision of these reports is optional and must be planned during the project phase.

Warning: If the client’s tool does not automatically create a file with a “.filepart” suffix during its transfer, the client company must include the “.filepart” suffix when writing the file, which must be subsequently removed at the end of the transfer.
This step is necessary to prevent UKG HR Service Delivery from processing a file that is being sent or has failed to be sent before the transfer is complete.

UKG is responsible for the destruction or archiving of files after processing.

UKG HR Service Delivery uses the same mechanism (See .filepart above) to prevent the client company from retrieving a file in the process of being created.
The company is responsible for destroying the files after recovery; otherwise, UKG HR Service Delivery destroys them automatically after three months.

Customer agrees to deposit these files with at least file permissions 640 (rw-r—–).

Default directories for each SFTP account¶

SFTP Directory Structure

Directories Usage

Input File Directory

Output File Directory

Other Directories

Other Directories

Proof of safe receipt (optional)

For each file sent to UKG HR Service Delivery server via SFTP, the system generates a proof of receipt containing the hash of the received file.

This proof is stored in the folder out/tra.

The generated file complies with the following naming convention:

cdmat_{client}_tra_{flux}_{timestamp}.xml

With:

• client: unique client identifier (the partner is not repeated in this name)
• flux: type of file received corresponding to the proof of receipt:
  • dis: batched distribution files (payslip, etc.)
  • usr: document management user (user updates)
  • usa: People Assist user (user updates)
  • sal: employee (employee updates)
  • ins: registration status
  • sir: company updates
  • bil: billing report
  • dse: data sets
• timestamp: timestamp corresponding to the creation of the proof

And the content of the file is as follows:

    <?xml version='1.0' encoding='utf-8'?>
    <transfert_report version="1">
      <file>
        <file_name>ndmat_198538752_2011091610440841_sal_rhw_930_20130206113837.csv</file_name>
        <file_timestamp>2013-01-16T14:20:00+01:00</file_timestamp>
        <file_fingerprint algorithm="SHA1">9849a4d500126203a099aca0cd7017cb8748fb2a</file_fingerprint>
        <file_size>238</file_size>
      </file>
    </transfert_report>

With:

• file_name: Name of the received file corresponding to the proof
• file_timestamp: Date when the proof was generated
• file_fingerprint: Hash of the received file
• file_size: Size of the received file in bytes

File naming conventions

The naming format of the uploaded files is as follows:

{dest}_{partner}_{client}_{flux}_{appemet}_{version}_{timestamp}.{extension}
or {dest}_{client}_{client}_{flux}_{appemet}_{version}_{timestamp}.{extension}
or {dest}_{client}_{client}_{flux}_{timestamp}.{extension}

With:

• dest:
  • ndmat: from the IS client to UKG HR Service Delivery
  • cdmat: from UKG HR Service Delivery to the IS client
• partner/client: partner identifier for indirect clients; for direct clients, user the client identifier in both slots
• flux: type of file; can be:
  • dis: distribution files (payslips, etc.)
  • usr: document management user updates
  • usa: People Assist user updates
  • sal: employee updates
  • ins: registration status
  • sir: company updates
  • bil: billing report
  • dse: data sets
• appemet (optional): sending application name or dataset code (used when multiple applications communicate)
  • From client: application name (e.g., SAP)
  • From UKG: UKG application name (e.g., ndmat)
  • For data set synchronization, this passes the dataset code used in the UKG administration interface
• version (optional): application version; use tst for test files in acceptance environments
• timestamp: creation timestamp in yymmddhhmmss format
• extension: one of zip, pdf, csv, xml, sig
  • Note: sig is the signature file for each report generated by UKG HR Service Delivery

Example: For a direct client macrosoft using an HRIS named hrmanager with version v6 and flux=sal, the file would be named:

ndmat_macrosoft_macrosoft_sal_hrmanager_v6_15486131891569.csv