Upload employee role revisions to WFM using Integration Central

Follow this guide to upload employee role revision records in bulk to Humanforce WFM using the Integration Central file import tool. This supports efficient, accurate management of role, award and rate information across multiple employees, locations or departments.

This task is designed for organisations managing role and pay changes at scale and helps ensure employee role records remain current after restructures, award changes or bulk updates.

If you're not yet familiar with Integration Central file imports, start by reviewing Configure and run file import tasks in Integration Central.

Part 1: Prepare the employee role revisions file

1. Go to Management > Advanced > Integration Central - Add New > File Import.
2. Download the latest Employee Role Revisions import template.
3. Enter your data, following the required field rules:
   • Each role revision must be a separate row.
   • All lookup values (e.g. PayCompany, Role, AwardProfile) must already exist in WFM. Supported lookups: GuidKey, Short Name, Name, or Export Code. Some fields do not support Short Name (see Additional information).
   • The RoleRevisionDateEffective field must use a supported date format (e.g. yyyy-MM-dd). Only the date is stored, times are ignored.
4. Review field mapping behaviour:
   • Fields not mapped will retain their existing values.
   • Fields mapped but left blank will:
     • Inherit default values, if available.
     • Otherwise, be cleared (set to null).
5. Save the completed file in .CSV format.

Once your file is correctly structured and saved, it’s ready for upload.

Part 2: Upload the employee role revisions file

1. Return to Management > Advanced > Integration Central - Add New > File Import.
2. Select Employee Role Revisions as the import type.
3. Choose an employee matching identifier (e.g. External ID or Employee Code).
   • This step is mandatory.
4. Choose how to upload:
   • Scheduled upload or
   • Ad-hoc upload
5. After upload, check results in View Logs or History:
   • Standard logs show file status and validations.
   • The upload results log includes:
     • Row-level validation errors (if any)
     • A downloadable copy of the processed file
6. Save the results log for audit and troubleshooting.

When successful, a confirmation appears in Integration Central. Updated role details are visible at Management > Employee > Employee Management - Employee Profile > Locations, Departments, Roles > Role.

Additional information

• Recommended upload order:
  1. First, upload Employee Basic records with a default location, department, and role.
  2. Then, use Employee LDR to add all additional LDR combinations.

  3. Finally, use Employee Role Revisions to load full revision history or future-dated changes.

     This order helps minimise upload errors by ensuring that employee and LDR records exist before any role revisions are applied.

• LDR validation:
  • Role revisions can only be added where an LDR already exists.
  • If the file references a missing LDR, those rows will not be uploaded.
    • Use the Employee LDR import to add any missing records before retrying.
• File size limits:
  • No enforced row limit, but the file must be under 15 MB.
  • For large datasets, split files to simplify error handling or for SFTP use.
• Required fields per row:
  • Role and RoleRevisionDateEffective must be populated.
  • At least one of AwardProfile, PayRate or HourlyRate must be included.
  • Files missing these will be rejected without processing.
• PayRate and HourlyRate conflict:
  • A role revision row cannot include both.
  • If both are present, the import will not be allowed.
  • Remove one of the conflicting fields and retry.
• PayRate and Charge Out Rate conflict:
  • A role revision row cannot include both.
  • If both are present, the import will not be allowed.
  • Remove one of the conflicting fields and retry.
• Supported lookup types:
  • For most fields: GuidKey, Short Name, Name, or Export Code
  • For AwardProfile, PayRate, AwardPayRate and BaseAwardProfile: only GuidKey, Name, or Export Code
    • The same look up type needs to be used across the AwardProfile, PayRate, AwardPayRate and BaseAwardProfile, if not the file import will fail.
• Value inheritance rules:
  • If AwardProfile, PayRate or HourlyRate are blank, WFM will attempt to inherit the value from the previous revision for the same employee and role.
  • Inheritance only applies within the same role. Revisions from one role will not carry over to another.
• Update behaviour:
  • If a row matches an existing revision (same employee, role, and effective date), only the non-null fields in the import file are updated.
  • Blank fields are treated as “not posted” and the current values are retained.
• Effective dates:
  • Only the date is stored, any time portion is ignored.
  • Use a standard yyyy-MM-dd format with no time value.
• Optional fields:
  • Optional values such as ChargeOutRate or ProductivityUnits can be omitted.
  • If omitted:
    • On insert, inheritance applies.
    • On update, existing values are retained unless explicitly updated.
• Partial failure handling:
  • If a data issue exists in any revision for a specific employee–role combination, all revisions for that combination in the import run are rejected.
  • Valid rows for other employees are still processed.
• Duplicate or ambiguous reference data:
  • If your environment contains non-unique names for lookup values (e.g. multiple Roles with the same Name), those rows are flagged with errors and skipped.
  • Use GuidKey or Export Code to avoid ambiguity.
• Validation results:
  • The results log shows:
    • Row success/failure status
    • Reason for any failure
  • You can download and review the processed file from the History screen.
• Unsupported actions:
  • Role revision deletions are not supported via file import. 
    Use the API or manual updates for deletions.
  • Effective dates of existing role revisions cannot be changed through this import. 
    Use APIs or the UI to update dates manually.
  • The import does not de-duplicate rows. If you upload multiple rows with the same attributes and different effective dates, all revisions are created and stored.
• Tip for large imports:
  • For imports over 50,000 rows, test in a lower-risk or non-production environment first to avoid system load or data issues.

Reference: Employee Contacts file field definitions