What you need before you start:

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

• A HITS testing account - apply from the Request an account section of the HITS Dashboard.
• This will give you access to your own testing environment 
• Your testing environment will provide you with all necessary authentication and access tokens to work with the HITS API.

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

• Here is some information from the SIF Association.
• Here is a short (1-day) course in developing with SIF 3 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 info@nsip.edu.au

How to implement NAPLAN results & reporting

1. Business problem

Allow jurisdictions (and potentially individual sectors) to retrieve information about the NAPLAN tests for the current cycle.

More…

2. Use case description and pre-conditions

A Jurisdiction client connects to HITS, as a proxy for the National Assessment Platform, and obtains:

• a list of all the schools for which the jurisdiction has the authority to obtain results
• copies of the test codeframes (a representation or plan of each test including the test, testlets and test items)
• student NAPLAN results for one or many schools

This data is then expected to be processed in local jurisdiction applications.

NAPLAN results reporting conceptual diagram

NAPLAN results reporting SIF objects

Diagrams the interactions between SIF objects for this use case.

Assumptions

• Information about the students taking part in the NAPLAN assessment has already been provided to the National Assessment Platform.

• The students have already undertaken all the NAPLAN assessment for this year, and the responses they have provided have been captured in the National Assessment Platform.

• The assessment results have already been processed post-assessment, and all required information is available for jurisdictions from the National Assessment Platform. This includes scaling of scored results, and deriving the national averages for each test.

• The assessment results data includes ACARA Ids for schools, which reference the school records held in the Australian Schools List.

• Jurisdictions need to access information about the NAPLAN test structure as well as the test results: the former helps contextualise and interpret the latter. Information about the NAPLAN test structure is available under SIF modelling in two separate models: a single codeframe object per test, which contains all testlets, test items, rubrics and stimuli accessible through the test; and separate test, testlet and test item objects, which are referenced individually from the student test results object. The results and reporting data available from the National Assessment Platform includes both representations.

• Jurisdictions can cope with streaming ZIP responses to HTTP queries. (Because of the volume of responses, the endpoints do not use plaintext XML. The responses will still be a few MB in size.)

• Clients can process multiple SIF object types contained in a single payload. (The NAPLAN endpoints deviate here from the normal SIF pattern.)

Pre-conditions

• Jurisdiction has access to HITS.

• Jurisdiction has contacted NSIP and obtained their State/Territory Sector specific account details (username/password eg vicgov abc123).

• HITS has been provisioned with School Data. Note that the school data is static for the HITS realisation of this use case, and is not to be supplied by clients.

• HITS has been provisioned with Student Data. Note that the student data is static for the HITS realisation of this use case, and is not to be supplied by clients.

• Vendor has mapped the relevant SIF Objects to their systems:
  • StudentPersonal
  • NAPCodeFrame
  • NAPTestScoreSummary
  • NAPTest
  • NAPTestlet
  • NAPTestItem
  • NAPEventStudentLink
  • NAPStudentResponseSet
  • SchoolInfo (the Platform API releases data for multiple schools from a single endpoint. StudentPersonal records contain the ACARAId of the school they are registered against; so there is no need to consume or model a StudentSchoolEnrollment record.)

3. Use Case Workflow

Workflow summary:

1. Join

2. Consume (Codeframe + Results)

Note:

• This is not the usual workflow under HITS of Produce–Consume or Consume–Produce. This is a Consume-only workflow.
• Any processing of the NAPLAN results is out of scope of this use case, since it depends on jurisdiction-specific setup. However, NSIP offers some support to jurisdictions for processing NAPLAN results, through its NIAS toolkit.
• The API is a simple, read-only REST API. It does not realise the additional infrastructure services, or query or header parameters specified in the SIF Infrastructure specification. There is for example no provision for flow control or queues. The REST API should not be confused with a SIF 3.x endpoint. In fact the REST API is not a SIF 3.x API as specified in the SIF 3.x Infrastructure Specification.
• The API will use the SIF_HMACSHA256 authentication method, as documented in the SIF Infrastructure Services Specification, section 4.1.5 (http://specification.sifassociation.org/Implementation/Infrastructure/3.2.1/Documents/InfrastructureServices_3-2-1.pdf page 24/25).
• No SIF environments are created for the endpoint: the authentication is purely in consumer mode (so the Create Environment part of the SIF specification is to be ignored, along with the instanceid and userToken parameters).
• The API does not support URI query parameters: only HTTP header values are recognised.

3.1. Connect to NAPLAN endpoint

• Jurisdiction client connects to NAPLAN endpoint
• Jurisdiction client authenticates
• The SIF_HMACSHA256 authentication method involves adding header values to the HTTP GET request:
  • timestamp: date and time according to the ISO 8601 standard. The time must be in ZULU time to avoid time zone issues (e.g. 2018-08-29T04:20:25.019Z).
  • authorization: the authorisation token, which is calculated based on the applicationKey, password (supplied previously - see Pre-conditions) and timestamp. The applicationKey and password are not included as header values.
    
• The applicationKey uniquely identifies the consumer for authentication purposes. There will be at least 24 of these (e.g. one key for VIC-GOV, VIC-CATH, VIC-IND, NSW-GOV, NSW-CATH… etc). For the National Assessment Platform, the applicationKey specific to the client will be issued as credentials by the ESA operations team. In the case of HITS testing, the applicationKey is completely unrelated to the applicationKey used on the Platform, and it will be provided by NSIP.
  • The HITS test data is statically generated, and is identical whichever applicationKey the user provides: HITS is only intended to let users test that they can use the API. On the National Assessment Platform, each applicationKey corresponds to a distinct data tenancy, so it will access completely different data.

• The algorithm to produce the access token in the authorization HTTP header based on these three values is outlined in the SIF specification cited above, and is as follows. A Javascript script to generate these headers for the Insomnia REST client is available from https://github.com/nsip/naplan-results-reporting/blob/master/API/naplan_api.zip.

  1. Concatenate the applicationKey and timestamp, and separate them by a “:” .
  2. Calculate the HMAC SHA 256 of this string using the unsent password (supplied previously - see Pre-conditions).
  3. Base64 encode the result.
  4. Concatenate the applicationKey and the new string, separating them again by a “:”
  5. Base64 encode the result.
  6. Prefix the result with the authentication method (SIF_HMACSHA256), separating them by a space.

• When the API receives a request for NAPLAN Online results, the following process will occur:

  1. Identify the Authentication Method. (SIF_HMACSHA256)
  2. Base 64 decode to obtain the applicationKey and the Base64 value of the HMAC SHA 256.
  3. Look up the applicationKey in the list of pre-stored authorized clients, to retrieve the pre-stored shared secret (password) specific to that client.
  4. Retrieve the timestamp that was used from the message header.
  5. Use the applicationKey and timestamp and calculate the SIF_HMACSHA256 value using the shared secret for this client. Compare the result with the string provide in the request.
  6. The authentication of the issuing application has been confirmed.

3.2. Consume base data

Client-facing (pull); HITS represents the National Assessment Platform and is the data source for results information.

Sample request:

GET /sifapi/some_endpoint_name HTTP/1.1
Host: example.org
Authorization: SIF_HMACSHA256 bmV3OjZUVmdZd2JBaG1RYzJ6QUxkYThadXBmcnpmcVorWEQ3ZjJiTUEwQXpXUm89Cg==
timestamp: 2013-06-22T23:52-07Z

Consume:

• The Jurisdiction client accesses all data about the test artefacts, from a single endpoint. This data is applicable to all test results.
• The Jurisdiction client accesses all SchoolInfo records corresponding to schools that it has access to on the platform.
• The Jurisdiction client iterates through the SchoolInfo records it has retrieved.
• For each SchoolInfo object, the Jurisdiction client retrieves the result set for all students enrolled at that school, from a single endpoint. The retrieval uses the SchoolInfo RefId in the service path.

The following is a list of calls that need to be made to consume the required information:

1. Get test data (contains NAPCodeFrame, NAPTest, NAPTestlet, NAPTestItem objects): http://hits.nsip.edu.au/api/naplantest/large/TestData
2. Get SchoolInfo objects: http://hits.nsip.edu.au/api/naplantest/large/SchoolList
3. Get results data for each SchoolInfo object (contains SchoolInfo, StudentPersonal, NAPEventStudentLink, NAPStudentResponseSet, NAPTestScoreSummary): http://hits.nsip.edu.au/api/naplantest/large/SchoolData/{School RefID}. The RefID for each school is to be retrieved from the SchoolList response.

The responses to each endpoint will be provided in streamed gzip. The responses to each endpoint will be wrapped in a NAPResultsReporting element, regardless of content.

Note that all connections to the endpoints must be through SIF_HMACSHA256 authentication. This reflects the security arrangements on the National Assessment Platform. The timestamp included for SIF_HMACSHA256 authentication is validated as following xs:dateTime with Zulu time, and expires within five minutes.

More information about using the NAPLAN API is available as a user guide. Currently this is available from NSIP / ESA on request.

Assurance

As there is no Produce component to the workflow, there is also no Assurance component. Any processing of NAPLAN results will be specific to the jurisdiction’s database setup, and will need to be undertaken within the jurisdiction: it is out of scope of this use case.

More information

What business problem does this use case address?

Jurisdictions need assurance that they can retrieve from the National Assessment Platform the large bulk of records associated with NAPLAN results.

Assurance pre-conditions

The following conditions also must be met:

N/A

Relevant Service Paths Supported on HITS

N/A. The endpoints do not follow normal SIF conventions for service paths.

Relevant Queries By Example Supported on HITS

None. This use case deals with the retrieval of bulk data; querying individual records from the data is not currently in scope.