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 this 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 contain 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 could be : Countries > Regions > Cities > Offices.
What are the advantages of using data sets?¶
In the traditional approach to UKG HR Service Delivery products, creating forms with the form builder is easy, but requires the administrator to create the data available in this form every time. This approach, while acceptable in small organizations, does not scale at an enterprise level, as any change in the data needs to happen per form using this data.
With data sets, you can leverage a single source of truth (the data set) and attach it / link it to multiple forms. If you update your data set, the forms are updated automatically without requiring any further operation from your side.
As you can see in the example below, the data set is linked to multiple forms and, when updated, does not require any ad-hoc form/dropdown changes.
Note
Please note that while the above examples use forms, data sets might be available through other UKG HR Service Delivery features and products in the future.
Key benefits of leveraging data sets and their APIs include:
Manage your data sets in one place
Update lists regularly, automatically through simple API calls
Use data sets in multiple forms, rather than configuring your form’s data one by one
Support and manage multiple languages
Single handedly manage hierarchies
Data sets conventions¶
Before you start submitting data sets to UKG HR Service Delivery APIs, you must understand the following formatting guidelines. The examples below refer to a hierarchical set that contains geographical information, from country to precise office locations.
Every data set MUST have an ID. Consider this ID as the name of your data set. For example,
geos.When creating a data set, you CAN also create your dimensions. If you wish, you can add them later.
A dimension is a sub-set of your data set that can be linked to other dimensions, as a parent or a child. For example
countries,citiesandofficesare dimensions of ourgeosdata set, that can be linked together.Dimensions are linked and their hierarchy is set according on their import/creation order; when you create a dimension, the next one is automatically the former’s child. Dimensions cannot have siblings, meaning only one Dimension per level in the hierarchy is allowed.
Each dimension MUST have an ID. As for the data set itself, this ID SHOULD describe its content. See example above. This ID is used to query the data in the dimension, and also to chain dimensions together. For example
countries.cities.officesFinally, a dimension MUST contain an array
localized_names.Language codes MUST respect the IETF BCP 47 language code specifications.
Note
Please note the DATASET API requires that you go through the following 2-steps approach to create data sets:
Create the data set, containing (potentially) its dimensions,
Insert data in the dimensions.
Step-by-step guide to creating your first data set with UKG HR Service Delivery APIs¶
UKG HR Service Delivery data sets can be created and updated using 2 ways:
with CSV files dropped to your SFTP folder (documentation available here),
with API calls.
While the API integration can be challenging at first, it guarantees real-time synchronized data sets and their availability for any other system, making your UKG HR Service Delivery sets your only ‘source of truth’.
In this guide, our goal is to create and populate a data set, used in a form meant to collect Employee Relocation Wishes. The company is growing rapidly and new offices are opened worldwide quickly, so the data set is meant to be updated on a regular basis.
Create the data set¶
Note
Data sets endpoint specifications are available in UKG HR Service Delivery OpenAPI documentation
We create a data set named company_offices, with 3 dimensions called countries, cities and offices;
Our employees speak English and French, so we want to support both languages:
curl --location --request PUT 'https://apis.REGION.people-doc.com/api/v2/client/datasets/company_offices'
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer $OAUTHTOKEN'
--data-raw '{
"dimensions": [
{
"id": "countries",
"localized_names": [
{
"language_code": "en-us",
"value": "Countries"
},
{
"language_code": "fr-fr",
"value": "Pays"
}
]
},
{
"id": "cities",
"localized_names": [
{
"language_code": "en-us",
"value": "Cities"
},
{
"language_code": "fr-fr",
"value": "Villes"
}
]
},
{
"id": "offices",
"localized_names": [
{
"language_code": "en-us",
"value": "Offices"
},
{
"language_code": "fr-fr",
"value": "Bureaux"
}
]
}
],
"localized_names": []
}'
If everything went well, you should get a 201 response with the data set and its dimensions:
{
"id": "company_offices_tutorial",
"name": "company_offices_tutorial",
"localized_names": [
{
"language_code": "en-us",
"value": null
},
{
"language_code": "fr-fr",
"value": null
}
],
"dimensions": [
{
"id": "countries",
"name": "Countries",
"localized_names": [
{
"language_code": "en-us",
"value": "Countries"
},
{
"language_code": "fr-fr",
"value": "Pays"
}
],
"level": 1
},
{
"id": "cities",
"name": "Cities",
"localized_names": [
{
"language_code": "en-us",
"value": "Cities"
},
{
"language_code": "fr-fr",
"value": "Villes"
}
],
"level": 2
},
{
"id": "offices",
"name": "Offices",
"localized_names": [
{
"language_code": "en-us",
"value": "Offices"
},
{
"language_code": "fr-fr",
"value": "Bureaux"
}
],
"level": 3
}
],
"values_count": 0,
"last_import_status": null,
"last_import_result": null,
"created_at": "2020-01-27T09:54:24.180732+00:00",
"updated_at": "2020-01-27T09:54:24.180732+00:00"
}
Note
The payload specifies the level of each dimension, which corresponds to its position in the tree of dimensions.
In our case, countries (level 1) > cities (level 2) > offices (level 3)
Adding data to your dimension countries¶
Your company has two offices, one in France, and one in the United-Kingdom.
Before adding your offices, you need to add these country values to your countries dimension.
To add (or edit) values of a dimension, we use the PUT /datasets/{id}/values/{code} endpoint.
curl --location --request PUT 'https://apis.REGION.people-doc.com/api/v2/client/datasets/company_offices/values/france'
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer OAUTHTOKEN'
--data-raw '{
"localized_names": [
{
"language_code": "en-us",
"value": "France"
},
{
"language_code": "fr-fr",
"value": "France"
}
]
}'
Here, we attach the france value to the parent dimension countries using the path syntax: dimension.value. But as countries is first level dimension, you do not need to put it here. If your value is in a deeper child dimension, you must specify its full path.
Check that the value france was added to the dimension countries¶
To check that France was added in the list of values of the countries dimension, you can call the GET /datasets/{id}/values/{code} endpoint.
curl --location --request GET 'https://apis.REGION.people-doc.com/api/v2/client/datasets/company_offices/values/france'
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer OAUTHTOKEN'
If the value is set correctly, the API answers with a 200 status code and the content of the value as follows:
{
"id": "countries.france",
"code": "france",
"name": "France",
"localized_names": [
{
"language_code": "en-us",
"value": "France"
},
{
"language_code": "fr-fr",
"value": "France"
}
],
"dataset_id": "company_offices",
"dimension_id": "countries"
}
You can now add the value united-kingdom` to your dimension ``countries, using the same endpoint as for france` above (**PUT /datasets/{id}/values/{code}**).
Completing your data set with cities and offices¶
The steps and endpoints to follow to add values to your data set are the same as seen previously.
You would, in our current use case:
PUT /datasets/{id}/values/france.paris
to create and attach the paris value to the right dimension.
Important
The following animation shows how a data set, connected to a Relocation Form on your employee portal, can be updated INSTANTLY with a new value via API. We are adding the country Italy to the list of available countries for employee relocation:
The employee can see the available countries for the relocation form: France & the United-Kingdom
using Postman, we make an API call to add
italyto the list of countries in thecompany_officesdata setThe employee can now select Italy from the same form and dropdown.
Data set creation via file import¶
The previous walkthrough guided you over the required steps to create your data set and its values through API calls. This method can be helpful when you need to sync or update data from a third party system on a regular basis, in real-time.
If you have more ‘static’ data sets, it can be a good option to create your data set in a CSV file, import it through UKG HR Service Delivery’s Uploads API, and submit this file to the /dataset_imports API.
To format your CSV , you can read more about data set formatting here.
Note that, once you submitted a data set import, you can follow the result of this import with the GET /dataset_imports/{id}.
Please read the /dataset_imports API specifications to know more.