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 Payroll?

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 functions and options available through API-based integration between Humanforce Workforce Management (WFM) and Humanforce Payroll (Payroll) in Humanforce Cloud. It is crucial to set up the integrations correctly to prevent data issues. 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 packages.

What does the integration do?

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

Here's what the integration accomplishes:

• Auxiliary Data
  • Humanforce Payroll → Humanforce WFM
    • Public holidays, LDRs, pay rates, and pay types are transferred from Payroll to WFM.
• Employee Personal Details:
  • Humanforce Payroll → Humanforce WFM
    • Newly created employees and updates made to the employee's details are sent to WFM in a bulk sync that can be scheduled or manually run through Integration Central (IC).
    • Termination dates entered in Payroll will sync to WFM.

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

      • Match WFM's Payroll Code to the incoming Employee Number in Humanforce Payroll.

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

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

  • Humanforce WFM → Humanforce Payroll
    • New employees created in the WFM Onboarding module or Employee Management screen, create a new employee in Payroll.
      • Note, an employee will not be active in Payroll until all payroll-specific fields (e.g. Tax details, leave accruals, etc) are completed directly in Payroll.
    • Updates made to employee's details from the Employee Management screen or via the Change Approval process will flow through to Payroll.
• Payroll Export
  • Humanforce WFM → Humanforce Payroll
    • Timesheets are clocked, authorised and processed against the employee's assigned award profile in WFM. Then award-interpreted timesheet data, leave taken, and override rates are synced to Payroll.
• Employee Leave Balances
  • Humanforce Payroll → Humanforce WFM
    • After payroll finalisation leave balances are updated in Payroll and can be synced to WFM.
• Payslips
  • Humanforce Payroll → Humanforce WFM
    • After payroll finalisation payslips are available in Payroll and can be synced to WFM.

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 Humanforce Payroll with comprehensive permissions to facilitate data exchange between the platforms. Ensure to note the system you are integrating with when requesting the API. i.e. Humanforce WFM or Humanforce HR.

• Source of Truth: Humanforce Payroll serves as the primary repository for employee data, unless Humanforce WFM onboarding is used, in which case WFM becomes the source of truth.

• Change Approvals: The "Changes Require Approval" permission must be enabled for changes to flow via the Change Approvals page into Payroll.

Best Practices and Tips

• Simplify employment types in WFM to improve reporting and reduce administrative overhead. Employment Types: Fulltime, FulltimeLL (with Leave Loading), PartTime, PartTimeLL, and CAS (Casual).
• Send timesheets for worked and leave hours for all employees, including salaried (autopaid) staff. This can be achieved by creating Master Templates for salaried staff, loading them into rosters, and using a data exchange task to auto-create timesheets based on these rosters for employees with the "Timesheet Autocreate" flag enabled.
• Ensure that awards are configured to cap hours per period for payment for full-time and part-time employees.
• Roster Max Hours, Locations, Departments, and Roles should be managed within the WFM system.
• Provide cost center mapping to Payroll for accurate timesheet cost mapping; if not provided, the employee's default cost center in Payroll will be used.
• Ensure the shift type in WFM is set to Enable Accruals when importing leave balances.

Known Issues / Gaps

1. Variable Amount Allowances
   • Issue: If an allowance is set as a variable amount in payroll and the export dollar figures are set/managed in WFM, the dollar value is not sent to Payroll in the payroll export.
   • Status: Work in progress, expected resolution by the end of June.
   • Workaround: Set up the pay element in Payroll as an allowance amount by unit, with the dollar value being held and managed in Payroll. If the value is unknown and entered at the time of the shift, set up the value in Payroll as $1, allowing the manager to add the required total value in WFM.
2. Role Revision Date
   • Issue: When a new employee has a role assigned, the role effective date defaults to 01/01/1900. On save, the rate does not flow from WFM to Payroll, as dates before the employee's start are not accepted in Payroll.
   • Status: An investigation is underway to address this issue.
   • Workaround: Manually update the role effective date in WFM to the employee's start date to allow the rate to flow through to Payroll.
