Configure the Import Tool

Translations enable you to convert data from an external system to the code values configured in UKG Pro.

Translations can be configured when the source file value must be converted to an UKG Pro code table value. For example, Junior may need to be converted to Jr.

Navigation:Menu > Administration > Integration Studio > Import Tool > Translations

1. From the Description column, select a field description link. The Add/Change Translations page appears.
   
2. At the Source field, enter the source field value.
3. At the Target drop-down list, select the UKG Pro field.
4. Check the Description to Code field to configure that the import data will contain a description that matches the UKG Pro description. Since the descriptions match, the translation will determine the UKG Pro code to submit. Field descriptions are displayed in the Target drop-down list.
5. Select Save.

Prepare a sample CSV (comma-separated value) or other delimited file to configure, validate, and activate an import tool file mapping.

1. Each column header label should be unique, even for repeating data that is sent on one record/row in a file.

   For example, if three Licenses are included in the file, then the column headers and any associated columns should be labeled as: License1, Note1, License2, Note2, License3, Note3.

   
2. Repeating data that is sent on one record, the data should be sent in sequential order and not skip.

   For example, if three Licenses are included in the file, then License1 data should be populated and then License2 data, followed by License3. The import file should not include License3 info with no data populated in the License1 or License2 fields.

   

File Mapping enables you to map data from a CSV (comma-separated value) or other delimited file into UKG Pro employee data tables.

File mapping can be configured for a specific business process or a set of business processes.

File Mapping supports on-demand imports of data through the File Upload page or through file transfer using UKG Pro Data Exchange Service (UDES)/SFTP automation.

Only active mappings can be applied to imports that are either automated using UDES/SFTP or manually uploaded on the File Upload page. A mapping can only be activated after it has been successfully validated. The Validated column indicates whether a mapping has been successfully validated. The Active column indicates whether a mapping is active. If you edit a mapping, the mapping is automatically deactivated and you must validate and activate the mapping again to use it.

• To activate a mapping, at the Active column, check the box for one or more mappings, and select Activate/De-Activate.

• To deactivate a mapping, at the Active column, remove the check for one or more mappings, and select Activate/De-Activate.

From the File Mapping page, administrators can:

• View file mapping details

• Add a file mapping

• Change a file mapping

• Delete a file mapping

• Activate or De-Activate a file mapping

• Export, Import, or Copy a mapping configuration

  • Check the box next to a mapping and select the applicable option from the Actions drop-down list. You can download or copy the file mapping as a back-up or to use in a different environment, as needed.

• View Available Templates

  • Check the Show Available Templates box to display the list of templates that are delivered with the Import Tool. Templates are pre-configured mappings that are intended as a reference or a starting point to create a mapping.

  • To view a template, check the box next to the template, select Import Template from the Actions drop-down list, and select OK. The template displays in the Mappings section with the name beginning with the word Template and a date and time-stamp appended to its description.

    

Navigation:Menu > Administration > Integration Studio > Import Tool > File Mapping

1. Select Add. The File Options page appears.
   

   • Select Choose File to submit a sample CSV or other delimited text file with a header row and at least one row of data that accurately represents the import data format.

   • From the File Type/Format drop-down list, select the import file type.

   • At the Mapping Description field, enter a description for this data mapping.

