Creating data sets

Note

Data sets is a complex and powerful feature to enable UKG HR Service Delivery customers and partners to create reusable and centralized structured data ‘nests’. You will learn more about data sets structure, richness, and API usage in the following guide. If you wish to learn more on how to manage data sets through SFTP, head to the relevant guide.

Prerequisites

Identify where on your platform data sets can be useful to your company and business users. Work with your UKG HR Service Delivery administrators & users to define the data sets that need to be made available on your instance.

What is a data set?

A data set is a collection of data. It can be hierarchical, each level of the data tree being called a dimension. A data set contains information such as translations (to allow your users to display that data in their respective language). A good example of a data set and its dimensions is: Countries > Regions > Cities > Offices.

What are the advantages of using data sets?

• Manage your data sets in one place
• Update lists regularly, automatically through simple API calls
• Use data sets in multiple forms, rather than configuring each form’s data separately
• Support and manage multiple languages
• Handle hierarchies in a consistent way

In the traditional approach to UKG HR Service Delivery products, creating forms with the form builder is easy but requires the administrator to duplicate dropdown data across forms. Data sets solve that by acting as a single source of truth.

Data sets conventions

Before submitting data sets to the UKG HR Service Delivery APIs, you must observe certain formatting guidelines:

• Every data set MUST have an ID (the name of your data set).
• When creating a dimension, the next one is automatically considered its child.
• Dimensions cannot have siblings (only one dimension per hierarchy level).
• Each dimension MUST have an ID.
• Localized names must follow IETF BCP‑47 language codes.

Step‑by‑step guide to creating your first data set

Choose one of two methods:

1. API — full control and real-time sync
2. CSV file import via SFTP

API approach

Example: Create a data set called company_offices with three dimensions: countries, cities, offices. Support English and French.

Adding data to dimensions

You can add or edit values through the API’s PUT endpoints (e.g. PUT /datasets/{id}/values/{code}).
You may need to specify parent paths (e.g. emea.france) for nested dimensions.

CSV import

• Upload a UTF‑8 CSV file to the in/dse SFTP directory.
• The import is complete, meaning old values are replaced (but dimensions persist).
• File structure is flexible — only headers matter, not column order.
• Required columns:
  • dimension_id
  • parent_code (optional)
  • code
  • One or more language columns (en-us, fr-fr, etc.)

Example rows

Summary

You can build robust, multi‑lingual, hierarchical dropdowns (datasets) connected across forms via APIs or file import. Use this to streamline form management and keep data consistent across your system.