School Data Import and the School User Data Store (SUDS)

The School User Data Store (SUDS) works as an intermediary between your Student Information System (SIS) and your Schoolbox instance. It is needed when Schoolbox is unable to integrate directly into the SIS in order to bring over user profile and timetable information.

Some SIS can be connected via API to automatically pull data directly into SUDS periodically, some may have connectivity indirectly via the Wonde API, and some will require a CSV to be manually populated. Manually populated CSVs may be uploaded manually via the User Interface or automatically via the Bulk API. Regardless of if SUDS is populated automatically or manually, it is in populating the database utilising the schema detailed below and is available to be used and downloaded in CSV format.

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 SUDS data) will surface the most recently uploaded information as per the schema and does not require the UPS to have completed its scheduled run (though caching of data may delay this). 

Note: Fields not marked as required can be safely left out, especially if you have privacy concerns.

On this page, you will find the following information:

Managing the School User Data Store (SUDS) 

Managing the School User Data Store (SUDS) API Imports

School User Data Store (SUDS) Schema - Staff

School User Data Store (SUDS) Schema - Students

School User Data Store (SUDS) Schema - Parents

School User Data Store (SUDS) Schema - Relationships

School User Data Store (SUDS) Schema - Schedule Based Timetable

School User Data Store (SUDS) Schema - Timetable Events

School User Data Store (SUDS) Schema - Timetable Classes

School User Data Store (SUDS) Schema - Timetable Involvements

School User Data Store (SUDS) Schema - Timetable Enrolments

School User Data Store (SUDS) Schema - Cyclic Grid (Legacy)

School User Data Store (SUDS) Schema - Timetable Structure

School User Data Store (SUDS) Schema - Timetable Template

  • SUDS Data Sources
  • Compass API
  • CSVs: UI and Bulk
  • iSAMS API
  • LISS API
  • Kamar API
  • Sentral API
  • TASS API
  • Veracross API
  • Wonde API

Managing the School User Data Store (SUDS)

Are you sure you want to remove this component?

To begin using the School User Data Store, you must follow the steps below.

  1. Go to Administration > System Settings > External DB.
     
  2. In the ‘Database Provider’ drop-down, select Schoolbox.
    image.php?hash=76c8a120d124302f06c94af21fea24ac69597024
     
  3. Select Save.
    ‘School Data Import’ will now appear in the Administration Menu.
Back To Top

Managing the School User Data Store (SUDS) API Imports

Are you sure you want to remove this component?

Schoolbox gives you more control over how you import data using School User Data Store (SUDS) from an API connector into Schoolbox. You can now import specific groups of data - like user profile data, timetable data - separately, instead of all at once.

This will help you when you want to make small updates or test new data without affecting everything in your system.

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

  1. First, ensure you have enabled school data import for your school. See Managing the School User Data Store (SUDS). 
     
  2. Next, go to Administration > School Data Import > Home.
    This opens the school data import home page for you. 
     
  3. Then, select the 3-dot menu icon3-dot Menu Iconand select one of the following:
    • Update user data and timetables
    • Update user data only
    • Update timetable only
  4. For each, select Save to proceed with the import.
     
  5. Next, in Daily Org Import Time, enter the specific time of day when you want your school’s timetable data to be automatically imported into Schoolbox from your external system.
    Note: This runs every day of the week.
    This scheduled import ensures that any timetable updates made in your source system are reflected in Schoolbox each day.
    Timetable data updates are not immediate. They typically take around 15–20 minutes to appear in Schoolbox, though in some cases, it may take longer.
    Note: This field only affects the import of timetable data.
     
  6. To view your current endpoint status and the status of previous imports, scroll beyond the API configuration: image.png
     
  7. 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 on the SIS and API configuration used. 
Back To Top

School User Data Store (SUDS) Schema - Staff

Are you sure you want to remove this component?

FieldTypeExampleDescription
External IDString(64) (required)321This is the unique identifier you use across your timetable and systems to identify this user
TypeEnum(‘Staff’) (required)StaffIdentifies this row in the CSV as a staff, is not stored.
UsernameString(255) (required)abrock 
TitleString(255)Mr 
FirstnameString(255)AnthonyThe person's formal/legal firstname
Preferred FirstnameString(255)Ant 
SurnameString(255)Brock 
EmailString(255)abrock@schoolbox.cloud 
CampusString(255)Senior 
Work PhoneString(45)+0011 92303234 434 
Staff CategoryString(255)TeacherUsed to denote the difference between Teaching and Non-Teaching staff such as librarians, counsellors, IT admin, etc.
Position TitleString(255)Head of English 
DepartmentString(255)English 
BuildingString(255)Building 1 
RoomString(255)A11 

 

Back To Top

School User Data Store (SUDS) Schema - Students

Are you sure you want to remove this component?

Field

Type

Example

Description

External ID

String(64) (required)

54362

This is the unique identifier you use across your timetable and systems to identify this user

Type

Enum(‘Student’) (required)

Student

Identifies this row as a student record, other imports will use different values for this field

Title

String(255)

Mr

  

Firstname

String(255)

