Paycode Mapping Bulk Update

Mapping paycodes in bulk is a two-step process:

1. Populate a CSV file with the mapping values using the appropriate formatting.
2. Upload the CSV file in the Configuration Portal, from the Paycode Mapping Bulk Update page.
3. The Paycode Mapping Bulk Update page shows the status of any bulk paycode mapping files you have uploaded, including whether the file upload was successful. If the upload failed, see what caused the error and how to troubleshoot the problem.

Note: As an alternative to running the bulk upload process yourself, during Data Hub implementation, work with your UKG Representative to supply your source paycodes and mapping values. Your UKG Representative will then upload the CSV file directly to the Data Hub GCP project.

After mappings are bulk updated, manage and update mapping values from the Paycode Mapping page. For more information about using paycodes, mapping examples, guidelines, and how to manually edit and export paycodes, see Configure Mappings.

When you bulk update paycode mappings, note the following:

• The CSV file with your paycode mapping details must conform to the proper structure. Before you upload the CSV file, it is recommended that you export your source paycode details from the Paycode Mappings page as a CSV file that has the proper columns and all your paycode names and IDs. Use it to populate your paycode mappings for upload. If at any time the underlying Data Hub paycode structure changes, you can export the CSV to ensure you use most recent columns.
• Before you upload the CSV file, do not change column names, the order of columns, or values in the payCodeId column.
• Inserting a new paycode that does not exist in UKG Pro Workforce Management is not supported. Doing so will cause the upload process to fail. Only CSV files are supported. Attempting to upload a file other than CSV will fail. For more information about CSV file upload errors, see Examples: Bulk file upload errors.
• CSV file size should not exceed 5MB and the file name should not exceed 50 characters.
• The bulk mapping process copies all mappings in the CSV file and replaces (overwrites) the Data Hub mappings.
• If you manually edit mapping values from the Paycode Mapping page, those changes will be overwritten when you run a bulk update.
• Bulk mapping can be run more than once depending on your business needs. For example, you may want to bulk upload mappings if you have hundreds of new paycodes due to your company expanding into a new geographic area.

1. Go to the Setup > Paycode Mapping Bulk Update page. The File Upload Status panel shows details about recent bulk update jobs run on the tenant, including:
   • File Name. The name of the CSV paycode mapping file.
   • File Upload Status. The current status of a bulk update. Statuses include:
     • In Progress, File Scanning, and Scan Success. Files are scanned for security reasons. A successful scan indicates the file does not contain a virus or other risks and the upload can continue.
     • Scan Failure. The file contains a virus or other threat and cannot be used.
     • File Imported. The bulk update was successful. The next time pipelines run, the summary metrics will recalculate based on the updated mappings.
     • File Import Failed. The upload fails when the file is not properly formatted. For example, if the file does not include the payCodeId column or there is a numeric value in a column that only supports a Boolean (Yes/No) value.
     • Note the following:
       • When the upload fails, the mapping process stops at the point in the file where the failure was detected, leaving the mapping in a partially completed state. For example, if there is an unsupported value in row 100, rows 2 through 99 are populated and rows 100 and higher are blank.
       • Note the error in the Description column. You must fix the problem in the CSV file and upload the file again to finish the process and ensure all paycode mappings are complete and accurate.
       • Note: For more information about CSV file upload errors, see Examples: Bulk file upload errors.
     • Invalid File. The file is empty.
   • Description. Details about the uploaded file job including the number of records updated. If the job failed, there are details about what caused the failure.
   • Upload Date Time. The date and time the job completed.

Note: By default, the panel shows the most recent file status first.

2. Refresh the page to see the latest status.

This section describes some of the types of bulk file upload errors that may occur, why they occur, and how to resolve them. These errors display in the Description column for the files that failed the CSV file upload process.

Data error example

{"Please validate file data or refer logs. Error occurred : {'isCoreSwt': [ErrorDetail(string='Must be a valid boolean.', code='invalid')]}"}

Reason

This error occurs when you enter non-Boolean values in any of the following paycode columns of the CSV file:

• payCodeId
• Core
• Productive
• Paid
• Meal Penalty
• Holiday
• OT Net Down
• Training
• On Call
• Callback

Resolution

Because most of the columns support only Boolean data, values other than “Yes” and “No” are not valid. Note the column name in the error (such as Core, in this example), and update the column with a valid value.

The following table lists the supported data types for each paycode column:

Column Names	Data Type
Paycode ID	INTEGER
Paycode Name	STRING
Pay Category	STRING
Absence Category	STRING
Core	BOOLEAN
Productive	BOOLEAN
Paid	BOOLEAN
Meal Penalty	BOOLEAN
Holiday	BOOLEAN
OT Net Down	BOOLEAN
Training	BOOLEAN
On Call	BOOLEAN
Callback	BOOLEAN
User Defined1 - User Defined10	STRING

Invalid file error example - omitted or removed Paycode ID value

“Please upload a valid csv file”

Reason

This error occurs when you try to upload a CSV file the has one or more Paycode ID values removed. Because Paycode IDs are system-defined values, you must never add, change, or remove them. Only the system-defined values are valid.

Resolution

Export the existing paycodes from the Paycode Mapping page. This exported CSV file includes all Paycode IDs.

Invalid file error example - uploaded an empty file

“Please upload a valid csv file”

Reason

The error occurs when you try to upload a blank (empty) CSV file.

Resolution

Follow Prepare the CSV file and upload the file again.

For guidelines and best practices for working with paycodes, see Best practices and examples

If you have not already done so, prepare the CSV file with the paycodes and the mapping values. To ensure you use the proper format, export a CSV of your source paycodes and mapping values.

Note: Occasionally, the paycode structure will change, for example, when support for new columns is added. It is recommended that you export the CSV to ensure you are using the most current structure. This can be at any time.

1. Go to the Setup > Paycode Mapping page.
2. Click Export Paycodes. A CSV file downloads to your browser. At a minimum, this file contains all the necessary columns and your source paycode ID values and names.
3. Update paycode mapping values as needed. Ensure the file is formatted with the right columns and the values are valid. For example, you cannot enter a number in a Boolean field that expects a No or Yes value. For guidelines and examples, see Configure Mappings.

Caution: Do not change column names in the first row, the order of columns, or values in the payCodeId column. Never insert a paycode or paycode ID that does not exist in UKG Pro Workforce Management.

4. Save the file.

1. Go to the Setup > Paycode Mapping Bulk Update page.
2. Click Choose File.
3. Navigate to and select the CSV file that has the paycode mappings.
4. If you attempt to upload a file with any of the following unsupported conditions, a message opens alerting you to the problem:
   • You select a non-CSV file.
   • The file size exceeds 5MB.
   • The file name exceeds 50 characters.

   You must fix any problems before you continue. For error examples and resolutions, see Examples: Bulk file upload errors.

4. Click Upload. Records are processed in consecutive order. The upload takes a few seconds to a minute or more to finish, depending on the number of paycodes.
5. Refresh the page and note the status in the File Upload Status column. For more about statuses, see View paycode file upload status. If the upload fails, determine the problem and fix the issue, then upload the file again.
6. To see the latest paycodes, click Back To Paycode Mapping. The Paycode Mapping page reflects the latest mappings. From the Paycode Mapping page you can manually update the paycodes as needed.