API keys
The Insight API is an additional module in Insight. It allows data to be drawn out of Insight to be used by other applications. There is also a free, limited version of the API which is automatically available if Insight is linked to PARS.
As the full version of the API is an additional module of Insight, a separate charge applies. Please contact sales@tascsoftware.co.uk for further information.
Contents
Creating an API Key
The API page is accessed via:
Manage > API Keys
The following Role Options are required to configure Insight APIs:
Manage > API Keys (On)
New API keys are created using the Add button at the top of the page. An API key has the following options:
Field | Purpose |
---|---|
Key | This is a randomly generated string that cannot be changed. |
Description | The title given to the key. This is only for internal Insight use, to help users organise the API keys. |
Role | The API key will use the chosen role when extracting data. This may affect the data that is extracted, for example by limiting the date range over which behaviour information is extracted. |
IP address range | A start and end address can be set to create an IP address range. Insight will only return data to an application if the request is made from an IP address within this range. The default values allow data requests from any IP address (note that API requests always require a 32 character key, regardless of the IP settings). |
Permissions | The information that the key is allowed to extract from Insight. |
Settings for PARS API
An API key is required for some functionality between Insight and PARS. These functions are:
- Allowing students to upload attachments in Insight for homework assignments created in PARS
- Triggering a push notification in the Insight app when a message is sent from the External Contact page in PARS
Only one API Key can be used by PARS. The Description given and the Role used for the API Key have no effect.
If you want to limit the IP addresses that the Insight API will reply to then you must create an internal URL for Insight, which will be used by PARS. In this case the API requests will either be sent from 127.0.0.1 (if the PARS and Insight websites share an IIS server) or otherwise the IP address of the IIS server hosting PARS. The PARS server must use IPv4 rather than IPv6.
The Permissions that can be used are:
Push - this allows PARS to trigger push notifications to notice recipients, and to students when they receive merits, demerits, detentions, removals or assignments, in the Insight app
Push S - this allows PARS to trigger push notifications to parents when students receive merits, demerits, detentions, removals or assignments
Evidence - this allows PARS to receive assignment uploads from Insight
The following preferences must be used to enable these features:
Manage > Preferences > PARS > Collect Assignments from PARS - this must be On for Insight to display assignments from PARS
Manage > Preferences > PARS > Include PARS communications in notices - this must be On for Insight users to see messages sent from PARS and to receive push notifications when such messages are sent
PARS must also be given the URL and API Key for Insight. These details are entered into PARS via:
Main menu > System management > Preferences > Personal
Using an API Key with other applications
Once you have created the appropriate API Key in Insight, you need to create a URL for your other application to use to request data from Insight. The URL is constructed as follows:
https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&adno=002467
The school's Insight URL | |
The API key | |
The information required from the API. The list of available information is shown in the Permission field when creating the API key | |
The identifying number for the pupil |
The final section of the URL is used to identify the pupil whose data is going to be extracted. In the example above, this section of the URL is &adno=002467. If the data being extracted is not specific to a student (such as PARSHousePoints) then this section can be omitted.
The example above uses ADNO to identify the pupil whose data is going to be extracted. MISID and UPN can be used instead. If this is the case, the URL would be written as:
https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&upn=N823432113104
or
https://insight.school.org/insightapi/ashx?apikey=b25a5fd2-965c-4bc8-b425-dbdc5234e6aa&op=Assignments&misid=9919
Error Messages
The following error messages can be returned by Insight to an application attempting to use Insight's API:
403.16 invalid api key
The API key is incorrect
403.6 IP address rejected
The IP address that the request was sent from is forbidden
403.18 invalid operation
The operation requested by the application is incorrect
403.1 Execute access is denied - role permission preclude call
The application is requesting to use an operation for which the API key does not have permission
403.13 Student id expected but none specified
An identifying number for a student is required, but has not been specified by the application