Business Structure Import

Description
The purpose of the Business Structure import is to maintain both generic jobs and business structure locations.
The integration is capable of:
• Creating and updating generic jobs
• Creating and updating business structure location nodes and job attachments, including re-names, moves, and
expirations
• Creating an export flat file containing the content of the business structure as of a range of dates or single date.
This mode does not process any updates to the configuration.

Moves and updates to the names of either jobs or locations require the use of either a fully unique (across all time
and locations) and unchanging "External ID" OR the ability to provide "before and after" full path data in the source
file, so that the job/location can be property identified for update or move.
For customers using forecasting, effective dated changes (and expirations) must be made at the start of the forecast
week. Mid-week changes are not supported.

Processing occurs "Top-Down" by location type. If you were to update a given location in the source file, the child
locations would be expected to reflect the post-update values of the parent in the same file.
By default, the import also creates before and after export snapshot files as "tomorrow", located inside the "/Inbound"
directory.
Business Structure ‘Root’ node must be created in the application before executing the import integration.

Additional Configuration Notes

Follow these steps to avoid the Generic Job Display Order requirement and sort the Generic Jobs Alphanumerically:

UKGD Application Setup > System Configuration > System Settings > Business Structure
Set all values to False: (JobSortOrderMandatory, JobSortOrderUnique, JobSorOrderNumeric)

UKGD Application Setup > System Configuration > System Settings > Global Values
Create non overlapping child nodes with same name: (nonOverlappingChildDuplicateNameDisallowed)

IMPORTANT: For any alphanumeric field types below do not include any of the following characters:

* %?:;=()/[]\|#@<>",

These characters can be removed/replaced automatically by the import by setting a process property named
"Remove Special Characters" to true. If enabled slashes are translated to hyphens, parentheses and regular brackets
to curly brackets, and all other reserved characters are removed. Please consider the downstream impacts of
“cleaning” the inbound data in this way, as the values may need to be stored for exports back to the source system.

1
Source File Specifications – Generic Jobs
Overview:

Name Value
File Name "generic_jobs.csv"

Format Comma-delimited

Text string qualifier Double quotes <">

Frequency On demand or scheduled

Header Row Yes, 1 row

File Layout - Generic Jobs

Grey fields denote minimum required fields

Data Type (Max

# Dimensions Field Comments/Examples
Length):
1 Job Name Alphanumeric (50) The name of the job as it appears in the Dimensions UI

2 Job Full Name Alphanumeric (50) Also known as the "Job Title"
3 Job Description Alphanumeric (250) The description for the job
A unique identifier for the job, used to sort the jobs in
4 Display Order Numeric (8,0) the Dimensions UI. Not required if Application Setting
described above are set accordingly.
The effective start date of the job.
Recommend sending 1900-01-01, the "beginning of
time" date
5 Effective Date Date (YYYY-MM-DD)
For customers using forecasting, changes cannot be
made mid-week and must be effective at the start of the
forecast week.
The expiration date of the job.
Recommend sending 3000-01-01, the "end of time" date
6 Expiration Date Date (YYYY-MM-DD)
For customers using forecasting, changes cannot be
made mid-week and must be effective at the start of the
forecast week.

2
 Used to provide a custom color for a job. Pass the HTML
hexadecimal color code
7 Color Hexidecimal
Example (for the color red):
#FF0000

8 Job Code Alphanumeric (50) The job code assigned to this job

Would be provided if the customer intends to update the

actual names of the jobs.
9 External ID Alphanumeric (120)
Pairs with the process property "Existing Job ID Type"
being set to "External ID".

Source File Specifications – Locations

Name Value
File Name "locations.csv"

Format Comma-delimited
Text string
Double quotes <">
qualifier
Frequency On demand or scheduled

Header Row Yes, 1 row

Source Folder /Inbound

File Layout - Locations

The default source file layout includes the External ID option, rather than the "before and after" data, one of the two is
required for name updates and move functionality.

Grey fields denote minimum required fields.

If deviating from the standard presented here to use "Before and After" data, include both for a location on a single
record.

# Dimensions Field Data Type (Max Length): Comments/Examples

The UKG Dimensions location type - corresponds to values

set up in Dimensions.
1 Location Type Alphanumeric (50) When passing jobs, please pass the literal Job for this field,
and the value must match an existing generic job name in
Dimensions.

3
 The full path (from the root node to the node above the
location being added). Each level in the location must be
2 Parent Path Alphanumeric (1000) separated by a slash.
Example:
Acme/Region 1/District 20/Location 100

3 Location Name Alphanumeric (50) The name of the location as it appears in the Dimensions UI

The full name of the location. If not specified, set to the same
4 Full Name Alphanumeric (50)
as Location Name
5 Description Alphanumeric (100) The location’s description
The effective start date of the location.
6 Effective Date Date (yyyy-MM-dd format) Recommend sending 1900-01-01, the "beginning of time"
date

The expiration date of the location.

