Difference between revisions of "API keys"

From InsightWiki
Jump to navigation Jump to search
(Created page with "{{Additional module}} The Insight API is a tool used to extract data from Insight for use in other applications. The API is an additional module in Insight. <br> <br> After t...")
 
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
{{Additional module}}
+
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. <br> <br>
−
The Insight API is a tool used to extract data from Insight for use in other applications. The API is an additional module in Insight. <br> <br>
 
  
−
After the Insight API has been purchased, you will need to enable it via the [[service controller]]. Run the service controller on the IIS server that hosts Insight. In the window you will see a checkbox for "enable unsecured API". This needs to be ticked before the API will work. <br> <br>
+
As the full version of the API is an additional module of Insight, a separate charge applies. Please contact <span class="plainlinks">[mailto:sales@tascsoftware.co.uk sales@tascsoftware.co.uk]</span> for further information. <br> <br>
  
−
Once the API is enabled, you can view a list of the operations it is able to perform by appending '''/insightapi.aspx?op=list''' to your Insight URL. For example, if the URL to access Insight was <nowiki>https://schoolwebsite/INSIGHT</nowiki> the URL to view the API operations would be <nowiki>https://schoolwebsite/INSIGHT/insightapi?op=list</nowiki> <br> <br>
+
=Creating an API Key=
  
−
This will show you a list of the valid operations. You can click on each of the operations and the browser's address bar will show you the URL that you need to use to extract the relevant data. The URL would be something like: <nowiki>https://schoolwebsite/INSIGHT/insightapi.aspx?op=behaviourpoints</nowiki> <br> <br>
+
The API page is accessed via: <br>
 +
'''Manage > API Keys''' <br> <br>
  
−
However this is not complete, you also need to append a string of text that tells Insight which pupil's data you wish to retrieve. You can use one of the following below: <br> <br>
+
The following Role Options are required to configure Insight APIs: <br>
 +
''Manage > API Keys'' (On) <br> <br>
  
−
'''&unsecuredpupilid=XXXX''' ''where you replace XXXX with the pupil's ID number from SIMS'' <br>
+
New API keys are created using the Add button at the top of the page. An API key has the following options:
−
'''&unsecuredpupilupn=YYYYYY''' ''where you replace YYYYYY with the pupil's UPN number'' <br>
+
{| border="1" style="border-collapse:collapse" cellpadding="5"
−
'''&unsecuredpupiladno=ZZZZZZ''' ''where you replace ZZZZZZ with the pupil's admission number'' <br> <br>
+
!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 [[Roles|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.
 +
|} <br>
  
−
For example, a complete URL could be: <nowiki>https://schoolwebsite/INSIGHT/insightapi.aspx?op=behaviourpoints&unsecuredpupilid=1234</nowiki> <br> <br>
+
==Settings for PARS API==
  
−
You must use IPsec in conjunction with the Insight API. The URL links are not password protected and if you do not use IPsec, anybody could access sensitive information about pupils at school if they guess the correct fields. <br> <br>
+
An API key is required for some functionality between Insight and PARS. These functions are: <br>
 +
* 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 <br> <br>
  
−
[[Category:Configuration]]
+
Only one API Key can be used by PARS. The '''Description''' given and the '''Role''' used for the API Key have no effect.
−
[[Category:Additional modules]]
+
 
−
[[Category:Technical]]
+
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. <br> <br>
 +
 
 +
The '''Permissions''' that can be used are: <br>
 +
'''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 <br>
 +
'''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 <br> <br>
 +
 
 +
The following preferences must be used to enable these features: <br>
 +
''Manage > Preferences > PARS > Collect Assignments from PARS'' - this must be On for Insight to display assignments from PARS <br>
 +
''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 <br> <br>
 +
 
 +
PARS must also be given the URL and API Key for Insight. These details are entered into PARS via: <br>
 +
'''Main menu > System management > Preferences > Personal''' <br> <br>
 +
 
 +
=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: <br> <br>
 +
 
 +
'''<span style="color:#00F"><nowiki>https://insight.school.org</nowiki></span>/insightapi/ashx?apikey=<span style="color:#F00">b25a5fd2-965c-4bc8-b425-dbdc5234e6aa</span>&op=<span style="color:#0A0">Assignments</span>&adno=<span style="color:#A0A">002467</span>''' <br> <br>
 +
 
 +
{| cellpadding="5"
 +
|style="background-color:#00F;width: 35px;"| ||The school's Insight URL
 +
|-
 +
|style="background-color:#F00;"| ||The API key
 +
|-
 +
|style="background-color:#0A0;"| ||The information required from the API. The list of available information is shown in the Permission field when creating the API key
 +
|-
 +
|style="background-color:#A0A;"| ||The identifying number for the pupil
 +
|} <br>
 +
 
 +
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=<span style="color:#A0A">002467</span>'''. If the data being extracted is not specific to a student (such as PARSHousePoints) then this section can be omitted. <br> <br>
 +
 
 +
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: <br>
 +
'''<span style="color:#00F"><nowiki>https://insight.school.org</nowiki></span>/insightapi/ashx?apikey=<span style="color:#F00">b25a5fd2-965c-4bc8-b425-dbdc5234e6aa</span>&op=<span style="color:#0A0">Assignments</span>&upn=<span style="color:#A0A">N823432113104</span>''' <br>
 +
or <br>
 +
'''<span style="color:#00F"><nowiki>https://insight.school.org</nowiki></span>/insightapi/ashx?apikey=<span style="color:#F00">b25a5fd2-965c-4bc8-b425-dbdc5234e6aa</span>&op=<span style="color:#0A0">Assignments</span>&misid=<span style="color:#A0A">9919</span>''' <br> <br>
 +
 
 +
==Error Messages==
 +
 
 +
The following error messages can be returned by Insight to an application attempting to use Insight's API: <br> <br>
 +
 
 +
'''403.16 invalid api key'''<br>
 +
''The <span style="color:#F00">API key</span> is incorrect'' <br> <br>
 +
'''403.6 IP address rejected''' <br>
 +
''The IP address that the request was sent from is forbidden'' <br> <br>
 +
'''403.18 invalid operation''' <br>
 +
''The <span style="color:#0A0>operation</span> requested by the application is incorrect'' <br> <br>
 +
'''403.1 Execute access is denied - role permission preclude call''' <br>
 +
''The application is requesting to use an <span style="color:#0A0>operation</span> for which the API key does not have <span style="color:#0A0>permission</span>'' <br> <br>
 +
'''403.13 Student id expected but none specified''' <br>
 +
''An <span style="color:#A0A>identifying number</span> for a student is required, but has not been specified by the application'' <br> <br>

Latest revision as of 09:54, 12 April 2019

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

Retrieved from "https://www.tascsoftware.co.uk/wiki/INSIGHT/index.php?title=API_keys&oldid=6300"