Integrate with StaffSavvy API¶

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

Adding Salary, Shift 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
Shift loading
Holiday booking synchronisation - add/delete/change
Excluding employees based on a Contract 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 StaffSavvy API for settings, and follow the steps below to set up.

Setup in StaffSavvy¶

Important

Salaries, Shifts and Holidays are linked to each employee via Works ID. Therefore you must assign a unique Works ID for each employee.

The integrations uses reports to fetch worker and salary information. StaffSavvy has a highly customisable approach to reports, but for ease of use, the following predefined templates should be used:
Refer to the StaffSavvy Guide to Setting up Paiyroll for details. If you are unable to use these predefined templates, refer to StaffSavvy support, who have detailed instructions on your options.
Edit the “Paiyroll Worker Export” report. Go to Remote API Access ‣ More ‣ View details and copy the URL. If you cannot see the URL, use New Remote Access.
Edit the “Paiyroll Salaries Report” report. Go to Remote API Access ‣ More ‣ View details and copy the URL. If you cannot see the URL, use New Remote Access.
Identify user, e.g. “Paiyroll API”, to be granted API access.
As the identified user, e.g. “Paiyroll API”, go to My Profile ‣ Edit <user> Details ‣ My API access. Under “Access Key”, use the blurred-out “Create New Credentials”, and copy the two values:
```
API User    000000000000000
API Key     0000000000000000000000000000000000000000
```

Holiday Schemes¶

The following naming conventions must be followed if synchronising Holiday absences:

The paiyroll® schemes for Holiday absences must have the same name as the corresponding StaffSavvy Absence Reasons.

Setup in paiyroll®¶

Add the GB StaffSavvy Report Definition using the GB StaffSavvy 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.
API User:
Enter value from previous section.
API Key:
Enter value from previous section.
Add from:
Select a Test (template) worker to automatically add Pay Items to new workers using Add from.
Sync from:
Select a Test (template) worker to automatically add Pay Items to new workers for salaries and absences. 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.
Excluded:
Optionally you can exclude specific employees by using Contract Type. For example to exclude all contractors, assign the value Contractor to the Employment Type in StaffSavvy 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.
Rewind:
After an initial run, subsequent runs will only pick up changes in StaffSavvy after the previous run. Set this box to always go back 3 months.
Worker Report URL:
Enter value from previous section:
Salary Report URL:
Enter value from previous section.
Shifts:
Shift pay items e.g. Shift {shift_number}. Clear to disable Shift fetch. Set the Display as input on the first Pay Definition (“Shift 1” in this example) to customise how shifts are displayed in a Payslip.
Shift approvals:
Set if Shifts must be approved.
Enable Holidays:
Clear to disable Holidays.
Holiday approvals:
Set if Holidays must be approved.

Click Add. The API key and queries will be validated in StaffSavvy 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 StaffSavvy 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 StaffSavvy 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 StaffSavvy. When a new employee is found in StaffSavvy, they will be added in paiyroll®. Otherwise existing employees are updated using the values in StaffSavvy.

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

email
title
name
mobile (or if not set will use value in paiyroll®)
preferences
works_id (will be defaulted from StaffSavvy ID if no workers have this set)
start_date
working days (“-” is taken as all 7 week days, else “am” and “pm” are OR’d)
FTE (or if not set will use value in paiyroll®)
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 StaffSavvy 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 StaffSavvy to Not Specified
This conveniently allows separation of gender in StaffSavvy and paiyroll® when required.
taxeedetail.NI_number
bankdetail.account_name
bankdetail.sort_code
bankdetail.account_number
bankdetail.payment_method

The following fields are not available in StaffSavvy, 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)
existing_employee
notes ()
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)

Salary synchronisation¶

The StaffSavvy 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 StaffSavvy. 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. The StaffSavvy API is used with the resulting values compared with the data previously fetched into paiyroll®:

Synchronisation details¶
StaffSavvy 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

The Holiday schemes in paiyroll® are mapped by name to the StaffSavvy AbsencePlanTypeName.

Exclusions¶

All employees specifically excluded by Contract 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 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.