The integration mentioned in this article is currently under development, and the details provided are subject to change. To stay updated on any modifications or enhancements, click the "Follow" button located at the top left corner of this article under the heading.

Who is Humanforce HR?

Humanforce is a unified HCM suite designed for frontline and flexible workforces. Combining workforce management, HR, payroll, and wellbeing, together in the aim to elevate employee experience and simplify compliance. With features like mobile apps, automated workflows, and employee engagement tools, Humanforce helps organisations improve efficiency, reduce costs, and attract & retain top talent. Whether you're in retail, hospitality, healthcare, or another industry with a dynamic workforce, Humanforce offers a customisable suite to meet your specific needs. For more details, you can visit ⭧Humanforce's official website.

What this article covers

This article outlines the steps to integrate Humanforce HR (HR) with Humanforce Workforce Management (WFM) for Humanforce Cloud customers. Proper setup is crucial to prevent data issues and ensure smooth workforce management operations. If you require assistance or are unsure about setting up the integration, please reach out for help before starting to avoid additional fees for support/service packages.

What does the integration do?

The integration between Humanforce HR and Humanforce WFM facilitates the transfer of crucial employee data, ensuring accuracy and efficiency in workforce management.

Here's what the integration accomplishes:

• Auxiliary Data Transfer: 
  • Auxiliary data, such as pay companies, employment types, and award profiles, are transferred from WFM to HR. Qualifications are transferred from HR to WFM 
• Employee Personal Details:
  • Humanforce HR→ Humanforce WFM:
    • Newly created People records in HR, with a primary job, are sent to WFM.
    • Updates made to the employee's People or Job in HR are sent to WFM.
    • Bulk sync of People and Job data can be scheduled to WFM.
    • Termination dates in WFM are updated when a person is deleted or a primary job is ended in HR.
    • Deleting a person or adding a Company End Date to the primary job in HR will update the termination date in WFM.

    • The integration prioritizes updating existing employees in WFM before creating new ones, using the following matching logic:

      • Match HR's internal GUID for the employee in WFM (invisible to users) 

      • If no match is found, identify the closest match based on Email, Date of Birth, First Name and Last Name (all attributes must match).

      • If neither approach yields a match, create a new employee.

  • Humanforce WFM → Humanforce HR: 
    • Updates made to employees' personal details from the Employee Management screen or via the Change Approval process will flow through to HR.
      Note, that changes made by employees via ESS, without approvals active will not trigger the integration flow.

      This feature is currently available for early access. If your organisation would like to take advantage of this capability, please raise a support ticket or contact your project team to discuss enabling the feature for your environment.

Humanforce HCM Suite Integration between Humanforce HR, WFM, and Payroll

For HCM Suite Customers: Data synchronisation between Humanforce HR, Humanforce WFM, and Humanforce Payroll is seamlessly managed through the Employee Data Forwarding feature. This ensures a unified data flow across the suite, reducing manual intervention and improving consistency.

For more information on the suite integration, refer to Humanforce Suite Integration or see the Employee Data Forwarding section.

Prerequisites

Before proceeding with the integration, ensure that the following prerequisites are met:

• Humanforce Cloud Customer: Access to this integration is exclusive to Humanforce Cloud customers.
• API Credentials: Obtain API credentials from HR with comprehensive permissions to facilitate data exchange between the platforms.
• Source of Truth: HR serves as the primary repository for employee data within the integrated ecosystem, ensuring consistency and accuracy across platforms.
• Change Approvals: The "Changes Require Approval" permission must be enabled for changes to flow via the Change Approvals page into HR.

Integration Workflow

Follow these steps to set up the integration between Humanforce HR and Humanforce WFM:

1. Prepare your data:
   1. Create Custom Fields (if needed): ⭧Learn how in this article.
   2. Create Auxiliary Data:
      • In WFM: Create pay company, employment type, award profile, roster period, access level, clock-in setting, location, department, role, and area.
      • In HR: Create qualifications and mark them as valid
      • In both systems: Create pay rates, gender, title, and visa type.
   3. Create or upload employee records in HR.
2. Set Up Integration:
   1. Create API credentials in HR. ⭧Learn how in this article.
   2. Set up the integration in WFM > Integration Central. ⭧Learn how in this article.
   3. Test the connection and resolve any errors.
3. Configure Mapping:
   1. Map auxiliary data fields between the two systems. Recommended mapping ⭳below.
   2. Map employee details fields for accurate data transfer. Recommended mapping ⭳below.
   3. Optionally, schedule automatic data synchronisation.
4. Review and Troubleshoot:
   1. Monitor the import log and address any errors for a successful data transfer.

Best Practices and Tips