3. Employees with New Zealand addresses not be created or updated in HF PAYROLL from WFM when State is set to non-standard value in HF Payroll
   • Issue: If a NZ address of an employee has State field set in WFM, then it needs to match exactly what HF Payroll supports in the State drop-down. Complexity here is that NZ does not have a concept of state (or as NZ calls them REGIONS) in their addresses yet this is critical for payroll processing for deducing public holidays. This is further exasperated when HF HR is added the mix where the state field cannot be manually adjusted. 
   • Status: Investigation in progress to identify a solution.
   • Workaround: If WFM-HF PAYROLL integration only, then manually adjust state to match regions in NZ. If HF HR-WFM-HF PAYROLL, then NO WORKAROUND. 

Integration Setup

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

API Documentation

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.

Integration Workflow

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

1. Prepare your data:
   1. Create Auxiliary Data:
      • In WFM: Create Access Level, Clock-in Setting, Qualification Types, Visa Types, Location, Department, Role, and Area in WFM.
      • In HF Payroll: Create Public Holidays, Pay Rates and Pay Type.
      • In both systems: Create and match Gender, Title, Pay Company, Employment Type, and Award Profiles in both WFM and Payroll.
   2. Create or upload employee records in Humanforce WFM.
2. Set Up Integration:
   1. Obtain API credentials for Humanforce Payroll. ⭧Learn how in this article - HF staff only
   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. Employee Import
      • Enable employee details, leave balances, pay slips and auxiliary data sync for accurate data transfer. Supported mapping ⭳below.
   2. Employee Upload
      • Enable employee details mapping for accurate data transfer. Supported mapping ⭳below.
   3. Payroll Export
      • Enable cost centre mapping, if required.
      • Match the WFM pay types to relevant export behaviour, payroll pay element and settings of Payroll.
      • To ensure Under-18 employees are paid correctly under the statutory superannuation guarantee rules, you will need to ensure the relevant pay types have an export behaviour = element, setting of Factor of Rate and have the tickbox ticked to send dates for under 18 employees.
   4. Optionally, schedule automatic data synchronisation.
4. Review and Troubleshoot:
   1. Monitor the import log and address any errors for a successful data transfer.

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.

Supported Data Mapping

This integration facilitates data transfer between Humanforce WFM (WFM) and Humanforce Payroll (HFP) 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 public holidays, location, department, role, pay rates, and pay types, which are transferred from HFP to WFM.
2. Employee Details: This includes employee information such as personal details, and employment details, which can be transferred in both directions between the two systems.
3. Payroll Export: Once timesheets are processed in the WFM payroll screen, the timesheet data can be uploaded to Humanforce Payroll.
4. Employee Leave Balances: Employee leave balances are checked and pulled every time the Humanforce Payroll integration central task runs in WFM.
5. Payslips: The payslip import is triggered as part of the integration when the Humanforce Payroll integration central task runs in WFM.

Auxiliary Data

The table below illustrates fixed mappings. Note, these fields can be enable or disabled on the integration configuration screen within Humanforce WFM (Management > Advanced > Integration Central).

Employee Details

The following tables will take you through which employee data fields can be transferred via the API.

Some fields are configurable in the integration configuration screen in WFM (Management>Advanced>Integration Central).

• Where field details are noted as "Summary Entity Model", ensure the values held in the auxiliary list match between systems.

Integrated Data

New Employee Defaults (HF Payroll to WFM Employee Import)

The following fields allow once-off values to be selected for newly created employees when importing employees from HF Payroll to WFM.

* 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 WFM fields

* Mandatory field

Humanforce Payroll fields

* Mandatory field

Payroll Export

Timesheet Upload API Integration

