Integrate with PeopleHR API¶

Follow this guide to set up the PeopleHR API integration which uses an automated data-feed. The integration is capable of updating paiyroll® as follows:

Adding Salary and Holiday Pay Items after running an import
Updating existing employees
Adding new employees
Using a Test employee to add company Pay Items when adding new employees
Salary synchronisation - add/delete/change including future and backdated pay changes
Holiday booking synchronisation - add/delete/change
Recurring Benefit synchronisation
Single Payment synchronisation
Single Deduction synchronisation
Pension synchronisation
Excluding employees based on an Employment Type
Excluding future starters that may only be partially defined e.g missing date of birth
Excluding historical leavers who were never imported.
Automatically run once during the payroll prompt window for each cycle
The integration is designed to be run as often as required, manually or automatically

See GB PeopleHR API for settings, and follow the steps below to set up.

Setup in PeopleHR¶

Important

Salaries and Holidays are linked to each employee via Employee ID. Therefore you must assign a unique Employee ID for each employee. If you do not need Salary and/or holiday updates, then you can skip these steps.

Salary Query:: From the Queries menu add a new query using the + plus button as below:

Paiyroll Sync Salary query¶
Name & Description	Selected Areas (Left)	Selected Areas (Right)	Filtering
Paiyroll Sync Salary	Employee Details	Employee Id	No filtering
	Salary Details	Salary Effective Date
		Salary Amount
		Salary Updated Date
		Salary Created Date
		Is Deleted?

Holiday Query:: From the Queries menu add a new query using the + plus button as below:

Paiyroll Sync Holiday query¶
Name & Description	Selected Areas (Left)	Selected Areas (Right)	Filtering
Paiyroll Sync Holiday	Employee Details	Employee Id	Holiday Type = “Holiday” and Does not equal “Public holidays Inclusive”
	Holidays	Holiday Start Date	Holiday Status = “Approved”
	Leavers	Holiday End Date	Optionally exclude holidays starting prior to your payroll migration date
		Holiday Type
		Start Date Part of the Day
		Part of the Day
		End Date Part of the Day
		Holiday Comments
		Holiday Status
		Authorisation Comments
		Holiday Updated DateTime
		Deleted Holiday

Recurring Benefit query:
From the Queries menu add a new query using the + plus button with Name set to Paiyroll Sync Benefit and columns as per Recurring Benefit synchronisation.
Single Payment query:
From the Queries menu add a new query using the + plus button with Name set to Paiyroll Sync Payment and columns as per Single Payment synchronisation.
Single Deduction query:
From the Queries menu add a new query using the + plus button with Name set to Paiyroll Sync Deduction and columns as per Single Deduction synchronisation.
Pension query:
From the Queries menu add a new query using the + plus button with Name set to Paiyroll Sync Pension and columns as per Pension synchronisation.
API:
From the Settings menu select API and click the + plus button to add a new API Key. Give the key a suitable name e.g. paiyroll API key. Optionally you can use login.paiyroll.com as the IP address. Then click the Employee and select Get All Employee Detail. The API key must also be configured to enable access to Querybuilder for the 2 queries added above. Ensure you Save the key. Copy the key using the copy icon for entry below.

Setup in paiyroll®¶

Add the GB PeopleHR Report Definition using the GB PeopleHR Template as follows:

Company:
Select the Company.
Dry run:
We recommend you always set Dry run first to ensure everything works as expected. If this is set, no actual update will occur but you will be able to verify what would change if the operation were allowed to complete. Also some errors become warnings.
Add from:
Select a Test (template) worker to automatically add Pay Items to new workers using Add from. Be sure to add a Salary Pay Item to the test employee and a Holiday Pay Item. Ensure the schemes are set appropriately.
Invite:
You can also send a password set welcome e-mail by selecting Invite welcome email.
API key:
Copy the API key created above into API key
Confirm:
Repeat the API key.
Salary query:
The Salary query must mach the query name used above.

Note