2. Select Next. The Import Options page appears. The Import Options page enables you to configure import file settings. The file name link is available in the page heading (for example, Job Change) to allow you to download the file that was uploaded, as needed.
   

   • At the Identifier Rule drop-down list, select the employee identification value. Each row in the source file must contain the selected value to identify the employee to which the import data applies. This value is appended to the company code to create a unique identifier for any changes made to the employee record. The Component Company must either be included in the import file or configured as a default value on the Value Mapping page.

   • At the Configure Automation section, check the File Naming Convention box to specify the data mapping according to a file naming convention. This selection is only necessary for automated file delivery through UDES/SFTP. UDES/SFTP automation requires a unique file naming convention for each file. For example, if the value entered in the File Naming Convention box is "newhire123*.*", then any files that are sent via UDES/SFTP with a file name starting with newhire123 will have this mapping logic applied.

     • The value entered in the text box that appears when you check the File Naming Convention box is what is used to determine if the current mapping should be applied.

   • At the Approval Rule drop-down list, select Force Auto Approval to allow this data mapping to override any configured workflows for a business process.

   • At the Empty Field Options section, select one of the options to determine how empty fields are processed.

     • Select No Overwrite to indicate that any blank values in the source data file must not be imported.

     • Select Define Overwrite Value to designate a character to indicate that a blank value was submitted. Select a character value to represent an overwrite in the file. When this value is included in the source file, the value in UKG Pro

       is changed to a blank.
     Important

     The overwrite value feature does not apply to decimal or currency fields, unless the field is a platform configuration or user-defined field. The overwrite value is respected for all platform configuration and user-defined field types.

     For fields that are not platform configuration or user-defined fields, to set a decimal or currency field to 0, you must enter a ‘0’ in the import file.

   • Check the Enable Translations box to enable this mapping to translate the file as determined on the Translations page.

   • At the Business Processes section, select one or more business processes to use to import the source file data. The business processes selection determines which fields display for mapping on the Value Mapping page. For example, if the process selected is Change Job/Position and Salary, then only fields related to that transaction type will display during value mapping.
     Note

     When selecting either the Add Employee business process or the Add/Change Global Employee, you are not able to select any additional processes to include in the same mapping. For example, you cannot map Add Employee and Change Job/Position and Salary in the same mapping configuration. For all other types of transactions, you are able to select different transaction types in the same mapping configuration. For example, you can select Change Job/Position and Salary, Update User Defined Fields, and Add/Change Direct Deposit in the same mapping.

     Choose one of the options to determine how to define the data mapping file.

     • Select Define By File to indicate that all rows in the file will have data that corresponds to the selected business processes.

       • Select one or more than one business process. Select more than one business process by holding down the CTRL key while clicking the business process names.

     • Select Define By Line to indicate that the rows in the file will include a column to identify the corresponding business processes.

       For example, if a source file contains Job Changes and Address Changes on separate lines, there would need to be a transaction identifier column with a pre-configured value to identify the data that applies to each of the business processes. A file example with the Transaction Identifier column and associated records is shown:

       Transaction	Employee Number	Company Code	Job - Annual Salary	Address Line 1
       Job	12345	USG1	10000.00
       Adr	12346	USG1		100 Address Street

       You can use one transaction identifier for multiple business processes, as needed. You can also assign multiple transaction identifiers to the same business process.

       

       At the Transaction Identifier field:

       • Enter the identifier used in the import file. This value is case-sensitive.

       • Select one or more than one business process. Select more than one business process by holding down the CTRL key while clicking the business process names.

       • Select Map to configure the transaction identifier for one or more selected business processes.

