Integrate with Cezanne HR API

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

  • Adding Salary, non-Salary compensation 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

  • Non-Salary compensation synchronisation - add/delete/change

  • Holiday booking synchronisation - add/delete/change

  • Excluding employees based on an Contract Term

  • 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 Cezanne HR API for settings, and follow the steps below to set up.

Setup in Cezanne HR

  1. Important

    Salaries and Holidays and so on are linked to each employee via Person Code. Therefore you must assign a unique Person Code for each employee.

  2. Cezanne HR supports multiple address types, and multiple addresses of each type, but paiyroll® expects just one. To select the address used by paiyroll® and disable the multiple address capability, under Address Types, tick Overlapping Addresses not allowed for exactly one type:

    ../../../_images/setup_cezanne_hr_integration.address_type.png

    Note: this does not alter pre-existing address information. Any workers with addresses of the wrong type, or with multiple addresses in use may need to be adjusted during initial setup for compatibility with paiyroll®.

  3. Create a new Username and Password for paiyroll® use of the Cezanne HR API. Contact Cezanne HR support for a Client ID and Client Secret linked to this new username and password. You will need to specify:

    scope timeout:

    This is how often you will need to reauthenticate paiyroll® use of the Cezanne HR API. paiyroll® suggests a value of “0” which means you will never normally need to reauthenticate.

    redirect URIs:

    This is how Cezanne HR communications back to paiyroll® are secured. The redirect URIs must be set as follows:

    https://login.paiyroll.com/paiyroll/reportdefinition/oauth2/,
http://localhost:8000/paiyroll/reportdefinition/oauth2/,       <==== temporary
http://freenas:8000/paiyroll/reportdefinition/oauth2/,         <==== temporary
x-cez://oauth-callback/

    The first redirect URI is for the paiyroll® production system, and the last redirect URI is mandated by Cezanne HR.

    access:

    The API integration requires read-only access.

Pension Schemes (Benefit)

If synchronising Pension Schemes:

  • All Cezanne HR Benefit Schemes for Pensions should be named starting with the word ‘Pension’ e.g. ‘Pension AE’.

  • All Cezanne HR Benefit Types that further qualify Pensions Benefit Schemes should be named starting with the word ‘Pension’ e.g. ‘Pension RAS’, ‘Pension Net’ or ‘Pension Sal Sacrifice’.

paiyroll® Pension Schemes must be created which follow the naming convention of joining the Benefit Scheme with the Abbreviated Benefit Type:

Benefit Scheme (Abbreviated Benefit Type)

where the Abbreviated Benefit Type has the prefix ‘Pension -’ removed. Examples:

Pension Scheme Examples

Cezanne HR Benefit Scheme

Cezanne HR Benefit Type

paiyroll® Scheme Name

Pension AE - 5%ER / 3%EE

Pension - Net

Pension AE - 5%ER / 3%EE (Net)

Pension AE - 5%ER / 3%EE

Pension - Sal Sac

Pension AE - 5%ER / 5%EE (Sal Sac)

SSP, SMP and SPP Sicknesses Schemes

The following naming conventions must be followed if synchronising SSP, SMP and SPP absences:

  • The paiyroll® schemes for SSP, SMP and SPP absences must have the same name as the corresponding Cezanne HR Absence Plan Type names.

The following Cezanne HR fields MUST be completed:

  • Qualifies for Sick Pay (Tick)

  • Entitled to SMP (Tick)

  • Entitled to SPP (Tick)

  • Date notified of SMP (Add date if you have it, otherwise at least 15 weeks before the baby is expected)

  • Date notified of SPP (Add date if you have it, otherwise at least 15 weeks before the baby is expected)

Setup in paiyroll®

