Third Party Integrations

Enter /learning/export/assessment/csv at the end of your URL. A CSV will automatically download. The CSV will display the following:

• Student code

• Class code

• Assessment title

• Assessment item code

• Result

NOTE: This process may take some time, depending on the quantity of data you have in your system. If you have too much data for your system to process, please log a ticket with support and they will provide you with this data.

If your school is using Clipboard to manage sports fixtures or other custom calendars for your users, you can display those calendars in Schoolbox.

A Superuser must enter the VCAL URL with the correct details in the calendar subscription area of Schoolbox Administration. For more information, visit our Calendar Help page.

Once the subscription has been setup correctly, all users will see their Clipboard calendar in Schoolbox. This means they will see it along with all their other events, learning activities, bookings, excursions, etc.

EdSmart allows single-sign-on (SSO) into the system via Schoolbox, using our Remote Services API, which embeds EdSmart into an iFrame in Schoolbox. To access EdSmart, the user will not need to log in again. 

Schools that are using or want to use this integration will need to be provided with a URL from EdSmart, which is the URL that can then be added on a tile or a link that will launch users into the EdSmart system. 

Parents can then easily access EdSmart from the parent dashboard and view or submit any forms as necessary.

There are 3 important aspects of this integration:

1. Managing existing forms:
When parents access EdSmart, they will see a view of all the forms that are being sent between the school and the parents. If there are any outstanding forms, the “Status” field will show what they need to action on that form and allow them to complete it. 

2. Reviewing any care information:
This is an optional element and will need to be configured by the school in order for parents to use it. The “Review Care Information” tab allows parents to review what the school has on file regarding important information staff refer to in case of an emergency. Here, parents can see what the school has on file for their children.

3. Submitting self-service forms:
These forms are initiated by the parents and include information such as a change in medical details, a change in address, or even an enrollment request. When the parent submits the form, it gets redirected to whatever workflow is necessary for it to be progressed. The parent will also be notified of the progress.

The google maps integration uses your existing Google API Key. However we will need you to enable the follow extra APIs for it to work.

1. Login to https://console.developers.google.com/
2. Select the project you created for Schoolbox to access
3. Select Library on the left menu
4. Search for and enable the following APIs
    Google Maps Embed API
    Google Maps Geocoding API
    Google Maps JavaScript API
    Google Static Maps API
Once those are added, that functionality should work correctly in Fixtures.

NOTE: The Google API Key set up relates to https://help.schoolbox.com.au/homepage/488 but if you don't want Google Drive you don't need to enable those permissions

This API is designed to allow native mobile applications to register and receive messages from Schoolbox. It will also allow you to fetch messages from Schoolbox on demand.

Registering your app

Currently, Schoolbox's official support for native apps is limited to the iOS and Android ecosystems. Other apps may be able to use the API, depending on their cloud notification infrastructure.

Configuration for iOS apps

You will need to register your app with APNS. In this process, your app will be issued a certificate and a key.

NOTE: You need to upload your certificate to somewhere on the Schoolbox server.

Once you have these, navigate to http://SERVER_ADDR/adminv2/settings/Modules

Populate:

• Apple Push Notification Service Certificate Path: the absolute path to where you put the certificate file
• Apple Push Notification Service Key: the passphrase to use on your certificate file

See this documentation for more information http://framework.zend.com/manual/current/en/modules/zendservice.apple.apns.html

Configuration for Android apps

You will need to register with GCM. In this process, your app will be issued an API key.

Once you have these, navigate to http://SERVER_ADDR/adminv2/settings/Modules

Populate:

• Google Cloud Messaging API Key: the API key issued by Google for your app

Configuration for Digistorm

When Digistorm is setup, they will provide an API key for communicating with their notification endpoint.

Once you have these, navigate to http://SERVER_ADDR/adminv2/settings/Modules

Populate:

• Digistorm API Key: the API key issued by Digistorm for your app

Configuration for TASS Orbit

To set up TASS Orbit as the delivery provider to have the notifications working:

As a Superuser:

1. Go to Adminstration > Notifications > Delivery Providers.
    
2. In Register New App, select TASS Orbit as the delivery provider.
    
3. In App Details, enter the details that TASS provided you for using the TASS Orbit:
   • Endpoint
   • App Code
   • Token
   • Company Code
4. When done, select Register.
   This registers the TASS Orbit for your school.

Note: For more information, see TASS Orbit.   