This section provides key guidelines and tips to ensure accurate data synchronisation between HR and WFM, along with any known issues affecting integration.

• Align Time Zones to Prevent Date Discrepancies
  To ensure accurate date synchronisation between HR and WFM, time zones must be aligned in both systems. WFM has an Humanforce HR Tenant Timezone setting that must be configured to prevent discrepancies in date fields. This can be set by navigating to Admin > Admin Config > System Settings in WFM and selecting the appropriate timezone to match HR, such as (UTC+10:00) Canberra, Melbourne, Sydney. Aligning time zones ensures consistency in date values across both systems.
• Ensure Job-Related Fields are Used for Specific Mappings
  Only job-related fields should be mapped from HR when configuring the following in WFM:
  • Default Award Profile
  • Min/Max Roster Hours
  • Default Pay Rate
  • Default Rate Override
    If these fields are not mapped from the Jobs table in HR, no date will be sent, which will cause an error in WFM. Mapping these correctly ensures proper data transfer and prevents integration failures.
• Ensure Humanforce HR is the source of truth for all employee data including Primary Job
  HF HR should be the source of truth for all employee data including Job & Rates data for the primary job. For all secondary jobs can be maintained and updated in WFM. If the primary job is updated in WFM it will not flow back to HF HR.
• Manage Non-Primary (Secondary) Roles in WFM
  Only the primary job of an employee syncs from HR to WFM. Any non-primary roles must be managed directly in WFM. If an employee holds multiple roles, these additional roles need to be set up and maintained in WFM, as they are not transferred through the integration.
  • This solution does not support multi-contract setups where a single employee has multiple contracted jobs. Humanforce implementation team will need to work with you to find a suitable solution.
• Maintain Location, Department, and Role (LDR) Structures
  The Default Location, Department, and Role (LDR) structure should be maintained in Humanforce HR, while any additional LDRs should be managed within WFM. Keeping LDR structures correctly assigned helps ensure accurate rostering and reporting.
• Manually Maintain Auxiliary Data for Accuracy
  Certain fields must be manually maintained in both Humanforce HR and WFM as they do not automatically sync. These include:
  • Pay rates
  • Gender
  • Title
  • Visa type
    Regular updates to these fields help maintain consistency and prevent errors in reporting, compliance, and payroll processing.
• Verify Field Mappings to Avoid Data Inconsistencies
  Field mappings and configurations should be double-checked in Integration Central to prevent inconsistencies. Ensuring these mappings are correctly set up prevents incorrect data transfers and maintains accurate payroll and workforce data.
• Understand Min/Max Roster Hours Start Date Configuration
  When mapping Min/Max Roster Hours, the start date visible in WFM is based on the "Scope for Roster Hours (Min & Max)" configuration. This setting determines which effective date is applied to imported Min/Max roster hours. Understanding this configuration ensures that workforce planners interpret roster hours correctly and avoid misalignment in scheduling data.
• Review Import Logs Regularly to Catch Errors Early
  Import logs should be reviewed frequently, and errors should be addressed promptly. Identifying and resolving synchronisation issues early prevents delays and ensures workforce data remains accurate across both platforms.
• Terminate Employees in HR First for Proper Processing
  Employee terminations should always be completed in HR first, as this will automatically sync with WFM. However, terminations must also be manually updated in Payroll to ensure that final payments and employment records are processed correctly.
• Default Values for Dynamically Mappable Fields
  Fields such as Employment Type, Default Award Profile and so on where you can define a default value will only pick the default value in case the source field in HF HR is empty. It will not map to the default value in case the data cannot be mapped to WFM due to any reason.

Known Issues

Resolved Issues

1. Role Revision Sync Between HR and WFM

   Issue: Role revisions and rates related to an employee’s primary job do not sync with WFM. This impacts the following fields: Default Award Profile, Min/Max Roster Hours, Default Pay Rate, and Default Rate Override.
   Status: RESOLVED and available for Early Access from 3rd Mar 2025.
   Action Required: If these fields were previously mapped, reset the mappings in Integration Central to ensure correct synchronisation.

Under Investigation

1. WFM Employee fields; Default Award Profile, Pay Rate and Rate Override can only be sourced from HF HR Jobs-Remuneration Native Fields

   Issue: As of now, you can only map the above mentioned fields in HF WFM to source data from HF HR's jobs-remuneration native fields. This means that any jobs or jobs-remuneration custom fields while they are allowed to be mapped, will not actually complete the task of transferring data from HR to WFM as users will expect.
   Workaround: There's no workaround. We plan to support mapping from HF HR jobs and jobs-remuneration custom fields. ETA June-2025

