Welcome to HITS (Hub Integration Testing Services)
An assurance and demonstration environment for education integrations.
There are a number of assurance use cases supported by HITS. All involve SIF CRUD operations over REST, and can confirm your ability to provide a hub provisioning data through SIF.
All the use cases follow a similar pattern. Below is our suggestion as to how to work through them:
1. Study the use case
The use case lists the kinds of objects involved in the exchange, the anticipated choreographies, and how the objects will be validated. Processing the use case assumes that your client can translate the SIF objects meaningfully into data objects that your software uses. [Here is an example usecase...](http://hits.nsip.edu.au/usecases/basic_daily_attendance/hits-dashboard.html)
2. Set up a client to use HITS.
As a part of your sign-up process for HITS, you will have received the URL for a unique environment for testing, which takes you to the dashboard you now see.
You can now create databases on HITS populated with the randomly-generated demo data you need for testing various use cases. HITS acts as a proxy for the hub you will be integrating into. When you create your database, depending on the options you select, your new database is populated with randomised objects that are representative of the information stored on a hub. To simplify testing, your client is assigned to one dummy school: all objects on the database are associated with that school.
3. Get some objects from HITS
The use case describes the objects from the hub that you need to access; we expect that you will get all objects of the given classes that are available from HITS. Each object class is associated with a distinct endpoint, named by appending an "s" to the object class; you fetch instances of ScheduledActivity, for example, from the endpoint ending in /ScheduledActivitys.
4. Based on those objects, generate some new objects
Your client will be validated based on your ability to generate valid SIF objects and post them back to the hub.
Amongst other things, your objects are tested for referential integrity: do they link to objects that are already on the hub? For example, a class roster must reference the existing students, staff, rooms, and subjects in the school. To create those links, you must access all the relevant objects from HITS (as noted above), and use only their GUIDs when generating the objects that reference them.
5. Clear the HITS database
The validation of your objects runs over the entire contents of your database instance. This means you can validate results only after you have posted all required objects (which may involve several messages). If you have posted some objects with errors, clear the database before resending the corrected objects. This allows you to start with a clean slate, without having to update or delete individual objects you have already posted: your rerun can be treated as new Creates on the endpoint.
5.1 Deleting objects
The database behind HITS imposes constraints on foreign key integrity, and does not implement cascading deletes. As a result, if you are deleting individual objects from HITS via REST, you should delete child objects before you delete parent objects; e.g. delete instances of StudentContactRelationship before StudentContactPersonal before StudentPersonal. An attempt to delete an object with unresolved dependencies will generate an error.
6. Post those objects to HITS (Return Path use cases)
Having created new objects, you will need to post them to the HITS endpoint specific to your client. If your post is successful, this will add the objects to the client database instance. As there is a different endpoint for each object class, you may need to post multiple messages. (Note that SIF 3 allows you to package multiple objects of the same class into a single message.)
If the message is not well-formed XML, the message will be rejected.
The message will NOT be rejected if the message is well-formed, but does not follow the SIF-AU schema. HITS does not automatically perform any syntactic validation of payloads against the SIF XML schema, although you can perform this validation against the transaction log as a manual operation (Dashboard->Developer Tools->Information->Tranasaction Log->Validate). HITS does not validate for failure to use the code sets prescribed in the SIF-AU specification. However, the payload populated may have empty elements where those elements have not been provided properly in the payload.
7. Run report on the objects you have posted
Validation is run when:
- you have posted all the messages required by the use case to the object end points, and
- the messages have been successfully processed, and
- the resulting objects have been added to the client database.
Validation runs over the objects added to the database, and checks that the objects make sense in the context of the use case. As a result of validation, a report is generated which indicates whether your objects satisfy the use case requirements.
The main things checked for are:
- Referential integrity: your objects only link to the RefIDs of other objects on the database - whether these are objects that were already on the database (and that you have read in from HITS), or objects that you have posted to the database in another message. Because you may need to spread your objects over many messages, do not run validation until you have posted all your messages.
- Object Obligations: you have posted at least the number of instances of each object that is set in the use case. For example, a timetabling application cannot be validated unless it has posted at least one TimeTableCell object.
- Element Obligations: you have posted all the elements in your object that are mandatory in the use case. This includes not only the elements that are mandatory in the SIF-AU schema, but also the elements that this use case specifically requires to be populated.
- Element Values: some use cases will require that a particular value appear in an element. The objects will be tested to confirm that this has been done.
Note that the validation report checks the current contents of the database. If you have prepopulated the database with objects automatically, and then run validation, the validation will give you a perfect score, as the prepopulated objects are valid. If you then add to the database objects with errors, the score will go down, and you will need to correct those errors to get the validation score back up.