Skip to main content
Skip table of contents

Importing pay history - NZ only

This document describes how to import the pay history for NZ customers from their legacy payroll system into MYOB Advanced People. This must be done before parallel pay runs to ensure that the correct rates are calculated from the first pay run that is processed on Advanced People.

Best practice for implementations:

  1. Build the environment.
  2. Import data from source system, e.g. employees.
  3. Configure entitlements, pay items, pay groups, employee Standard Pay details .
  4. Import opening balances.
  5. Import pay history.
  6. Create parallel pay runs in your Advanced People and previous payroll.
  7. Go live

Set up the import prerequisites

Before importing pay history, you need to configure all the relevant MYOB Advanced Payroll preferences and employee master records: 

  • Payroll preferences
  • GL purposes
  • Posting classes
  • Employee information, including start date
  • Employee entitlement opening balances
1. Create entitlements and pay items

 Use the Entitlements form (MPPP3300) to set up entitlements as per the Managing Annual Leave (NZ) and Managing FBS Leave (NZ) white papers.

For annual leave entitlements, make sure that you select Annual Leave in the Choose leave type field.

2. Create pay groups

 Important details for importing pay history:

  • Make sure that the type and dates are correct
  • Set public holiday items

3. Add employees to pay groups

 Use the Employee Pay Groups form (MPPP2250) to ensure that the employee has been added to the appropriate pay groups. The system will use these values during the import. For instance, if you don’t set the Work Hours field, the system will take it from the employee’s standard hours.

The calendar will be taken from the employee’s standard pay.

4. Set up employee pay details

The employee’s details on the Pay Details form (MPPP2310) must be set properly for the import process to run according to the NZ Holidays Act.

There are two critical fields:

  • The Employee start date on the Employment tab.
  • The employee’s definition of a week, defined on the Definition of Week tab. Set this up before adding leave pay items to the employee’s standard pay.

Standard pay

To set up the employee's standard pay, add all the pay items as normal, including entitlements and accruals, but there are a couple of things to double-check when adding the annual leave accrual item:

  • Make sure the employee only has one annual leave accrual pay item.
  • Check that the entitlement that the accrual belongs to has the Choose leave type field set to "Annual Leave".

 Employees with leave rollover dates that don't match their start dates

If any employees have a leave entitlement that started after their employment, you must override the trigger date for that employee in the Employment tab on the Employee Pay Details form (MPPP2310). The entitlements for that employee will be listed with the trigger date rule and value for each entitlement. The trigger date rule for these entitlements should be employee specific and the trigger date would the default to their start date. You must choose override and change the trigger date value to when the entitlement should start accruing.

Set the trigger date to the date of the employee's last rollover before the first imported pay run. The import pay process does mini pay runs applying 52 weeks of pay data from the legacy payroll system to Advanced payroll, so it needs the correct trigger date to know when the employee's leave rolls over.

Always use the employee's actual start date in the definition of a week, regardless of their entitlement trigger date.

For example, you are importing pay runs for the last 52 weeks starting from 01/06/2020 to 31/05/2021. The employee started on 16/11/2015 as a casual with no annual leave. The employee became a permanent employee with annual leave on 01/08/2017 and this is their annual rollover date. Even though their last actual rollover is 01/08/2020, you should override the employee trigger date to 01/08/2019 because this is the last rollover before the imported pay runs. When it is importing pays, it will start on 01/06/2020 and will trigger the rollover for this employee when it hits 01/08/2020.

5. Check import numbering is set up correctly

The numbering of imported pays is controlled by the Import Pay History Numbering Sequence field on the Numbering Sequences tab of the Payroll Preferences form (MPPP1100), Numbering Sequences tab.


Import entitlement opening balances

  1. To import employees’ entitlement opening balances, create entitlement adjustments of the type “Opening Balance” on the Entitlement Adjustment form (MPPP3000).

    If you haven’t set an accrual pay item in the employee’s standard pay, you will not be able to select the entitlement.

  2. Check the dates related to the adjustment:
    • Last Rollover Date must be the most recent rollover. In our previous example where the employee became entitled to annual leave on 01/08/2017 and you are importing the pay run from 01/06/2020 to 31/05/2021, the last rollover will be 01/08/2020.
    • Transactions Date should be set to the Pay Period End Date of the most recent record in the NZ Import Pay History excel file
    • For Document type select either “Accrued Balance”, “Leave Paid in Advance” or “Earned Balance”.
      • For an Accrued Balance, load the total accrual.
      • For Leave Paid in Advance, capture the leave data as a positive value to reduce the Accrued balance in entitlement movements.
        When an entitlement adjustment containing a “Leave Paid in Advance” line is released, the system generates an additional Entitlement Movement transaction with the reason “Normal Payment in Advance” (the other fields of the transaction behave as for an “Accrual Balance” line). The “Leave Paid in Advance” line does not generate a GL Batch transaction.

Import pay history

  1. Before starting an import, make a snapshot so you can revert back if anything goes wrong.
  2. Go to the Data Providers form (SM206015) and search for "NZ". Select Import Pay History (NZ).
  3. Open the Schema tab to see the list of required fields from the source payroll system. Each row in the data provider is a summary for that employee for a pay run. Pay particular attention to these fields, as they are used to calculate leave rates according to the Holidays Act:
    • Income liable for ADP: The total for all taxable and non-taxable income that is liable for ADP
    • Income liable for OWP4: The total for all taxable and non-taxable income that is liable for OWP 4 week rate
    • Income liable for AWE (Holiday Pay): The total for all taxable and non-taxable income that is liable for AWE, also known as Holiday Pay
    • Days for Average Daily Pay: The total number of whole or part days the employee either worked or was on paid leave or holidays
  4. Go to the Import Scenarios form (SM206025) and find the ADVP-Import Pay History (NZ) scenario. Check that all fields are mapped.

  5. Go to the Import by Scenario form (SM206036) and use ADVP-Import Pay History (NZ). Click Upload File Version to load the data collected from your source system.

    • For more information, see Importing and Exporting Records by Using Scenarios in the MYOB Advanced in-product help.

    • Make sure there are no errors during the import.

    • The process can take some time to complete, because it has to pass the data to the MYOB Advanced calculation engine as it imports the data to calculate the leave rates
  6. When the import is complete, open the Import Pay History form (MPPPP11PL) and check that the expected number of pay runs are there, and that all employees are included as per your data provider.

 Don’t try to reverse imported pay runs. It will affect the further process and system will give invalid results.

