This article explains how to set up the 'write-back' integration between Arbor and iTrent, enabling HR data, including employee details, contracts, salaries, and absences, to flow from iTrent to Arbor. It covers permissions needed, data synchronisation, field mapping, and setup instructions, ensuring iTrent serves as the single source of truth for HR data.
Permissions
- School: User Accounts: Administer - Approve the API connection
- Integrations: Administer All Integrations - Access the Integrations Administration page to set up the integration in Arbor
If you don't have the permission, you'll need to ask your admin team to give you permission using these instructions.
What is included in the integration?
The integration includes the following areas of Staff HR data:
- Staff/Employee Profile
- Staff/Employee Contract
- Staff/Employee Contract Salary
- Staff/Employee Absence
Data is synced to Arbor immediately after a change is made to one of the above areas in iTrent.
Field mapping
Staff Member
When personal details for a staff member are created or updated in the Organisation Structure> People area of iTrent, these details are updated in Arbor in accordance with the field mapping in the table.
| iTrent | Arbor API | Mandatory? |
|---|---|---|
| Title* | title | Yes |
| Forename | legalFirstName | Yes |
| Preferred Name | preferred FirstName | |
| Forename 2 | legalMiddleNames | |
| Surname | legalLastName | Yes |
| Preferred Surname | preferredLastName | |
| Sex* | gender | Yes |
| Date of birth | dateOfBirth | |
| Ethnic origin* | ethnicity | |
| Religion | religion | |
| Personal ref | staffNumber | |
| Nationality* | countryOfBirth | |
| Address Line 1 | address1 | |
| Address Line 2 | address2 | |
| Address Line 3 | address3 | |
| Address Line 4 | postalTown | |
| Address Line 5 | postalState | |
| Address Line 6 | postalCode | |
| Country | country |
*Configured with a mapping exercise in iTrent
Teacher status
Teacher status fields are all optional and are found in the Third party returns> Schoolforce status area of iTrent. Updates to these fields in iTrent result in updates to the corresponding fields in Arbor.
| iTrent | Arbor API |
|---|---|
| Qualified teacher status | qualifiedTeacherStatus |
| Qualified teacher learning and skills status | qualifiedTeacherLearningAndSkillsStatus |
| Early Years Teacher Status | earlyYearsTeacherStatus |
| QTS route | qualifiedTeacherRoute |
| HLTA Status | hltaStatus |
Contract details
These fields are found in the Organisation structure > People > Positions area of iTrent. Updates to these fields in iTrent will update the corresponding fields in the Contracts area of staff profiles in Arbor
| iTrent | Arbor API | Mandatory? |
|---|---|---|
| Job Title | contractName | Yes |
| Arbor Staff ID) | staff | |
| Type* | staffEmploymentType | |
| tparty_lnk.party_lnk_id | contractReference | |
| Occupancy Start | startDate | Yes |
| Expected occupancy end date | expectedEndDate | |
| Personal ref | payrollNumber |
*Configured with a mapping exercise in iTrent
Positions
These fields are found in the Organisation structure > People > Positions and SWF details areas of iTrent. Updates to these fields in iTrent will update the corresponding fields in Arbor.
iTrent establishes which position to use by searching the Job Title against Position Names that already exist in Arbor. If a position isn't found by name or multiple positions are found, a further search looks for positions with the same Position Category and Census Business Role. If there is still no match found, a new position will be created.
| iTrent | Arbor API | Mandatory? |
|---|---|---|
| Start Date | startDate | Yes |
| End Date | endDate | |
| Job Title | positionName | Yes |
| FTE Hours | fteHoursPerWeek | Yes |
| Contractual hours | expectedHoursPerWeek | Yes |
| [parameter value]* | expectedWeeksPerYear | Yes |
| Role Identifier | N/A | |
| Post** | positionCategory |
*Configured during initial configuration
** If the Include in return checkbox is ticked in the SWF details section of iTrent, the Arbor Position Category is populated with the data in the Post section of SWF details in iTrent
If the Include in return checkbox is not ticked in the SWF details section of iTrent, the Arbor Position Category is populated with “Not included in School Workforce Census (XXX)” and the contract will be discounted from the Workforce Census - more on that here: Excluding staff or contracts from the Workforce Census
Contract Post Details
These fields are found in the Organisation structure > People > Positions area of iTrent. Updates to these fields in iTrent will update the corresponding fields in the Contracts area of staff profiles in Arbor
| iTrent | Arbor API | Mandatory? |
|---|---|---|
| Arbor Staff contract href | staffContract | Yes |
| Job Title | jobTitle | |
| Arbor Position href) | position | Yes |
| tparty_lnk.party_lnk_id | postReference | Yes |
| Occupancy Start | startDate | Yes |
| Expected occupancy end date | expectedEndDate | |
| Role Identifier | N/A |
Contract Post Salary
These fields are found in the Organisation structure > People > Positions area of iTrent. Updates to these fields in iTrent will update the corresponding fields in the Contracts area of staff profiles in Arbor
| iTrent | Arbor API |
|---|---|
| Arbor ContractPost href | staffContractPost |
| Personal ref | payrollNumber |
| Payscale Value | payScale |
| Arbor spinal point href | payScaleSpinalPoint |
| FT Salary | grossSalary |
| Contractual hours | hoursPerWeek |
| FTE hours | fteHoursPerWeek |
| Annual weeks worked | weeksPerYear |
| [parameter value]* | fteWeeksPerYear |
| Positions Salary details > Effective date | effectiveDate |
| Positions Salary details > Effective End date | endDate |
*Configured during initial configuration
Staff Absence - iTrent to Arbor System
These fields are found in the Organisation structure > People > All absences list > Absence details section of iTrent. When absences are added, updated or deleted in iTrent, the corresponding fields are added or amended in Arbor as if you were creating or amending an absence for a staff member in Arbor.
| iTrent | Arbor API | Mandatory? |
|---|---|---|
| Arbor Staff href | staff | Yes |
| Personal ref | staffContract | Yes |
| Absence start date* | startDatetime | |
| Absence end date | endDatetime | |
| Absence type | staffAbsenceCategory | Yes |
| Absence reason | sicknessCategory |
Staff Absence - Arbor to iTrent
When absences are created, changed or deleted in Arbor, the corresponding fields are updated in the Organisation structure > People > All absences list > Absence details area of iTrent.
| Arbor | iTrent API | Mandatory? |
|---|---|---|
| Arbor Staff ID | personal_reference | Yes |
| Start date/time | startDate | Yes |
| N/A* | iTrentStartType | Yes |
| End date/time | endDate | |
| N/A* | iTrentEndType | |
| Sickness category** | staffAbsenceCategory | Yes |
| Sickness subcategory** | sicknessCategory | Yes |
*Derived from iTrent AM/PM/Full and Arbor. For partial absences:
- If they start after the start of the morning session but before the afternoon, the type is HALF_AM.
- If they start after the start of the afternoon session, the type is HALF_PM.
**Configured with a mapping exercise in iTrent
Fields that don't populate via the integration
Some fields in Arbor cannot be populated through the integration with iTrent. This means that you are not able to add these details to Arbor via iTrent. The table below gives an overview of those fields. The left column shows the area of Arbor where the field can be found. The right column specifies the name of the field.
| Area in Arbor | Arbor field |
|---|---|
| Teacher status | Newly Qualified Teacher Date |
| Contract details | Issued Date |
| Contract details | Staff Origin |
| Contract details | Superannuation Scheme |
| Contract details | Last Pay Review Date |
| Positions | Position Reference |
| Positions | Supervisor Position |
| Contract Post Details | Offered Date |
| Contract Post Details | Accepted Date |
| Contract Post Details | Start Reason |
| Contract Post Details | Expected End Reason |
| Contract Post Salary | Pay Scale Grade |
| Contract Post Salary | Safeguarded Period Start Date |
| Contract Post Salary | Safeguarded Period End Date |
| Staff Absence | Sickness Subcategory |
| Staff Absence | Sickness Subcategory |
Before setting up the integration
-
Check Positions - As iTrent establishes which position to use by searching the Job Title in iTrent against Position Names that already exist in Arbor. If a position isn't found by name or multiple positions are found, a further search identifies positions with the same Position Category and Census Business Role. If no match is found, a new position will be created.
Ensure Position Job Titles in iTrent are matched to the Position list in Arbor, and use unique names for positions where possible to avoid duplication and ensure consistency.
See how to manage Positions here: Setting Positions, Position Categories and Census Business Roles for the Workforce Census. -
Check business roles - Ensure the Business Role in Arbor links to the Position so staff are assigned a Business Role. If they are not, the write-back sync will succeed, but the staff member won’t be visible in the current staff list in Arbor. Staff Positions in Arbor can be linked to Business Roles from the same positions page as detailed in the article linked above.
- If you would like the iTrent integration to automatically assign a business role to staff profiles created by the sync, Staff Positions in Arbor can be linked to Business Roles from the same positions page as detailed in the article linked above.
- If you want to manually assign business roles or permissions in Arbor, new staff added via iTrent won't appear in current staff lists and won't be able to log in until they are given a business role: Adding a Business Role to a member of staff.
- Consider restricting permissions - As Staff profile data and Absence data can be controlled in iTrent when the integration is enabled, consider restricting users’ permissions to edit these areas in Arbor if you only want this to be managed in iTrent. You can do this by removing the permissions associated with a Business Role.
- Apply for test site access - Contact Arbor to discuss the provisioning of a test site and associated cost. Typical lead time for test site provision is 1-2 weeks. A specified school’s dataset is copied into the test site for testing purposes. The integration can then be enabled in your test site via a request to Arbor Support.
Setting up the integration
- Request that the integration be enabled by speaking to your MHR Account Manager
- iTrent will send the request to your Arbor site. You can approve the integration from System > Partner Apps (API Users): Setting up and managing 3rd Party API Integrations
Checking for a Successful Write Back
In Arbor, you can check for a successful write-back by looking at the Staff Profile and checking that the employee data from iTrent has either been added or updated in Arbor.
- To see all staff absence data in Arbor, follow this article: Staff Absences
- Absence data sent to Arbor can then be used to manage staff cover. Follow this article: Manage cover
Using the integration in Arbor
Once enabled in iTrent, all existing employees will be linked to the corresponding staff record in Arbor. This creates the Arbor ID in the background, which serves as the unique identifier for subsequent edits to this data in iTrent.
- Updated staff details in iTrent will automatically pull through to Arbor.
- Absences entered into iTrent will be immediately available in Arbor for cover purposes.
- Absences entered into Arbor will be immediately available in iTrent
Important things to note:
- The direction in which absences are synced depends on how the absence's type has been configured. Depending on your configuration, absences may not all be synced in both directions.
- It is possible to record staff details in Arbor directly. It isn't possible to disable this, so please advise your staff to update staff details that do not sync from Arbor in iTrent to ensure data is synced across both systems.
Further Support
For support with your integration, please contact the iTrent Support Team on 0115 945 6000.
The iTrent team will contact Arbor’s API Support Team directly if needed.
FAQ
With this new write-back integration, iTrent is treated as the controlling system for Staff/HR/Salary/Absence data.
The School Workforce Census can be completed in either Arbor or iTrent
Pay Scales need to be updated in both Arbor and iTrent
Data is synced to Arbor immediately after a change is made in iTrent
Comments
Article is closed for comments.