3. Select Next. The Value Mapping page appears. The Value Mapping page enables you to map the source file columns to target fields in UKG Pro.
   

   If the data in a source column must be imported, then you must map to target fields or enter default values for those source columns. However, if the data in a source column does not need to be imported, then you are not required to map to target fields or enter default values for those source columns. For example, you may wish to include first and last name in the source file to help identify the employee, but for a job change, you would not need to map the name to a target field.

   Required fields must be mapped or an error will display during validation. Refer to the Import Tool XML and Configuration Settings Guide available in the UKG Community Library for information regarding required fields for each transaction type.

   • At the Target drop-down list for each source field, select the UKG Pro target field for data mapping. The Target drop-down list displays all fields related to the business processes selected on the Import Options page.

     The Target drop-down list includes a field that allows for type-ahead functionality that will dynamically filter the list to available options that match the value. If you do not use the text field, all fields are displayed and can be searched through for selection.

     • There may be multiple entries where the target name is the same followed by [x] where x represents a number. This indicates that multiple fields of the same type can be imported onto a single record. For example, the Contacts transaction type can include up to ten contacts imported on a single record.

     • If a Transaction Identifier was selected on the Import Options page, the Target selection is Transaction Type.

       
     • From the Action column, you can select the Add icon next to a source field to map the field to an additional target field. This can be used when a value is:

       • an identifier, but also needs to be designated as an import value.

       • used to populate two targets. For example, the source value Company is the same value needed for the Company and OrgLvl1 targets.

     • At the Default field, enter a target value that can be used when there is no value in the source file.

       This could be used for all entries or for when most entries in the source file have a value but some may not. In this case, the records with the value will be set to what is populated in the source file and those that are blank will be set to the default value. For example, there may be job change reasons for most entries in the source file, but if one is blank, a default value can be configured.

       Default functionality is available for all fields but should not be used for all fields. For example, defaults on target values such as required fields, direct deposit, property, licenses, etc. is not recommended.

       

       • Select the Search icon next to a Default field, if applicable, to select a code configured in the code table for that field value.

       • Enter a Default field value if the default value is not a code.

         • For Date fields, if you want to default to the current (file processing) date rather than setting a static date, you can indicate this in the Default field with #CURRENT_DATE#.

       • Select the X icon next to a Default field, if applicable, to remove the default field selection.

       • Select the Overwrite icon next to a default field, if applicable, to enter a value that will overwrite the value in UKG Pro.

         If the Import Options page Empty Field Options - Define Overwrite Value setting is enabled, this icon allows you to set the overwrite value as a code. For example, if the file contains Local Unions for some employees, but not for others, and the value in a row of the file is blank, this setting will supply the overwrite value for this record. For non-code values, if an overwrite value is specified on the Import Options page, but the overwrite value is not populated in the file for one or more fields, then you can set the default to an overwrite character for the field(s).

   • From the Actions drop-down list, select Add mapping for field not on file to add and define a field that is not on the source file and will always need the same value. For example, for files that only include merit increases, you can assign all records the corresponding job change code. This will create a new row in the grid where the target and default can be set. The Source will display as "Not in file – Apply Default Value’.

   • To add platform configuration fields, from the Actions drop-down list, select Add mapping for field not on file. Select OK. You will need to do this once to add the Platform Configuration Token (ID) and again to add the Platform Configuration View Path (Path) for each platform configuration field. The Path is case-sensitive and must match the capitalization as show on the Configurations PC Fields page. The platform configuration field that displays in the Source column must be mapped to a corresponding Platform Configuration Value. The Platform Configuration Token number must match that of the Platform Configuration View Path and the Platform Configuration Value (for example, Platform Configuration Token [1], Platform Configuration View Path [1], Platform Configuration Value [1]). You can import up to ten platform configuration fields for each of the business processes that the import tool supports.

     
     Tip You can locate the ID and Path for a particular business process' platform configuration fields using the Configurations tab PC Fields link. (Navigation: (Navigation: Menu > Administration > Integration Studio > Configurations > PC Fields).

     Refer to the Import Data Containing Platform Configuration Fields section to learn how to locate platform configuration ID and Path.

     In order for data to be imported into platform configuration fields that have access rules configured, the user importing the data must have appropriate role access granted.

     Money and Phone Number platform configuration fields also require a corresponding modifier field to be populated in the source file. The modifier mapping number must match that of the platform configuration field (for example, Platform Configuration Value [5], Platform Configuration Modifier [5]).

     Modifier values must both be included in the source file and mapped in the File Mapping - Value Mapping page:

     • Money platform configuration fields must have a Currency Type modifier field value (for example, USD, CAD, EUR, etc.)

     • Phone Number platform configuration fields must have an Access Code/Country Code modifier field value (for example, 1 for USA phone numbers, blank for non-USA phone numbers.)

       
4. Select Next. The Validate page appears. The Validate page enables you to validate the data mapping by checking the first row of data in the source file as an example. Since only the first row of data is validated, when importing a file using the File Upload page or UDES/SFTP, based on the data submitted, there may be data errors that are not caught in the validation on this page. Platform configuration fields are not included in the validation.
   

   • At the Select a Business Process drop-down list, select the business process that maps to the source file.

   • Select Validate to run the validation process for the selected business process. The File Mapping Validation Messages field displays messages or errors, as applicable. Errors must be corrected for successful data mapping.

   • Check the Display Standard XML Output box to view the corresponding XML file mapping data. The XML Output field displays.

5. Select Finish. The Start page displays to enable you to activate the mapping.
   
6. From the Start page, check the Active box for a validated mapping.
7. Select Activate/De-Activate to activate a mapping.
   • To de-activate a mapping, uncheck the Active box for the mapping. Select Activate/De-Activate.

File Upload allows you to import files on-demand.

Files can be manually uploaded to either a Test environment or a Production environment. When preparing a file for upload, blanks lines should be omitted to reduce the risk of errors. To optimize performance, files sizes are limited to a maximum of 5MB.

From the File Upload page, administrators can:

• Upload an import file

• View uploaded import file history details

Navigation:Menu > Administration > Integration Studio > Import Tool > File Upload

1. The Available File Mappings drop-down list displays mappings if there are any mappings that have been activated. At the Available File mappings drop-down list, select the mapping that corresponds to the import file. This drop-down list does not display if there are no active data mappings.
2. Select Choose File to locate the import file.
3. Select Upload.
   The imported file status displays on the Import Results page (Menu > Administration > Integration Studio > Import Tool > Results).

   To comply with GDPR (General Data Protection Regulation) security requirements, records older than 30 days are removed from the import tool.