API keys - Revision history

Admin: /* Settings for PARS API */

2019-04-12T09:54:59Z

Settings for PARS API

Admin: /* Settings for PARS API */

2018-09-24T14:49:32Z

Settings for PARS API

Admin at 16:02, 20 September 2018

2018-09-20T16:02:39Z

Admin at 11:02, 31 May 2018

2018-05-31T11:02:22Z

Admin: /* Using API keys */

2018-05-31T11:00:32Z

Using API keys

Admin: /* Creating API keys */

2018-05-31T11:00:11Z

Creating API keys

Admin: /* Creating API keys */

2018-05-31T10:56:44Z

Creating API keys

Admin: /* Using API keys */

2018-05-31T10:55:34Z

Using API keys

Admin: /* Using API keys */

2018-05-31T10:50:05Z

Using API keys

Admin: /* Using API keys */

2018-05-31T10:49:25Z

Using API keys

@@ Line 37: / Line 37: @@
 The '''Permissions''' that can be used are: <br>
-'''Push''' - this allows PARS to trigger push notifications in the Insight app <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>
 '''Evidence''' - this allows PARS to receive assignment uploads from Insight <br> <br>

@@ Line 34: / Line 34: @@
 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. <br> <br>
+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>

@@ 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>
-As 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>
+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>
-==Creating API keys==
+=Creating an API Key=
-The API is managed via the API keys page. Several API keys can be configured, each of which can be used to extract a certain aspect of data from Insight. <br> <br>
+The API page is accessed via: <br>
 New API keys are created using the Add button at the top of the page. An API key has the following options:
@@ Line 12: / Line 15: @@
 !Field!!Purpose
 |-
-|Key||This is a randomly generated string that cannot be changed
+|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
+|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]] when extracting data. This may affect the data that is extracted, for example by limited the date range over which behaviour information is extracted.
+|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. The API key will only function in this range. This is used to add security to the API
+|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
+|Permissions||The information that the key is allowed to extract from Insight.
 |} <br>
-==Using API keys==
+==Settings for PARS API==
-A URL is needed to extract data from Insight using the API module. The URL is constructed as follows: <br> <br>
+An API key is required for some functionality between Insight and PARS. These functions are: <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>
@@ Line 51: / Line 75: @@
 '''403.16 invalid api key'''<br>
-''The API key used is not found in Insight'' <br> <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 not allowed'' <br> <br>
+''The IP address that the request was sent from is forbidden'' <br> <br>
 '''403.18 invalid operation''' <br>
-''The operation requested by the application does not exist in Insight'' <br> <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 operation for which the API key does not have permission'' <br> <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 identifying number for a student is required, but has not been specified by the application'' <br> <br>
+''An <span style="color:#A0A>identifying number</span> for a student is required, but has not been specified by the application'' <br> <br>

@@ Line 14: / Line 14: @@
 |Key||This is a randomly generated string that cannot be changed
 |-
-|Description||The title given to the key
+|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]] when extracting data. This may affect the data that is extracted, for example by limited the date range over which behaviour information is extracted.

@@ Line 29: / Line 29: @@
 '''<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
 |-

@@ Line 9: / Line 9: @@
 New API keys are created using the Add button at the top of the page. An API key has the following options:
-{| border="1" style="border-collapse:collapse"
+{| border="1" style="border-collapse:collapse" cellpadding="5"
 !Field!!Purpose
 |-

@@ Line 42: / Line 42: @@
 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>''' 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>&upn=<span style="color:#A0A">N823432113104</span>''' <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>

@@ Line 45: / Line 45: @@
 '''<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==
-Worth remembering that Insight makes PARS run a Contact History Report to get Notices.
+The following error messages can be returned by Insight to an application attempting to use Insight's API: <br> <br>
--->
 [[Category:Management]]
 [[Category:Additional modules]]
 [[Category:Technical]]