[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:

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:

API library to give you full autonomy but may require development resources on your side.
UKG HR Service Delivery distribution module

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.