Next steps

Once you have imported the employees' pay histories you are aready to create your first "real" pay run.

To quickly check the leave rates and year-to-date gross earning, open the termination wizard, then close the screen without terminating the employee.

Import reference

This section has more detailed information about the import pay history functionality, including data validation and available fields.

Import Pay History form (MPPP1122)

Import Pay History shows imported pay history data grouped by pay period and pay group. Each batch creates a new Pay Run (MPPP3120) with an Employee Current Pay (MPPP3130) for each line.

To add data into this screen, you can add records manually, or use the import scenario described below.

To view the imported and processed records, use the Import Pay History generic inquiry (MPPP11PL). This serves as the primary list for the Import Pay History Batch entry, and allows the standard mass actions on the records: delete, update, action execution. These actions can be customised by the administrators.

The Import Pay History screen contains the following fields.

Summary Area



Batch Number

The number that identifies the Batch in the system, as generated by the system according to the numbering sequence assigned on the Payroll Preferences (MPPP1100) form.


A read-only box that shows the status of the batch, which was assigned by the system and can be one of the following:

  • On Hold – the document is a draft; it can be edited but not released. Remove Hold action changes the status to Open.
  • Open – the document is reconciled to the external data and ready to be released. User can Release the batch using the Release action or put the record on hold by clicking Put On Hold action.
  • Closed – a Pay is generated without errors for all employees included to the Batch.
  • Errors – at least one detail records had errors during the release processing, or no Pay is created.

Pay runs created during the release can be removed using the Delete Pay Run action. This action is available for batches with Closed and Errors statuses.

Pay Group ID

Pay group selector.


Any user-provided description for this document.

External Pay Run ID

The unique reference to the imported pay from the legacy system. This field is not mandatory but is used in the default import scenario to drive the creation of the imported batches and grouping of the detail records into batches.

Pay Run ID

The ID of the pay run generated for this batch in MYOB Advanced.

Pay Period Start Date

Pay period start date.

Pay Period End Date

Pay period end date. Cannot be before the start date.

Physical Pay Date

Pay run physical pay date. You cannot import multiple batches with the same Physical Pay Date for a single pay group.

If a batch has the Errors status, review and correct the lines and then release the batch again. You can release a single batch as many times as you like – it will only process those lines that had errors and were not already imported. Alternatively, it is possible to delete all generated pay runs and release the batch again.

 Details Grid

In addition to the fields available for the previous import pay history functionality the following fields have been added:



Employee ID

Employee selector.

The system checks if the Employee Standard Pay configuration for the Pay Group used in the batch has a pay item linked to the Annual Leave entitlement.


Indicates if the detail record has been successfully included to the generated Pay Run.

Lines marked as Imported cannot be updated. You need to delete the generated pay run before updating the record.

ADVP-Import Pay History (NZ) import scenario

The new import scenario ADVP-Import Pay History (NZ) automates the import pay history process. It uses the Import Pay History screen as a destination and an excel file as a source.

The scenario generates a new batch for each unique pay run ID in the external data file. It also searches for existing existing employee data in the details grid and updates it where possible. New lines are only created if no employee found in the grid. If needed, you can update the default mapping as with other Import Scenarios (SM206025).

 The scenario uses the Pay Run ID column to create batches and group detail lines into them, so make sure you fill out this column.

Rather than directly generating pay runs, this scenario creates Import Pay History screen batches, which you can then review and reconcile before releasing them as pay runs. The imported batches can also be deleted and reprocessed if needed.

Data validation

Additional data validations are in place in the Import Pay History screen:

  1. Only one batch can be created for the same Pay Group and Physical Pay Date.
  2. Permanent employees must have a pay item linked to the annual leave entitlement.
  3. Pay Start Date cannot be after Pay End Date.
  4. Employee Start Date must be before the Pay Period End Date. Specify employee start and end dates in the Employment tab of the Pay Details screen (MPPP2310).
Import Pay History Processing form (MPPP5046)

 The Import Pay History Processing screen lets you process pay history batches in bulk and schedule their processing.

By default, the screen is not visible in the payroll workspace. You can add it using the standard site map editor functionality.

Summary Area




  • Release – Perform the Release action on the selected pay history batches. When it is selected, only Open batches populated in the grid.
  • Delete – Execute the Delete Pay Run action on the selected batch. This action only populates Closed and Error batches.

Pay Group

Pay Group filter. If no Pay Group is specified, records for all pay groups are selected.


Filter is applied to the Pay Period Start Date of the batch.


Filter is applied to the Pay Period Start Date of the batch.

Table Columns




An unlabelled check box that you select to include this document for release.

Batch Number

The Import Pay History batch number.


The batch status.

External Pay Run ID

The pay run ID from the external system.

Physical Pay Date

The pay run's physical pay date.

Pay Period Start Date

The pay period start date.

Pay Period End Date

The pay period end date.

Pay Group ID

The pay group ID.

Pay Run ID

The ID of the pay run generated for this batch in MYOB Advanced.


Description for this document.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.