If you want to disable Salary updates, then leave the query name blank.
Holiday query:
Holiday query must mach the query name used above.

Note

If you want to disable Holiday updates, then leave the query name blank.
Recurring Benefit query and column mapping
Recurring Benefit query must mach the query name used above.

Note

If you want to disable Recurring Benefit updates, then leave the query name blank.

Recurring Benefit column mapping. See Recurring Benefit synchronisation.
Single Payment query and column mapping
Single Payment query must mach the query name used above.

Note

If you want to disable Single Payment updates, then leave the query name blank.

Single Payment column mapping. See Single Payment synchronisation.
Single Deduction query and column mapping
Single Deduction query must mach the query name used above.

Note

If you want to disable Single Deduction updates, then leave the query name blank.

Single Deduction column mapping. See Single Deduction synchronisation.
Pension query and column mapping
Pension query must mach the query name used above.

Note

If you want to disable Pension updates, then leave the query name blank.

Pension column mapping. See Pension synchronisation.
Excluded:
Optionally you can exclude specific employees by using Employment Type. For example to exclude all contractors, assign the value Contractor to the Employment Type in PeopleHR and be sure to include the value Contractor in the Excluded report setting. Multiple values are separated by a semi-colon.
Schedule:
Select your schedule.

Click Add. The API key and queries will be validated in PeopleHR and you will have the opportunity to correct any errors.

Integration details¶

Migration¶

You can use the data-feed after migrating data with one of the importers. This is a quick way to add Salary and Holiday Pay Items. Be sure to specify a Test employee.

If you run the integration with existing employees, and you have added a Salary Pay Item to the Test employee, then a Salary Pay Item will be added to each employee with an annual salary. Holiday will work in a similar way.

Synchronisation Overview¶

paiyroll® synchronises with PeopleHR using the API as follows:

On first run, as well as the information required for the current pay run, it is necessary to fetch historical information. The historical information needed can be very bulky, and therefore slow. If the run encounters errors, this first run will need to be redone.
Once the first run completes without errors, later runs do not need to fetch the historical information. If a later run encounters errors, it will need to be redone.
Runs can be repeated as needed, either to fix errors, or to fetch updated information.
An error-free synchronisation run should be obtained before approving a Pay Run to ensure that valid results are obtained.
Where salaries are synchronised, until the first run completes without errors:
- Backdated salary changes are assumed to be the current salary and no changes are calculated.
- In-period salary changes will change from the salary that pre-dates the pay period.
When the the first run succeeds:
- A base salary is established, and dated changes will then operate as intended relative to this salary.
Where Absences are synchronised, subsequent runs can be faster as Absences may be saved even if there are other errors.

Once a clean synchronisation run is obtained on a given date “HWM”, and a subsequent Pay Run is approved, later synchronisation runs may only fetch changes made in PeopleHR since HWM.

Note

This can be overriden using the Rewind setting.

Different types of information are synchronised in different ways as described in the following sections.

Employee synchronisation¶

Employees are matched by username in paiyroll® and email in PeopleHR. When a new employee is found in PeopleHR, they will be added in paiyroll®. Otherwise existing employees are updated using the values in PeopleHR.

The following fields are fetched from PeopleHR and will always overwrite values in paiyroll® for new or updated workers:

email
title
name
mobile (or if not set will default to +447700000000)
works_id
start_date
end_date
original_start_date
company
department
postaldetail.line1
postaldetail.line2
postaldetail.line3
postaldetail.line4
postaldetail.postcode
postaldetail.foreign_country
taxeedetail.date_of_birth
taxeedetail.gender
Note

HMRC require gender to be set as M or F for every employee. Therefore:
- You must set gender in PeopleHR to M or F on initial Import or data-feed and for new employees to avoid a validation error.
- Subsequently, you can set gender in PeopleHR to Not Specified
This conveniently allows separation of gender in PeopleHR and paiyroll® when required.
taxeedetail.NI_number
bankdetail.account_name
bankdetail.sort_code
bankdetail.account_number