2. Role Revision Date Set to Company Start Date

   Issue: When a new employee's first job in HR has a start date that differs from their company start date, WFM creates the corresponding role with an effective date that matches the company start date instead of the actual job start date.
   Status: Investigation in progress.
   Workaround: The role effective date must be manually updated in WFM to match the job start date as configured in HR.

3. Role Revision Date Update in HR for an existing Role in WFM creates new Revision without replacing
   Issue: When an existing role revision date is updated in HF HR, it creates a new entry in WFM without replacing the existing role effective date. E.g. If an employee was promoted to a new role on the 2nd of Feb 2025 and after this was sync'd to WFM, HR manager realized that a mistake was made where the actual promotion date needed to be 22nd of Feb 2025, then the integration will create a second role revision from 22 Feb 2025 onwards without removing the 2nd Feb 2025 entry.
   Workaround: The 2nd Feb 2025 entry needs to be manually deleted in WFM.

4. Any future dated role revisions imported to WFM will not reflect the latest rates until an employee import is run
   Issue: When an employee has future dates role revisions, they will be imported to WFM to enable future rostering. However, in some scenarios, the rate related to those future dated roles may not reflect the latest rates applicable in real-time and requires an import.
   Workaround: To ensure to latest rates are reflected, please run the employee import daily.

5. An Employee's emergency contacts & qualifications are not imported to WFM on JOB.CREATED Webhook Event from HR if the employee doesn't exist in WFM already
   Issue: When an employee is created in HF HR with emergency contacts and/or qualifications, those emergency contact and qualifications are not flowing through to WFM in real-time as they should when the job.created webhook has been triggered.
   Workaround: These data will flow through to WFM on the employee bulk sycn import or the next job.created or person.updated webhook that is triggered on this employee.

6. Qualifications deleted in HR are not deleted in WFM automatically
   Issue: Qualifications are deletions in HR are not sync'd to WFM.
   Workaround: You will need to build a process that will manually delete the qualification from WFM after its deleted from HR.

7. All Qualifications are imported to WFM irrespective whether they are not in a "Current" or "Approved" status in HF HR
   Issue: The current integration behaviour is to import all qualifications that are considered valid as of the date of running the data import into WFM. Due to not filtering by HF HR's qualification statuses, qualifications in other statuses such as "draft" will be imported as well.
   Workaround: Only way to avoid this is for customers to only load qualifications that are valid to HF HR.

This section will be updated as new fixes or workarounds become available. For further assistance, contact Humanforce Support.

Integration Setup

Detailed step-by-step setup instructions for the Humanforce HR integration can be found in this article ⭧Set up Humanforce HR integration

API Documentation

• The Humanforce HR integration utilises webhooks for employee updates. Any changes made within Humanforce HR will trigger the webhook and update Humanforce WFM. More information on Humanforce HR webhooks is available in this article ⭧Set up Humanforce HR integration.
• Humanforce WFM uses its REST API to push and pull data between the systems. More information on the Humanforce REST API is available in this article ⭧Humanforce REST API Overview.

Employee Data Forwarding (Available for use in Early Access)

Overview

Humanforce is excited to introduce the Employee Data Forwarding feature, which enables seamless data synchronisation across multiple integrations within Humanforce Workforce Management.

Key Benefits

• Seamless Integration: Connect Humanforce products (Humanforce HR, Humanforce WFM, and Humanforce Payroll) and supported third-party integrations.
• Automatic Updates: Ensure that data changes made in HR are automatically forwarded from WFM to Payroll, eliminating the need for manual updates.
• Improved Data Consistency: Minimise the risk of data inconsistencies and reduce manual data entry efforts, maintaining up-to-date records across all systems.

Getting Started

With Employee Data Forwarding, you can link Humanforce HR, WFM and HF Payroll systems together. 

For detailed setup instructions and more information, please refer to the Employee Data Forwarding documentation.

Integration Options

This integration facilitates data transfer between Humanforce WFM and Humanforce HR in two main categories:

1. Auxiliary Data: Auxiliary data serves as the admin list for specific employee data fields, ensuring consistency across systems. This includes information like pay companies, employment types, and award profiles, which are transferred from Humanforce WFM to Humanforce HR.
2. Employee Personal Details: This includes employee information such as personal details, employment details, and qualifications, which can be transferred from Humanforce HR to Humanforce WFM, however please pay close attention to the supported mapping directions per field as bi-directional support is not available for all fields. 

Auxiliary Data

Field Mapping

The Humanforce HR field names noted below are populated to reflect the recommended mapping. However, these fields are configurable on the integration configuration screen within Humanforce WFM (Management > Advanced > Integration Central).

