What you need before you start:

To use the Hub Testing Integration System (HITS), you'll need the following:

You'll also need a basic knowledge of SIF REST:

You need to know how to work with a use case in HITS and access the HITS API

If you get stuck: drop us a line at

How to implement gradebook

1. What's the business problem?

Allow schools to securely provide account information to the classroom assessment product of their choice, and also to allow assessment results records to be published to a jurisdictional data hub.


2. Use case description & pre-conditions

A third party classroom assessment application connects to HITS as a jurisdiction hub, collecting the relevant information and publishing back assessment results records to the centralised system.

Gradebook conceptual model

The following diagram gives some wider context around school-level interactions for this use case. Note that not all interactions shown here are covered within this technical use case.

Gradebook SIF objects

Diagrams the interactions between SIF objects for this use case.


The third party vendor is a current supplier of a classroom assessment product in schools or has knowledge of classroom assessment processes in K-12 Schools.


Here is the XSD schema for SIF 3.4.1, and here are the specifications for the grading objects listed above.

3. Use Case Workflow

Workflow summary:

  1. Join

  2. Consume

  3. Process

  4. Provide

  5. Assurance

3.1. Join school zone.


3.2. Consume base data from HITS

Vendor-facing (pull); HITS represents the Jurisdiction and is the data source for seed information.

There are two possible ways to obtain the base information through REST service path calls:

Via single data dump

The first assumes that all available students, staff, and classes, in all known schools, will be exposed to the third party application, as a single dump of data. This is the path recommended for HITS assurance, as it is simpler to fetch the data and start generating objects for validation.  (This is useful to prove that the objects can be consumed and processed, as HITS end points contain customised test data.)

  1. Get SchoolInfos: http://.../SchoolInfos
  2. Get StudentPersonals: http://.../StudentPersonals (linked to school via StudentSchoolEnrollment; equivalent to http://..../SchoolInfo/{REFID}/StudentSchoolEnrollments/{REFID}/StudentPersonals)
  3. Get StaffPersonals: http://.../StaffPersonals (linked to school via StaffAssignment; equivalent to http://.../SchoolInfo/{REFID}/StaffAssignments/{REFID}/StaffPersonals)
  4. Get TeachingGroups: http://.../TeachingGroups (linked to a school via SchoolInfoRefId)
Via teaching groups

The second assumes, more realistically, that only certain teaching groups will be exposed to the application, and that any staff and student records exposed should be accessed via their teaching group. You do not need to obtain data this way for HITS assurance: you will end up getting the same data, since at this stage endpoints are customised for the user. But you should be prepared to consume data from SIF APIs in the following way for production environment where the end point contains more than one school's data:

  1. Get SchoolInfos: http://.../SchoolInfos
  2. Get TeachingGroups: http://.../TeachingGroups
  3. Get StudentPersonals: http://.../TeachingGroups/{REFID}/StudentPersonals (Note that the same student record may appear under two different teaching groups)
  4. Get StaffPersonals: http://.../TeachingGroups/{REFID}/StaffPersonals (Note that the same staff record may appear under two different teaching groups. )

Endpoints may support additional queries for retrieving data - refer to Query-by-example or service paths? for HITS guidance on queries.

3.3. Processes in third party application

The third party app uses the consumed data to produce descriptions of classroom assignments, and records of assignment results. The definition and automation of this process is out of scope of HITs.


  1. Third party app processes information and generates accounts for staff and students, organised by teaching group.
  2. Staff uses third party app to create classroom assessment tasks.
  3. Staff uses third party app to assign classroom assessment tasks to students in a teaching group.
  4. Students use third party app to perform classroom assessment tasks.
  5. Third party app creates descriptions of the classroom assessment tasks created.
  6. Third party app creates descriptions of the results that students achieved when performing the classroom assessment tasks.

3.4. Provide authoritative data

Prior to providing, the third party expresses return information in SIF/XML:

  1. Third party app connects to jurisdiction-established zone for the school ("HITS Zone 1").
  2. Third party app authenticates to jurisdiction-established zone for the school ("HITS Zone 1 Authz").
  3. Jurisdiction-established zone authorises write access to objects in the jurisdiction zone for the School ("HITS Zone 1 Authn").
  4. The third party app posts the following back to HITS;

Note: The Activity object could be used instead of, or alongside, the GradingAssignment object to describe a classroom task, and gives much more information about the pedagogical context of the task. However although Activity/Points provides the possible score of the task, SIF does not contain an object giving individual students' performance against the activity.)  

3.5. Self-confirm use case support

  1. Validate GradingAssignment records
  2. Validate GradingAssignmentScore records

The SIF/XML data sent by the third party app to the Jurisdiction Zone for the app must satisfy the following conditions:


More information

What business problem does this use case address?

In brief:

Schools currently use third-party classroom assessment locally for formative assessment. The seed information for generating accounts on third party apps is held in the School's Student Information System (SIS), and is usually exported locally to the third party apps with little security. There is an added complication: both student and class membership data are required as seed information, since classroom assessment is typically assigned to a class cohort by the class teacher. Class memberships can change frequently, imposing an additional burden on teachers who must manually update the third-party tools.

As jurisdictions centralise systems, third party vendors have the opportunity to seed their product/s from a quality-assured data hub using automated feeds, rather than manual updates from the school. This allows changes such as new enrolments and changes in class membership to be reflected promptly and accurately in the third party applications. Third party vendors are also expected to provide information directly back to the centralised system through an automated feed, rather than having the information mediated through the school. This enables not only more secure and efficient transfer of information, but also the possibility of extracting business intelligence across the assessment results of multiple schools stored in the same hub. 

This use case shows how third party classroom assessment vendors can connect to a centralised data hub to securely access to the required information and publish back the assessment result records to the centralised data hub.

Use case preconditions for assurance

For the purposes of validation, a new GradingAssignment object is well-formed if:

For the purposes of validation, a new GradingAssignmentScore object is well-formed if it satisfies the following requirements:

Relevant Service Paths Supported on HITS

Relevant Queries By Example Supported on HITS





  [<TimeTableSubjectLocalId>{subject}</TimeTableSubjectLocalId>] <!-- TBD -->


  <StudentPersonalLocalId>{id}</StudentPersonalLocalId >