Add the GB Cezanne HR Report Definition using the GB Cezanne HR Template as follows:

  1. Company:

    Select the Company.

  2. 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.

  3. Client Id:

    Enter value from previous section.

  4. Client Secret:

    Enter value from previous section.

  5. Authorisation:

    From the Settings menu click the Grant button to allow paiyroll® to access Cezanne HR on your behalf. You will be taken to the Cezanne HR site, where you must enter your credentials and then allow access as required.

  6. Excluded:

    Optionally you can exclude specific employees by using Contract Term. For example to exclude all contractors, assign the value Contractor to the Contract Terms in Cezanne HR and be sure to include the value Contractor in the Excluded report setting. Multiple values are separated by a semi-colon.

  7. 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.

  8. Invite:

    You can also send a password set welcome e-mail by selecting Invite welcome email.

  9. Schedule:

    Select your schedule.

  10. Rewind:

    After an initial run, subsequent runs will only pick up changes in Cezanne HR after the previous run. Set this box to always go back 3 months.

Click Add.

For each non-Salary compensation item, a Pay Definition must be created with a name matching the CompItem. The Pay Definition must be based on the Payment or Deduction template, with Buss settings configured treatment for appropriate PAYE, NIC, pension and so on.

Pension Schemes (Benefit)

The following naming conventions must be followed if synchronising Pension Schemes (Benefit).

Scheme Pay Definitions in paiyroll® must be created and named using convention described above. For example,

Pension Scheme Pay Definition Example

Cezanne HR Benefit Scheme

Combined with Cezanne HR Benefit Type

Would need paiyroll® Scheme Pay Definition

Pension AE

Pension - RAS

Pension AE (RAS)

ditto

Pension - Net

Pension AE (Net)

ditto

Pension - Sal Sacrifice

Pension AE (Sal Sacrifice)

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, non-Salary compensation 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.

Non-Salary compensation Pay Items will be deleted and recreated on each run.

Synchronisation Overview

paiyroll® synchronises with Cezanne HR using the API as follows:

  1. 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.

  2. 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.

  3. Runs can be repeated as needed, either to fix errors, or to fetch updated information.

  4. An error-free synchronisation run should be obtained before approving a Pay Run to ensure that valid results are obtained.

  5. 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.

  6. 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 Cezanne HR 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 Cezanne HR. When a new employee is found in Cezanne HR, they will be added in paiyroll®. Otherwise existing employees are updated using the values in Cezanne HR.

The following fields are fetched from Cezanne HR 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

  • FTE

  • end_date

  • original_start_date

  • company

  • department

  • postaldetail.line1

  • postaldetail.line2

  • postaldetail.line3

  • postaldetail.line4

  • postaldetail.postcode

  • postaldetail.foreign_country

  • taxdetail.weekly_hours_worked set from workings days (or if not set will default to 0/A worked hours)

  • 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 Cezanne HR 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 Cezanne HR to NB (or anything other than other than M or F).

    This conveniently allows separation of gender in Cezanne HR and paiyroll® when required.

  • taxeedetail.NI_number

  • bankdetail.account_name

  • bankdetail.sort_code

  • bankdetail.account_number

The following fields are not available in Cezanne HR, 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 (5+2 pattern)

  • existing_employee

  • notes ()

  • 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)

Control of the following fields can be changed between Cezanne HR and paiyroll® in the report settings:

  • working_days

    • paiyroll®: Controlled by the employee working pattern

    • paiyroll®: This is set for each worker as follows. First, all 7 days are set as having zero working hours. Then the Cezanne HR’s EmployeeWorkingTimePatternDetails table is queried for non-zero entries, and for each entry, one day for one worker will be set to the non-zero value. After all the entries are processed:

      • Any day with a non-zero number of worked hours will be marked as a working day.

      • If no days are with a non-zero number of worked hours is found, the worker will be set to a 7 day working pattern.

Exclusions

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

Salary synchronisation

The Cezanne HR API 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 Cezanne HR. 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.

Synchronisation details

Cezanne HR change

paiyroll® effect

New or changed

The new salary amount will be applied from the Effective Date, backdated as needed.

Delete annual salary. This is an error; change the salary amount to zero instead.

Error.

Non-Salary compensation synchronisation

Synchronisation is by deleting and then recreating the relevant pay items on each run.

Holiday booking synchronisation

Full synchronisation of Holiday bookings. The Cezanne HR API is used with the resulting values compared with the data previously fetched into paiyroll®:

Synchronisation details

Cezanne HR 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

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.