7 Expiration Date Date (yyyy-MM-dd format)
Recommend sending 3000-01-01, the "end of time" date
8 Address Alphanumeric (100) An address attached to the location (not valid for jobs)
The name of the cost center to associate to this location.
9 Cost Center Alphanumeric (50)
The cost center must already exist in Dimensions
Only valid if passing a job.
10 Direct Work Percent Numeric (3,0) The direct labor percentage for this job, ranging from 1 to
100
Only valid if passing a job.
The indirect labor percentage for this job, ranging from 1 to
Indirect Work
11 Numeric (3,0) 100
Percent
Note: the sum of the direct and indirect work percentages
must not exceed 100.
The UKG Dimensions time zone ID or name.
12 Timezone Alphanumeric (50)
CRT is available for translation to valid values.
Boolean to denote if location is transferable
13 Transferable True/False A transferable location has the system job of “Work”
attached and available.
Would be provided if the customer intends to update the
actual names of the location and/or execute moves within
14 External ID Alphanumeric(120) the business structure.
Pairs with the process property "Existing Location ID Type"
being set to "External ID".

Developer Section

Please fully review the attached document "Assessment and Implementation

Considerations" regarding BEFORE assessing and implementing this
integration.
For customers using forecasting, effective dated changes (and expirations) must be made at
the beginning of the forecast week. Mid-week changes are not supported.
4
Additionally, we are currently (as of mid-August 2021) discussing updates to current
functionality around location expirations and the last revision attribute. If you have a customer
seeking to do temporary expirations of locations via the import, please feel free to reach out to Kyle
Dosmann to discuss further. The Assessment and Implementation Considerations document has
been updated to reflect this status and evolving best practices.

Due to the complexity of this integration and the business structure in general, more modifications
beyond the traditional editing of source mapping sub-processes may be required to tailor the
integration to your customer.

Such changes may include:

• Removal of indexes from document caches, in the case of "External ID" not being used.
These are referenced and noted within the Source Mapping sub-processes with floating
shapes.
• Modification of the "Derive Internal ID" map function to reflect your customer's ability to
provide identification for existing locations.
• Modification of the business rules shape "Evaluate To Determine If Update" within "_Core
Processing - Locations". This shape does comparisons from the source file content to the
existing configuration and suppresses calls to the location update API if nothing is
changing.
Business Structure ‘Root’ node must be created in the application before executing the import
integration.
CRTs
Remember to update the "CRTConfig" Process properties with any changes to the CRT definitions
or any additional custom tables added.

1.) BusinessStructureImport_TimeZoneCRT This CRT is available and connected to the

integration, but not actually hooked up to any processing by default.

Field
Field Example Help Text
Name

Source
1 "CST"
Value

Valid Time
2 "Central" Full list of acceptable values are provided.
Zone

Java Time Used to calculate anchor time zone for relative date
3 "US/Central"
Zone ID calculations. For instance, the value of "tomorrow".

5
Control Properties
Property Parameter Default
Help Text
Name Type Value

Remove
Special Boolean false Enable to implement automatic character replacement from the source file.
Characters

Source
yyyy-
Date String Modify to match source file date format
MM-dd
Format

Existing Job
String Name Determines how an "existing" job is identified. Valid values include: "Name" "Exte
ID Type

Existing
Location ID String Name Determines how an "existing" location is identified. Valid values include: "Name"
Type

Allows user to switch between both jobs and locations imports/processing, or just
Processing
String Dual include: "Dual" "Jobs Only" "Locations Only" "Export Only" Creates an SFTP outpu
Mode
full output of the business structure as it existed over the range of provided dates

Move
Boolean false Must be enabled to process moves. Requires the use of external ID or before/aft
Processing

Root Node
String Must populate to cache only objects under a given location node.
Name

Force Enable to force backdating for existing locations by matching the effective date sp
Boolean false
Backdate an existing business structure.

Enable to NOT send any data to the create/update/move APIs and instead to send
Preview
Boolean false Kronos Logging Connector for viewing via process reporting. Due to the fact that
Mode
single request, preview content for moves will only be valid for the highest level b

Export Only Allows for date prompts or programmed relative dates for "Export Only" mode. E
Date
Start Date default. Cannot be set equal to "Export Only End Date" if using export mode; rang

Export Only
Date Pairs with "Export Only Start Date" Expects format of "yyyy-MM-dd" by default.
End Date

Anchor Set to provide input for time zone CRT that will be used for Boomi relative date lo
String
Time Zone doing relative date calculations as of UTC.

Set Context String ORG "ORG" Or "FORECAST". Forecast will return all of ORG and any configured forecast

6
Property Parameter Default
Help Text
Name Type Value

This setting permanently retires the node ID and allows a new location to be creat
Last as what is being retired. The new ID will not be linked to any other configuration a
Boolean true
Revision totals will be split by node ID, regardless of the paths being identical. Last revision
removal of locations.

APIs
API Name API Section Type Resource Path Location

Create Common
_Create
Generic Resources/Business POST /v1/commons/jobs
Jobs
Job Structures/Jobs

Common
Create _Create
Resources/Business POST /v1/commons/locations/multi_create
Locations Locations
Structures/Locations

Common
Move _Move
Resources/Business POST /v1/commons/locations/apply_update
Location Locations
Structures/Locations

Retrieve
Common _Retrieve
Generic
Resources/Business POST /v1/commons/jobs/multi_read Generic
Jobs by
Structures/Jobs Jobs
Reference

Retrieve Common
Location Resources/Business _Core
POST v1/commons/location_types/multi_read
Types by Structures/Location Caches
Context Types

Common
Retrieve _Retrieve
Resources/Business POST /v1/commons/locations/multi_read
Locations Locations
Structures/Locations

Update Common
_Update
Generic Resources/Business POST /v1/commons/jobs/
Jobs
Job by ID Structures/Jobs

Common
Update _Update
Resources/Business POST /v1/commons/locations/multi_update
Locations Locations
Structures/Locations