[RPA005] Batch of employee documents

What is it?

Documents ingestion is the process of uploading employee documents in mass onto the UKG HR Service Delivery Document Manager Core module (also known as employee folder).

It takes as input a ZIP file with documents and a descriptive CSV file, uploaded onto a HRSD SFTP server. Once processed and ingested, the files are discarded as described in Customer data - Documents.

The following diagram presents a high-level view of this standard configuration:

Workflow for RPA005


For what purpose?

This approach is recommended when you need to upload more than 1,000 employee documents to the UKG HR Service Delivery platform.

  • Historical ingestion of employee documents

  • Daily employee document import sent by a scanning partner

Warning

The expiration date feature is not handled by UKG HR Service Delivery API endpoints yet. It is therefore not possible to set up an orchestration including expiration dates.

Alternative approaches

You can also use:

Prerequisites

In order to get ready for mass ingestion, you need:

  • The technical IDs of the employees (if you want to assign the documents based on this data)

  • The registration reference of the employees + the organization code to which it is linked to (if you want to assign the documents based on this data, instead of the technical ID)

  • An account on an SFTP server hosted by UKG HR Service Delivery

  • An SFTP client (for example, FileZilla)

  • To contact our Team beforehand

On the SFTP server, use the following directories:

  • Deposit: in/rpa/emp

  • Report: out/rpa

We do not expect specific naming convention in this deposit directory but, as a good practice you can follow our recommendations described in File naming conventions.

Note

If you already have an SFTP account with UKG HR Service Delivery, and start uploading ZIP files, the documents will not be processed. The orchestration must be set up first.

Mass ingestion conventions

ZIP file structure

For document mass ingestion, you need to provide one or several ZIP files, each containing the documents to be ingested and a CSV file to map the documents to the right employees and attach metadata.

ndmat_acme_acme_emp_202108161212.zip
  metadata.csv
  file1.pdf
  file2.pdf
  file3.pdf
  file3.pdf
  file4.docx
  file5.pdf
  file6.jpeg
  file7.png
  file8.pdf

ZIP file format

  • Maximum file size: 250 MB

  • Maximum upload limit per day: 10 GB

  • Maximum upload limit per hour: 1 GB

  • Maximum content: 2,000 documents (2,000 lines in the CSV file)

  • UTF-8 encoding (no special characters in the file names)

Warning

Uploading more than 10 GB on one day can cause a backlog which can lead to time out errors. It goes the same for the 1 GB hour limitation.

CSV file format

  • .csv file extension (whatever the name of this file)

  • At the root of the ZIP file

  • UTF-8 encoding

  • Header line (data identification is based on the name of the columns not on their order)

  • Semicolon separators

Note

You may use double quotes if you need to have “;” in the value

CSV fields

Note

For optional fields, the presence of the column isn’t mandatory in the CSV file. Headers are case sensitive and must comply with the syntax below.

Header (Case sensitive)

Field type

Description

file

Mandatory

Path of the document as archived in the ZIP file  (can be the name with the extension if you do not use subfolders)

employee_external_id

Mandatory

Technical ID of the employee to assign the document to. Mandatory if the document is assigned to the employee based on that data.

registration_number

Mandatory

Registration reference (or employee number) of the employee to assign the document to. Mandatory if the employee_external_id is not used to assign the document.

organization_code

Mandatory

Organization code linked to the registration reference of the employee. Mandatory if the document is assigned based on the registration_number field.

document_type_id

Mandatory

ID of the document-type the document belongs to in Document Manager Core.
You can find this code in your archiving plan on UKG HR Service Delivery.
E.g. contract, acceptance-letter

title

Mandatory

Title of the document to be displayed on UKG HR Service Delivery

date

Optional

Date explicitly defined at the document upload via the API.
If available, it will be used instead of the deposit date to store the document.
Format : YYYY-MM-DD.

external_reference

Optional

External document reference to help identify the document in external tools or filing systems. 
Can track historical ingestion from several sources.

metadata__xxxx

Optional

Document metadata to give more information about a document.  

Replace “xxxx” by the metadata technical code you can find in the administration of your archiving plan on UKG HR Service Delivery.  
Example for a diploma: metadata__school-name
Prefix = “metadata” 
Second part = “__ “ (underscore x2)
Last part = metadata code = “school-name”

Note

With a standard orchestration, the documents are linked to all the active registration numbers of the employees. Please contact us if this does not fit your needs.

To ingest documents of different types, you can alternatively:

  • Use one ZIP with all the document types: add a column for each metadata and leave empty when a metadata is not linked to a document. For instance, leave the column “metadata__school-name” empty if your line is about an ID Card.

  • Build separate ZIP files for each document type, which simplifies maintenance.

Download a sample ZIP file (with a subfolder)

Options to be setup during the implementation phase by your Ipm

Reports

CSV error report

Error reports keep track of any file not processed successfully. The error reports detail which file has failed and what the error is/status. It is posted on the UKG HR Service Delivery SFTP server in the folder out/rpa (only if an error occurs). The file destination is shared with you by the Project Manager.

Encryption

Possible encryption formats: GPG or PGP (see our technical documentation about the SFTP)

Compatible trigger

The RPA can be triggered by the deposit of a file on the SFTP server.