The following fields are not available in PeopleHR, so when a new employee is added, default values (in parentheses below) are used. It is then assumed that these values will be updated and maintained in paiyroll® and therefore re-running the data-feed will not update these values:

username (email, with a number suffix if not unique)
is_active (True)
mobile (only if not set will default to +447700000000)
preferences (default)
working_days (Mon, Tue, Wed, Thu, Fri)
existing_employee (Existing if started before pay period first day)
taxdetail.weekly_hours_worked (D)
taxdetail.P45_tax_code ()
taxdetail.P45_week1_month1 (False)
taxdetail.P45_leaving_date ()
taxdetail.P45_total_pay_to_date ()
taxdetail.P45_total_tax_to_date ()
taxdetail.P45_continue_student_loan (0)
taxdetail.P45_continue_postgraduate_loan (False)
taxdetail.NI_category (General)
taxdetail.director (False)
taxdetail.director_from ()
taxdetail.director_NI_cumulative (False)
taxdetail.paid_irregularly (False)
taxdetail.off_payroll_worker (False)
taxdetail.migrated_rti_payid ()
taxeedetail.employee_statement ()
taxeedetail.student_loan (0)
taxeedetail.postgraduate_loan (False)
bankdetail.payment_method (All)

Salary synchronisation¶

The PeopleHR query is used to fetch salary details and update Salary Pay Items. If an employee has a Salary Pay Item, this will be updated with base salary.

If an employee does not have a Salary Pay Item, but it does exist on the specified Test Worker, it will be copied onto each employee with an Annual Salary in PeopleHR. The annual salary value will be set.

If there is no Salary Pay Item on an employee or Test Worker, or a Test Worker is not selected, then Salary synchronisation will not occur.

Holiday booking synchronisation¶

Full synchronisation of Holiday bookings. A PeopleHR query is used with the resulting values compared with the data previously fetched into paiyroll®:

Synchronisation details¶
PeopleHR approved holiday booking	paiyroll® holiday booking starts before Pay Period Start	paiyroll® holiday booking starts on or after Pay Period Start
New or changed	Add new booking	Add new booking
Created, then deleted in-between data-feeds
Unchanged
Deleted	Error	Deleted
Edited end and/or start date(s) and/or deleted	Error	Deleted

Recurring Benefit synchronisation¶

To synchronise Recurring Benefits, a PeopleHR query is used with a set configurable set of query fields. These must be mapped to fixed column names in paiyroll®. In the table below the default query field name is taken from the out-of-the box configuration, but in practice, the PeopleHR configuration can be extended in very flexible ways, and Configurable queries describes how the field-to-column mapping can be configured in paiyroll® to support this.

Synchronisation details¶
paiyroll® column	Default PeopleHR query field
EmployeeId	“Employee Id”	Implicitly set, cannot be changed.
BenefitName	“Benefit Type”	Typically set to the name of a Managed List, better known as dropdown. Must match a paiyroll® Payment, Deduction or NetToGross Pay Definition name.
EffectiveFrom	“Benefit Date Awarded”	The starting date of the benefit.
EffectiveTo	“Benefit Date Expiry”	The ending date of the benefit, or blank for open ended.
Value	“Benefit Value”	The per-pay period value.
LastModified	“Benefit Approved Date”	If you do not use an approval process, omit this entry.

Here is a complete example of a Benefit setup. Let’s assume:

PeopleHR defines Benefits using:
- A field called Benefit Type which is set to a dropdown with values “Cycle Scheme” and “Dental Plan”.
- A field called Benefit Value which is set to when Benefit Type is “Cycle Scheme”, and another field called Employer contribution which is set when Benefit Type is “Dental Plan”.
paiyroll® defines corresponding Pay Definitions with names like “Cycle Scheme” and “Dental Plan”. So, the column configuration for “BenefitName” is simply:
```
Benefit Type
```
but “Value” is:
```
{Benefit Value} or {Employer contribution}
```
This approach assumes that the convention for setting these values has been diligently applied. A second, “safer” but more clumsy approach, is:
```
{Benefit Value} if {Benefit Type} == 'Cycle Scheme' else {Employer contribution}
```
A third approach is to use the builtin one() which will raise an error unless exactly one value is set:

one({Benefit Value},{Employer contribution})

This is the recommended approach where/once the PeopleHR data is clean.

So the complete Benefit query column mapping looks like this:

{
    "BenefitName": "Benefit Type",
    "EffectiveFrom": "Benefit Date Awarded",
    "EffectiveTo": "Benefit Date Expiry",
    "Value": "{Benefit Value} or {Employer contribution}"
}

Single Payment synchronisation¶

To synchronise Single Payments from PeopleHR Ad-hoc Entitlements, a PeopleHR query is used with a set configurable set of query fields. These must be mapped to fixed column names in paiyroll®. In the table below the default query field name is taken from the out-of-the box configuration, but in practice, the PeopleHR configuration can be extended in very flexible ways, and Configurable queries describes how the field-to-column mapping can be configured in paiyroll® to support this.

Synchronisation details¶
paiyroll® column	Default PeopleHR query field
EmployeeId	“Employee Id”	Implicitly set, cannot be changed.
BenefitName	“Ad-hoc Pay Entitlement Type”	Typically set to the name of a Managed List, better known as dropdown. Must match a paiyroll® Payment or NetToGross Pay Definition name.
EffectiveFrom	“Ad-hoc Pay Entitlement Payment Date”	The payment is made in the pay period containing this date.
Value	“Ad-hoc Pay Entitlement Amount”	The payment value.
LastModified	“Approved Date (Ad-hoc Pay Entitlement)”	If you do not use an approval process, omit this entry.

Single Deduction synchronisation¶

To synchronise Single Payments from PeopleHR Ad-hoc Deductions, a PeopleHR query is used with a set configurable set of query fields. These must be mapped to fixed column names in paiyroll®. In the table below the default query field name is taken from the out-of-the box configuration, but in practice, the PeopleHR configuration can be extended in very flexible ways, and Configurable queries describes how the field-to-column mapping can be configured in paiyroll® to support this.

Synchronisation details¶
paiyroll® column	Default PeopleHR query field
EmployeeId	“Employee Id”	Implicitly set, cannot be changed.
BenefitName	“Ad-hoc Pay Deduction Type”	Typically set to the name of a Managed List, better known as dropdown. Must match a paiyroll® Deduction Pay Definition name.
EffectiveFrom	“Ad-hoc Pay Deduction Payment Date”	The payment is made in the pay period containing this date.
Value	“Ad-hoc Pay Deduction Amount”	The deduction value.
LastModified	“Approved Date (Ad-hoc Pay Deduction)”	If you do not use an approval process, omit this entry.

Pension synchronisation¶

To synchronise Pensions, a PeopleHR query is used with a set configurable set of query fields. These must be mapped to fixed column names in paiyroll®. In the table below the default query field name is taken from the out-of-the box configuration, but in practice, the PeopleHR configuration can be extended in very flexible ways, and Configurable queries describes how the field-to-column mapping can be configured in paiyroll® to support this.

Synchronisation details¶
paiyroll® column	Default PeopleHR query field
EmployeeId	“Employee Id”	Implicitly set, cannot be changed.
SchemeName	“Benefit Type”	Typically set to the name of a Managed List, better known as dropdown. Must match a paiyroll® Pension Scheme Pay Definition name.
EffectiveFrom	“Benefit Date Awarded”	The starting date of the benefit.
EffectiveTo	“Benefit Date Expiry”	The ending date of the benefit, or blank for open ended.
Value	“Benefit Value”	The value is treated as the worker’s percentage contribution.
LastModified	“Benefit Approved Date”	If you do not use an approval process, omit this entry.

Here is a complete example of a Pension setup. Let’s assume:

PeopleHR defines Pensions using:
- A field called Pension Type which is set to a dropdown with values “Salary Sacrifice” and “Net”.
- A field called Pension Level which is set to values like “3-5years EE 5% ER 6%”.
paiyroll® defines corresponding Pension Schemes with names like “Aviva Net 5”, “Aviva Net 6”, “Aviva Net 7”, “Aviva Sal 5”, “Aviva Sal 6” and “Aviva Sal 7”. So, the column configuration for “SchemeName” is:
```
'Aviva ' + ('Sal ' if {Pension Type}.startswith('Sal') else 'Net ') + {Pension Level}.rsplit(maxsplit=1)[-1][1:]
```
and “WorkerPercent” is:
```
{Pension Level}.rsplit(maxsplit=3)[-3][1:]
```

So the complete Pension query column mapping looks like this:

{
    "SchemeName": "'Aviva ' + ('Sal ' if {Pension Type}.startswith('Sal') else 'Net ') + {Pension Level}.rsplit(maxsplit=1)[-1][1:]",
    "EffectiveFrom": "Benefit Date Awarded",
    "EffectiveTo": "Benefit Date Expiry",
    "WorkerPercent": "{Pension Level}.rsplit(maxsplit=3)[-3][1:]"
}

Configurable queries¶

It is common for Recurring Benefits, Single Payments, Single Deductions and Pensions to be customised in PeopleHR using fields other than the defaults. To support this:

The name of the query can be configured as needed (or set to blank to disable synchronisation).

The fields returned by the query can be converted to the needed columns using a mapping defined as follows:

columns             ::= '{' column-definition [',' column-definition]... '}'

column-definition   :: output-column: column-spec

column-spec         ::= The |PARTNER| name of the field |
                        fmt-expression

output-column       ::= The |PRODUCT_NAME| column.

fmt-expression      ::= A Python format string which is also a Python
                        expression.

The fmt-expression is a Python format string which can include fixed text (such as whitespace) and field text using PeopleHR query field names {}, for example {Employee Id}.

The fmt-expression also allows limited processing of the field text. For example:

Example fmt-expression usage¶
fmt Usage	Description
`{Employee Id} + ' XYZ'`	Extract the “Employee Id” field and combine it with fixed text “ XYZ”.
`{First name[0]}`	Extract the “First name” field, and use its first letter only.
`\{AccountNumber:>08}`	Extract the “AccountNumber” field, zero fill to a width of 8, and add a preceding (single) “\\”.

The result of the fmt-expression is always stripped of any leading and trailing whitespace. The fmt-expression is then evaluated. The expression can also use:

A variable called “_” initialised with the result of fmt.
Variables called “_1”, “_2”, etc. initialised with the result of each placeholder in fmt.
Most standard Python builtins, plus re, string, unicodedata, datetime from datetime and utc from datetime.timezone
A builtin one() which is like all() or any() but requires exactly one set value.

For example:

Example fmt-expression usage¶
fmt-expression evaluation	Description
`{StartDate} -> str(datetime.strptime(_, '%d/%m/%Y').date())`	Extract the “Date” cell, parse it as %d/%m/%Y datetime, extract the date portion, and convert it into a string (in the default format, yyyy-mm-dd).
`{Benefit Value} or {Employer Contribution (Benefits)}`	Finds the first of “Benefit Value” or “Employer Contribution (Benefits)” which is set and returns it.

The result of the evaluation is NOT further normalised.

Exclusions¶

All employees specifically excluded by Employment Type will not be added and will be ignored for updates.

Future starters with a start date after the Pay period last date will be excluded. This it to allow for incomplete employee setup where bank details or date of birth may not be known.

Historical leavers with a leave and start date before the pay period first date who do not exist in paiyroll® will also be excluded.

Operating the Integration¶

You can run the integration anytime in My data feeds by clicking Start. Payroll Debbie uses the pay schedule related settings to automatically run the integration..

Click the View button to see a log of the changes made.