Tristian

The person's formal/legal firstname

Preferred Firstname

String(255)

Tris

  

Surname

String(255)

Baker

  

Username

string(255) 

tbaker

Usually corresponds to some kind of authentication in a SIS; schools can configure their own usernames via UPS

Email

String(255)

tbaker@school.cloud

The primary email address to use for correspondence. Schools can configure their own email addresses via UPS.

Gender

String(25)

M

Free string to indicate preferred gender identity

Mobile

String(45)

23345435

  

Date of Birth

Date (ISO 8601)

1998-02-02

  

Campus

String(255)

Senior

  

House

String(255)

Red

  

Head of House ID

String(64)

2446

  

Head of House Name

String(255)

Mr Smith

  

Form

String(255)

6th Form

  

Form Teacher ID

String(64)

3456

  

Form Teacher Name

String(255)

Mr Barlow

  

Tutor Group

String(255)

8B

  

Tutor Teacher ID

String(64)

192837

  

Tutor Teacher Name

String(255)

Mr Andrews

  

Year Level

String(255)

Year 8

  

Year Level Coordinator ID

String(64)

7546

  

Year Level Coordinator Name

String(255)

Mrs Jane Gooding

  

Studies Code

String(45)

IB34563

A global student identifier for reporting back to central authority

Medical Alert

String(1024)

Allergic to peanuts

Simple medical alert displayed to all teachers 

Comment

String(1024)

  

Overall comment about the student shown to all teachers

Contact Alert

String(1024)

  

Information relevant to the students contact, like which contacts are preferred

Legal Alert

String(1024)

  

Alert teachers if there are any current legal orders in place

Enrolment Date

Date (ISO 8601)

2012-01-01

Date student started at school

Leaving Date

Date (ISO 8601)

2020-04-02

Date student leaves the school

IB

Bool

1

Are they studying IB International Baccalaureate

ILP

Bool

0

Does this student have an ILP Individualised Learning Plan, or special requirements

ESL

Bool

0

Does this student speak english as a second language

Special Needs

Bool

0

Does this student have any disabilities that may impact learning

Boarding Status

Bool

1

Is the student a boarder at the school

Boarding House Name

String(255)

Cuthbertson

The name of a student's boarding house, if applicable

Emergency Contact Name 1

String(255)

Mr Jack Stone (uncle)

  

Emergency Contact Phone 1

String(255)

265476111

  

Emergency Contact Phone Alt 1

String(255)

265476112

  

Emergency Contact Name 2

String(255)

Dr Jane Stone

  

Emergency Contact Phone 2

String(255)

265476121

  

Emergency Contact Phone Alt 2

String(255)

265476122

  

Emergency Contact Name 3

String(255)

Tom James

  

Emergency Contact Phone Alt 3

String(255)

265476131

  

Emergency Contact Phone Alt 3

String(255)

265476132

  

Photo Redacted

Bool

1

Used specially with one of our premier partners and indicates whether someone’s profile picture should be displayed in that premier partner’s system

 

Back To Top

School User Data Store (SUDS) Schema - Parents

Are you sure you want to remove this component?

FieldTypeExampleDescription
External IDString(64) (required)321This is the unique identifier you use across your timetable and systems to identify this user
TypeEnum(‘Parent’) (required)ParentIdentifies this row in the CSV as a parent, is not stored.
TitleString(255)Mr 
FirstnameString(255)AnthonyThe person's formal/legal firstname
Preferred FirstnameString(255)Ant 
SurnameString(255)Brock 
UsernameString(255)abrock 
EmailString(255)abrock@schoolbox.com.au 
MobileString(45)0323 233 232 
Home PhoneString(45)029883 4232 
Work PhoneString(45)+0011 92303234 434 

NOTE: Parents with access restrictions are not imported by the data sync into SUDS.  

Back To Top

School User Data Store (SUDS) Schema - Relationships

Are you sure you want to remove this component?

Field

Type

Example

Description

Student ID

sting(64) (required)

54362

The students “external ID” as supplied in the previous imports

Guardian ID

string(64) (required)

321

The parent or guardian “external ID” as supplied in the previous imports

Type

String(55) (required)

Father

A string to description the relationship the guardian has to the student
Back To Top

School User Data Store (SUDS) Schema - Schedule Based Timetable

Are you sure you want to remove this component?

SUDS API connectors import timetable data into a schedule-based timetable, akin to a calendar. This allows the flexibility of having a different number of periods each day and for their periods to start and finish at varying times. The connectors implementing this are:

  • Compass
  • iSAMS
  • LISS
  • Sentral
  • TASS
  • Veracross
  • Wonde
  • Civica

The number of past and future timetable days imported varies depending on the implementation of each connector.

Notes: 

  • Civica imports timetable data for a date that ranges from the start of the week to three months later to speed up the import time. 
  • Schoolbox allows you to sync events with SUDS Civica. For this, go to Calendar > Subscribe and in School Data Events, toggle ‘ON’ Schoolbox Events. This enables Civica to access the Schoolbox calendar feed. This means event data from your school’s SIS will sync into Schoolbox, where it will appear in the Schoolbox calendar and be visible to staff and students.
     