Registering users in Schoolbox

In order to register your app to receive push notifications you first need to notify Schoolbox of a valid user and the app identifier. This process is handled via a POST call as specified below.

A successful HTTP request will be:

POST https://SERVER_ADDR/api/register/[APNS|GCM|Digistorm] where

$_POST ~= [
   'username' => :valid_username,
   'password' => :valid_password,
   'token'    => :unique_notification_identifier,
   'appId'    => :mobile_app_id
]

Alternatively if an oAuth endpoint has been configured in Schoolbox you can send a jwt token for us to validate against that endpoint.

$_POST ~= [ 'jwt' => :jwt, 'token' => :any_string, 'appId' => :mobile_app_id ]

and will respond with:

{
   "id" : "user_id",
   "key": "user_key",
   "role": "staff",
}

If the user is invalid you will receive a 401 Unauthorised header.

"id" => The internal schoolbox user ID

"key => The session key used to identify the session

"role" => The users role type, can be one of [staff|student|parent|guest]

If your request is successful you will also receive a PHPSESSID and rememberme cookie. The PHPSESSID cookie will be valid for generally around 20 minutes. However, the rememberme token is valid for 2 months.

Note: currently this registry lasts forever, but in the future this will be periodically garbage collected. You will need to re-register your users' apps when their sessions expire periodically.

Authenticating users in Schoolbox

To help authenticate the native browser we have a specific endpoint that can be used to login with.  This endpoint accepts both a username/password or JWT token.  In addition it will take a redirect paramater to redirect the user to after the authentication takes place.

To send a user to a homepage you can do the following requests

POST https://SERVER_ADDR/api/session?page=/homepage/123

$_POST ~= [
   'username' => :valid_username,
   'password' => :valid_password
]

OR

$_POST ~= [ 'jwt' => :jwt ]

Fetching Messages

Messages are available via our websocket. In order to receive messages you must send at least one of the PHPSESSID or rememberme cookies with your request to

GET ws://$SERVER_ADDR:8080/websocket

Data Format

The websocket server communicates via JSON, in the form

{
  "$COMMAND" : $DATA
}

where $DATA is the payload for the given command.

Request/Response Handling

The client may anticipate, but may not expect a response from the server for any request sent, as is the nature of sockets. The server may—typically in flood-protection scenarios—ignore requests from clients. In such cases, the client should wait for a reasonable timeout, and then retry the request.

Connection Handshake

Attempting a connection will validate the identification cookie provided; if the cookie does not match a valid session, the server will close the socket after sending an error message, eg:

{
  "error": {
    "code": 401
    "msg": "Unauthorized"
    "retry": false
  }
}

Upon a successful connection, the server will wait for the client to initiate communication.

Firstly, the client must request a subscription with

{ "subscribe": true }

If the request cannot be fulfilled, the server will respond with an error and close the socket.

Upon a successful subscription, the server will confirm that the client is clear to "fetch" messages by reciprocating

{ "subscribe": true }

Transmission of Messages

Server-Initiated Transmission

The server will send any unread messages for the authenticated user in realtime (including a push of any backlog). This follows the format

{ "push": [
    $MESSAGEDATA, 
    ...
  ] 
}

All messages received via "push" must be treated as unread by the user.

Client-Initiated Transmission

The client may request a list of messages, which includes both read and unread, with:

{
  "fetch": $COUNT
}

where $COUNT is the maximum number of messages to be retrieved.

If the request can be fulfilled, the server will respond with

{
  "fetch": [
    $MESSAGEDATA, 
    ...
  ]
}

Message Acknowledgement

(Also known as "mark as read")

In order for the client to request that one or more messages be marked read, it can send

{
  "ack": [
    "$MSGID",
    ...
  ]
}

The client must not assume that the request will be successful and mark-as-read at this point. The server will propagate successful acknowledgement to all connected clients (for this user), in the same format.

Thus, when a client receives an "ack", it should then mark any messages matching the given IDs as read.

Interpreting Message Data

As described above, the two sources from which a client can receive messages are "push" and "fetch".

From "push", all messages are unread. From "fetch", messages may be read or unread.

To consolidate these two sources into a single list, the following logic should be observed:"For any MessageID in FETCH: if is present in PUSH it is UNREAD; otherwise it is READ. 

NOTE: For any MessageID in FETCH: if is present in PUSH it is UNREAD; otherwise it is READ.