Skip to main content

Callbacks

Request Callbacks​

Xporter on Demand supports a number of options for you to use to ensure that data can be flexibly received from the API.

A caching layer is implemented between the MIS and the endpoints that are called to ensure that requests are serviced as efficiently as possible, minimising the time you wait for the data, along with the impact of requesting live data from the school MIS.

Each school's information is stored as a series of encrypted databases, distinguished by datatype and purpose for performance and granularity. These databases are all defined with a TTL (Time To Live), defined the in the table below - each endpoint also defines the databases it includes and the TTL in use.

Once a school has authorised their first partner, data is automatically cached for the following databases, automatically each night at approximately 03:00:

Database NameTTL (Minutes)Refresh Mode
XodSchoolData1440Auto (Overnight)
XodAttendanceSummary1440Auto (Overnight)
XodAssessmentTables1440Auto (Overnight)
XodAttendanceForDate (Today)30Auto (Overnight/On Request)
XodConductForToday30Auto (Overnight/On Request)
XodConductPoints30Auto (Overnight/On Request)
XodConductForDateRange720On Request
XodAssessmentResults30On Request
XodEndpointInfo5On Request
Important

Only fields within these databases that are covered by the overall set of scopes that a school has authorised across all applications is transferred to and cached in the platform.

We cache parameter-less databases in this way to ensure swift response times to API requests. For endpoints that require specific dates or other query parameters like school.assessmentresults, we fetch the data in real time unless there is a cached request with where the same parameters have been passed already. In this case, we instantly return the expired cache data and fetch the fresh info in the background. Have a look at callback options below for flexible ways to manage these scenarios.

When you query the school.students endpoint, the information you receive is comprised of the cached data from XodSchoolData and XodAttendanceSummary which was gathered automatically overnight. These databases both have an expiry of 1440 minutes (1 day) and as such the databases are unexpired.

The default behaviour of the Xporter on Demand API is to return the data it has for a database immediately, even if the database it currently has for an endpoint is expired. When an expired database is requested, Xporter on Demand automatically fires off a request to the school's MIS to refresh the expired cache with the latest information. You can tell if you have received an older database by checking the date in the "meta" table that is returned with each request.

Example: When you query school.attendancefordate with today's date, because Xporter on Demand cached XodAttendanceForDate overnight for the current date, you will instantly be returned the dataset. In the background we are fetching the updated information for your request and will update the XodAttendanceForDate database when it is returned so on your subsequent request, you will get the updated information.

Requesting Intelligently​

Every endpoint has an associated __DBStatus__ object that defines the current status of each of the component databases that make up data response for each endpoint call.

Example __DBStatus__ object:

    {
    	 "__DBStatus__": [
        {
          "Id": "XodSchoolData",
          "Status": "ok",
          "Error": null,
          "Expires": "2017-02-14T03:40:43",
          "LastRequested": "2017-02-13T03:34:47",
          "DBQueryString": null
        },
        {
          "Id": "XodAttendanceSummary",
          "Status": "ok",
          "Error": null,
          "Expires": "2017-02-14T03:11:59",
          "LastRequested": "2017-02-13T03:11:45",
          "DBQueryString": null
        }
      ]
    }

You can check the __DBStatus__ object on every endpoint by passing the optional parameter onlygetDBStatus=true. This will return you a JSON object detailing the status of each database required by the endpoint. The following statuses are possible for a given database:

Important

The component databases for each endpoint are subject to change as we make refinements for performance so rather than looking for specific databaes, we recommend simply looking for the status of the databases that are returned.

DBStatusDescription
okDatabase is ready to be requested and is not expired
requestedDatabase is expired and will return expired cached data. An update has been requested from the MIS
fromcacheThere has been a problem with a previous request and we will be unable to return data. Try again in 15 minutes

In theory, you could periodically request an endpoint with the parameters you require with "onlygetDBStatus=true" until all databases in the object return "ok".

Example: /attendancefordate?date=2017-09-23&onlygetDBStatus=true

Then request without:

Example: /attendancefordate?date=2017-09-23

However, so you don't have to make multiple unnecessary calls to the API, requesting data to check if it is updated, we have implemented additional funationality based on the DBStatus object to provide you with the flexibility to work in multiple ways.

Writeback Callbacks​

Every endpoint now supports an additional GET parameter "callbackUrl". If you pass this paramaeter with a URL the can receive a POST message, then we will do the DBStatus checking for you and call you back with the DBStatus object once all component databases are status "ok".

Example:/attendancefordate?date=2017-09-23&callbackUrl=https://xporter.groupcall.com/TryIt/callback?estab=3281102&id=attendance1

We suggest you provide the Estab and your own abritrary Id so you know which request the callback is referring to, if you are making multiple requests against different schools.

The maximum wait period before determining there is a problem with a callback is 10 minutes. After this time, we will call you back with an appropriate status. If there is an error received immediately, then we will call you back as soon as we have that error as well. In this scenario, based on the databases statuses received in the object, the recommended action would be to request the data direct, so we can return you data from the cache.