Timetabled Events, Timetabled Classes and Timetabled Enrolments may be downloaded as CSVs to assist in understanding the interpretation of the data and to aid other workflows that may require the data.

Note: An API sync, or update to the CSV files, is required to reflect new or updated timetable data.

Back To Top

School User Data Store (SUDS) Schema - Timetable Events

Are you sure you want to remove this component?

FieldTypeExampleDescription
TitleString(255)Specialist MathsThe name of a subject being taught or an event that's occurring
LocationString(255)ART03The room/theare where this event occurs
DetailTextIt's practice exam time today so bring your calculators.Some text to describe more about the event or convey particular details.
CodeString(255)SPEC123A class code, if this event is a subject being taught. 
DayString(255)Day 1Optional. Text corresponding to the current academic day's name
PeriodString(255)Period 4Optional. Text corresponding to the current academic period's name
StartDate2022-01-28 09:30:00The date and time when this event starts
FinishDate2022-01-28 11:00:00The date and time when this event finishes
All DayBool1Denotes whether this is an all day event, displaying it differently in the calendar
TypeString(255)HolidayOptional. A text string corresponding to one of the event types in schoolbox admin which will be used to categorise this event.
ClassificationEnum('event', 'timetable')timetableThis indicates how the event should be processed; either as a calendar event or as a timetable event.
GuidString(255) Optional. A text string that uniquely identifies this particular event.
SourceString(255) Internal use only.
Back To Top

School User Data Store (SUDS) Schema - Timetable Classes

Are you sure you want to remove this component?

FieldTypeExampleDescription
NameString(255)Specialist MathsThe name of a subject.
CodeString(255)SPEC123A class code corresponding to this subject.

Notes: The class code you enter will automatically be shortened to a maximum of 64 characters.
For example, a class code with 82 characters:
025-Year12-English-Literature-Extension-Semester1-TeacherA-Room305-Period3-Day5’ will be automatically shortened to 025-Year12-English-Literature-Extension-Semester1-TeacherA-

Make sure the most important details are included within the first 64 characters to avoid losing key information.

Back To Top

School User Data Store (SUDS) Schema - Timetable Involvements

Are you sure you want to remove this component?

The schedule-based timetable supports multiple staff being allocated to a class. This may be utilised for cover teachers, learning assistants or team teaching. The method of implementing this is different for each connector due to the availability and limitations of data from the SIS.

FieldTypeExampleDescription
Event IDInt4489The internal identifier for a timetabled event
External IDString(255)ABC123The external identifier for a person involved with this event
ActionEnum('clear', 'clear_staff', 'add', 'subtract')clear_staffThe mutation applied to the external id specified. For example, adding or subtracting an external id. Allows you to manipulate the enrolments of teachers, facilitate covering teachers, etc.
SequenceInt3The mutations for each event occur sequentially; this int specifies the order
Back To Top

School User Data Store (SUDS) Schema - Timetable Enrolments

Are you sure you want to remove this component?

Field Type Example Description
Class Code int(11) (required) ENX11 Class timetable code as per Timetable template
Class Title varchar(256) (required) English X11 Class title as per Timetable template
Student Code varchar(64) (required) ST111X Student External ID
Back To Top

School User Data Store (SUDS) Schema - Cyclic Grid (Legacy)

Are you sure you want to remove this component?

The Timetable Structure and Timetable Template are legacy implementations for older connectors using SUDS and for manually populated CSVs. Data using these implementations will utilise a recurring cycle of lessons where the start and finish times days and their scheduled lessons will always appear to be the same. 

  • CSV
  • Kamar
Back To Top

School User Data Store (SUDS) Schema - Timetable Structure

Are you sure you want to remove this component?

Field Type Example Description
Term Identifier varchar(255) (required) term1 Unique term identifier
Term Title varchar(255) (required) Term 1 2020 UI Visible unique term title
Term Start date (required) 2020-01-27  
Term Finish date (required) 2020-03-24  
Term Start Day Number int(11) (required) 3 Definition of which day of the timetable the particular term starts.
Period Day int(11) (required) 1  
Period Title varchar(64) (required) Period 1 Unique Period Identifier
Period Start time (required) 09:00:00 Start time of Period
Period Finish time (required) 09:50:00 End time of Period
Back To Top

School User Data Store (SUDS) Schema - Timetable Template

Are you sure you want to remove this component?

Field Type Example Description
Term Identifier varchar(255) (required) term 1 Term identifier as defined in Timetable structure
Term Title varchar(255) (required) Term 1 2020 Term title as defined by Timetable Structure
Period Day int(11) (required) 1 Period Day as per those defined in Timetable Structure
Period Title varchar(64) (required) Period 1 Period title as per those defined in Timetable Structure
Class Code varchar(64) (required) ENX11 Class timetable code used for creation of Class pages.
Class Title varchar(256) (required) English X11 Title of Class
Class Room varchar(64) 3 Room number for class/period combination. 
Teacher Code varchar(64) (required) T111 Teacher External ID
Back To Top