Working with use cases in HITS

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 use case…

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 HITS dashboard.

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.

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 fetch 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.

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.)

NOTE 1: If the message is not well-formed XML, the message will be rejected.

NOTE 2: 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->Transaction 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.