The Humanforce Payroll Timesheet Upload API allows you to upload timesheet data directly into the payroll system, ensuring a seamless and efficient process. This section provides detailed information on how to configure and use this integration.

• Endpoint: /Api/Timesheet
• Method: POST

• The API accepts the following input parameters:

  Parameter Name	Description	Accepted Values
  IsAppend	Indicates if the export should append or override data.	True; False
  LoadStandardPayElements	Used when loading into Pay Adjustment only.	True; False
  FileFormat	The format of the export data.	“json”
  FileContent	Content of the export file formatted according to FileFormat.	A string representing the file content in csv or json format

Field Descriptions

* Mandatory field

Cost Centre Mapping

Cost centre mapping (CCM) is a crucial step in integrating Humanforce WFM with Humanforce Payroll. It ensures that timesheet data is accurately matched to the corresponding cost centres in Humanforce Payroll.

Activating Cost Centre Mapping (CCM):

1. Navigate to the Payroll Export section and access "Cost Centre Mapping" on the second tab.

2. Select the appropriate source(s) for the cost centre codes, such as:

   • Location ExportCode
   • Role Name
   • <Custom Cost Centre Mapping Name>
     This list includes built-in sources, with the option to custom cost centre mappings can also be configured and will appear by their names.

3. Reorder the mapping when using a combination of sources by dragging and dropping using the icon to the left of each source.

4. Default Values: If a combination of timesheet attributes does not resolve to a cost centre map string, a default value (if set) will be used instead of sending a blank string.

5. Separators: Choose the required type of separator for cost centres as defined in Payroll, such as:

   • Slash /

   • Dot .

Further Resources:

• How to import Cost Centre Mapping through Integration Central?
• How do I update Cost Centre Mappings? (Back Office). Note, this will be available in web early 2025.

Employee Leave Balances

Humanforce Payroll offers the option to convert leave balances between different units (weeks, days, hours) during the import and export processes. This functionality is available for specific countries and leave types, allowing for accurate data transfer between Humanforce WFM and Humanforce Payroll.

Australia: Long Service Leave Conversion

For Australian customers, the integration supports converting long service leave balances between weeks and hours.

Import Process:

• Applies only when the task country is set to "Australia"
• Applies only to the leave type "Long Service Leave"
• Applies only when the leave unit is set to "Week"
• If the "Import Long Service Leave as hours" setting is enabled, the leave balance (in weeks) is multiplied by the employee's LslAverageHoursPerWeek value from Payroll to convert it to hours.
• If the LslAverageHoursPerWeek value is null, this leave type is skipped for the employee, and a warning is logged.

Timesheet Upload Process:

• Applies only when the task country is set to "Australia"
• Applies only to the leave type "Long Service Leave"
• If the "Upload Long Service Leave as weeks" setting is enabled, the leave hours from the timesheet are divided by the employee's LslAverageHoursPerWeek value to convert them back to weeks.
• If the LslAverageHoursPerWeek value is null, a warning is logged, and the leave is uploaded in hours without conversion.

New Zealand: Leave Balance Conversion

For New Zealand customers, the integration supports converting leave balances between weeks and days.

Import Process:

• Applies only when the task country is set to "New Zealand"
• Applies to all leave types
• Applies only when the leave unit is set to "Week"
• If the "Convert leave from weeks to days" setting is enabled, the leave balance (in weeks) is multiplied by the employee's NzAverageDaysPerWeek value from Payroll to convert it to days.
• If the NzAverageDaysPerWeek value is null, this leave type is skipped for the employee, and a warning is logged.

Timesheet Upload Process:

• Applies only when the task country is set to "New Zealand"
• Applies to all leave types
• If the "Convert leave from days to weeks" setting is enabled for the selected leave mapping, the leave hours from the timesheet are divided by the employee's NzAverageDaysPerWeek value to convert them back to weeks.
• If the NzAverageDaysPerWeek value is null, a warning is logged, and the leave is uploaded without conversion.

Payslips