Note, for auxiliary data to transfer between systems, an integration must be run.

Employee Details

Available Integration Flows

The integration supports bidirectional employee data synchronisation between WFM and Humanforce HR, ensuring that employee records remain accurate and up to date in both systems.

WFM→ HR 

Employee data is synced in real-time from WFM to HR when an employee record is edited and saved in WFM. Updates are triggered by changes made via the Employee Management or Change Approval screens. The synchronisation follows the export mappings configured in Integration Central to determine which fields are updated in HR.

HR→ WFM

Employee data is transferred from HR to WFM through the following methods. In all cases, the synchronisation follows import mappings set in Integration Central.

• Job Created Webhook: When an employee's primary job is created in HR, their record is created in WFM. This sync includes:

  • • Personal details

    • Primary job information

    • Qualifications (all non-DRAFT qualifications in HR, with a VALID FROM and VALID TO date that matches the date at which the webhook triggers) 

  • Person Updated Webhook: When an employee’s personal details, primary job, or qualifications are updated in HR, the integration automatically updates WFM to reflect these changes.

  • Person Deleted Webhook: When an employee is deleted in HR, the integration marks the employee as terminated in WFM, using the current date as the termination date.

  • Qualification Instance Updated Webhook: When an employee's qualification details are updated in HR, all non-DRAFT qualifications in HR (with a VALID FROM and VALID TO date that matches the date at which the webhook triggers) are imported into WFM.

  • Job End Date Finalised Webhook: When an employee’s job end date is confirmed in HR, the integration marks the employee as terminated in WFM, using the termination date provided by HR.

    Real-Time Synchronisation via Webhooks

    When certain employee events occur in HR, webhooks trigger automatic updates in WFM. The following webhooks control specific data flows:

     

• Bulk Synchronisation (Scheduled or Ad-hoc)

  A full employee data sync can be run either on a scheduled basis or manually triggered in WFM. This sync imports:

  • Employee personal details

  • Primary job and all historical job revisions

  • Qualifications (all non-DRAFT qualifications in HR with a VALID FROM and VALID TO date that matches the date at which the webhook triggers) 

  • Any termination date updates

  Bulk synchronisation is recommended for initial data loads or periodic validation of records between HRand WFM.

Employee Connection

When integrating employee details between systems, it's important to understand the criteria for bringing an employee into the system. Initially, the system filters for employees with a current primary job. Further filters can be applied through the integration setup page, such as specific Business Entities or Custom Field requirements. Enabling this option prompts the system to check for a specified field value against an employee (e.g., "Default Location = Melbourne, Sydney and Brisbane") in addition to having a current primary job.

Before the integration connector is activated, scenarios may occur where the same employee exists in both HRand WFM systems. In such cases, the system employs a combination of the following identifiers to determine if it's the same individual:

• iHR GUID Key (GUID)
• First Name (FN)
• Last Name (LN)
• Date of Birth (DOB)
• Email

Case 1: If a potential duplicate entry is identified, a new record is created in the WFM.

Case 2: Upon recognising a match between the existing HRand WFM records, the system updates the WFM record with relevant changes.

Fixed Mapping

The table below illustrates fixed mappings:

Note: Items in red are planned for a future release.

* Mandatory field

Adjustable Mapping

In addition to fixed mappings, certain fields allow for adjustable mapping configurations within Humanforce WFM. These fields can be customised based on your business requirements. The following things should be considered before completing the integration.

• Where field details are noted as "Summary Entity Model", ensure the values held in the auxiliary list match between systems.
• When using custom fields, the custom field must be created within HR before they can be used for mapping in WFM. For more information on how to do this refer to our ⭧Custom Field article.
• Where noted below the following Job Fields are available for alternate mapping - Business Entity, Business Unit, Employment Condition, Hourly Rate, Hours Per Cycle, Location, Pay Grade, Position Title, Work Class, and Work Type.
• The mapping configurations may vary per customer based on their unique needs and system setups.

The following table illustrates the adjustable mappings:

The Humanforce HR field names noted below are populated to reflect the recommended mapping. However, these fields are configurable on the integration configuration screen within Humanforce WFM (Management > Advanced > Integration Central)

Note the job related field mappings only refer to the primary job of the employee as mentioned in the Known Issues / Gaps / Callouts section.

Note: Items in red are planned for a future release.

* Mandatory field

Non-Integrated Data

The following fields are not available to map between the two systems, so need to be maintained in the source system if required.

Humanforce HR fields

* Mandatory field

If an Humanforce HR custom field is marked as “sensitive,” it won’t be available for field mapping in the integration. For more details on custom fields, refer to this article.

Humanforce WFM fields