Compass API

Overview - Compass API

Are you sure you want to remove this component?

The Compass API populates the School User Data Store (SUDS) with user profile and timetable information.

Once SUDS has been populated, the User Provisioning System (UPS) is able to run as a scheduled process for the creation of and ongoing updates to a user’s Schoolbox Profile. A user's timetable and profile page (that directly rely on the Compass API data in SUDS) will surface the most recently uploaded information as per the schema and do not require the UPS to have completed its scheduled run (though caching of data may delay this). 

NOTE: Due to the duration that the import of data can take, it is recommended that an hourly sync is NOT used.

On this page, you will find the following information:

Generating your Compass API Key

Managing the Compass API Connector

Managing the Compass API Imports

Mapping of Staff - Compass API to SUDS

Mapping of Students - Compass API to SUDS

Mapping of Parents & Relationships - Compass API to SUDS

Generating your Compass API Key

Are you sure you want to remove this component?

To access Compass' documentation on generating an API Key:

1. Navigate to your instance of Compass.

2. Append '/ApiDocs/Documentation/index.html' to the URL.

Managing the Compass API Connector

Are you sure you want to remove this component?

1. Log in to Schoolbox.

2. Navigate to Administration > School Data Import > Home.

image.php?hash=b302e431fc2690f9a41a5ef6038bf27b79de4843

3. Select data source as 'Compass'.

4. Enter your School Data Endpoint Host.

5. Choose your Import Frequency

Note: It is recommended that an import is conducted after midnight to ensure that SUDS is populated with the correct timetable day and to gather current profile data (including new starters). The completion of this import should precede the User Provisioning System’s scheduled run. An additional import before the start of the school day may be utilised to present changes made to the timetable for cover lessons and room changes that may have been made in the SIS that day. A final import after working hours can also be utilised to update any changes made by the SIS administrators that day.

6. Enter your Import Timeout.

7. Enter your Compass Configuration Key.

8. Select Save.

image.php?hash=fb58fdcd4057358ec9693c2c89b295a65c9353fe

Managing the Compass API Imports

Are you sure you want to remove this component?

To perform an update of your SUDS data from an API connector.

1. Navigate to Administration > School Data Import > Home.

image.php?hash=7c0e97888862344c840a1f18ec533fc58bc50577

2. Select the 3-dot Menu and select 'Perform Live Update'.

image.php?hash=21f4d779e9499d2f8376320a66e327ac42b7ad6a

To view your current endpoint status and the status of previous imports.

1. Scroll beyond the API configuration.

image.php?hash=df513b50c51dbe3ef79131d7407cb2573d45f780

2. Select 'current endpoint status' for a detailed view of the status of each endpoint and node as required.

NOTE: The 'Previous Imports' section will vary based upon the SIS and API configuration used. 

  • The School User Data Store (SUDS) and its Schema

Mapping of Staff - Compass API to SUDS

Are you sure you want to remove this component?

SUDS Field API Endpoint API Node
External ID person/v1/GetStaff /importIdentifiers/importIdentifier
Username person/v1/GetStaff username
Title person/v1/GetStaff title
Firstname person/v1/GetStaff firstName
Preferred Firstname person/v1/GetStaff preferredFirstName
Surname person/v1/GetStaff either preferredLastName or lastName
Email person/v1/GetStaff organisationUserEmail
Campus person/v1/GetStaff /organisationMilestones/homeCampus
Work Phone person/v1/GetStaff phoneExtension
Staff Category person/v1/GetStaff

isTeachingStaff

We hardcode:

'TEACHING_STAFF' to 'Teaching Staff' 

'NON_TEACHING_STAFF' to 'Non-Teaching Staff'

Position Title person/v1/GetStaff roleInSchool
Department person/v1/GetStaff organisationTitles
Building - -
Room person/v1/GetStaff room

Mapping of Students - Compass API to SUDS

Are you sure you want to remove this component?

SUDS Field API Endpoint API Node
External ID person/v1/GetStudents /importIdentifiers/importIdentifier
Username person/v1/GetStudents username
Title person/v1/GetStudents title
Firstname person/v1/GetStudents firstName
Preferred Firstname person/v1/GetStudents preferredFirstName
Surname person/v1/GetStudents either preferredLastName or lastName
Email person/v1/GetStudents organisationUserEmail
Date of Birth person/v1/GetStudents dateOfBirth
Gender person/v1/GetStudents gender
Mobile - -
Emergency Contact Name 1 person/v1/GetStudents /emergencyContacts/Name
Emergency Contact Phone 1 person/v1/GetStudents /emergencyContacts/contactNotes
Emergency Contact Phone Alt 1 - -
Emergency Contact Name 2 person/v1/GetStudents /emergencyContacts/Name
Emergency Contact Phone 2 person/v1/GetStudents /emergencyContacts/contactNotes
Emergency Contact Phone Alt 2 - -
Emergency Contact Name 3 person/v1/GetStudents /emergencyContacts/Name
Emergency Contact Phone 3 person/v1/GetStudents /emergencyContacts/contactNotes
Emergency Contact Phone Alt 3 - -
Campus person/v1/GetStudents /organisationMilestones/homeCampus
House person/v1/GetStudents /organisationMilestones/groupC
Head of House ID - -
Head of House Name - -
Form person/v1/GetStudents /organisationMilestones/groupA
Form Teacher ID - -
Form Teacher Name - -
Tutor Group person/v1/GetStudents /organisationMilestones/groupB
Tutor Teacher ID - -
Tutor Teacher Name - -
Year Level person/v1/GetStudents /organisationMilestones/yearLevel
Year Level Coordinator ID - -
Year Level Coordinator Name - -
Studies Code person/v1/GetStudents govtCode1 / govtCode2
Medical Alert person/v1/GetStudents medicalConditions
Comment - -
Contact Alert - -
Legal Alert - -
Enrolment Date - -
Leaving Date   -
IB - -
ILP - -
EAL - -
Special Needs person/v1/GetStudents receivesEsl
Boarding House Name    
Boarding Status person/v1/GetStudents boarderType
Photo Redacted    

Mapping of Parents & Relationships - Compass API to SUDS

Are you sure you want to remove this component?

SUDS Field     API Endpoint     API Node

External ID 

person/v1/GetParents /importIdentifiers/importIdentifier
Username person/v1/GetParents username
Title person/v1/GetParents title
Firstname person/v1/GetParents firstName
Preferred Firstname person/v1/GetParents preferredFirstName
Surname person/v1/GetParents either preferredLastName or lastName
Email person/v1/GetParents emailAddress
Mobile person/v1/GetParents mobileNumber
Home Phone person/v1/GetParents homePhoneNumber
Work Phone - -
Relationship  person/v1/GetParents relationships/type