API keys

From InsightWiki
Jump to: navigation, search

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.

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