• Introduction
• Quick start
  • LTI
    • Connexion
      • LTI 1.1
      • LTI 1.3
    • Environments
    • Use a service
    • Example
  • API
    • Connexion
    • Environments
    • Use a service
    • Example
• Actions
  • Candidate and tests
    • Create a candidate
    • Add a test to a candidate
    • Create a candidate and take test
    • Add/remove online proctoring to a test
    • Delete a test
    • Add a confirmation test to a completed test
    • Update a candidate
    • Delete a candidate
  • Emails
    • Send registration email
  • Results
    • Get PDF results
    • Get results as a JSON
    • Get results details as a JSON
    • Get test status
  • Administration
    • Create a session
    • Anonymize a candidate
    • Log-in as an administrator
    • Log-in as a candidate
    • Get available tests list
    • Get available credits
• Appendices
  • Language codes
  • Distributor accounts
  • LTI - Grades via Basic Outcome Service

Introduction

The aim of this document is to describe how to use the services the Isograd system offers, either to LTI consumers or via the API.

Quick start

LTI

Connexion

Isograd plateform is compatible with both LTI 1.1 and LTI 1.3 protocols

LTI 1.1

Your system should include an area to define LTI providers. In this area, you must:

• Give a name to Isograd LTI Provider
• Specify your client key
• Specify your client secret Your client key and your client secret will be provided by Isograd upon request.

LTI 1.3

What we require from you

What we will provide to you

Environments

There are two environments, one for testing and the other for production:

• Testing: https://recette.isograd.com/public/lti.php
• Production : https://app.isograd.com/public/lti.php

Use a service

Most of the calls made to Isograd LTI Services require custom parameters to indicate what you want to achieve. Your system should include the possibility to add custom parameters in your LTI messages.

Example

To manually test your requests, you can use the LTI Emulation tool accessible here: https://saltire.lti.app/platform. Below is an example of such a test:

API

Connexion

The authentication is done via OAuth. To get a token, you need to make a POST request to the following URL:

https://auth.isograd.com/oauth2/token?grant_type=client_credentials&scopes=usage

This call must contain two fields: client_id and client_secret. The content of these fields must be the two values Isograd’s team provided you with once your account is created.

Environments

There are two environments, one for testing and the other for production:

• Testing: https://recette.isograd.com/api/usage
• Production : https://app.isograd.com/api/usage

Use a service

To use a service, make a POST request to the URL of the chosen environment. The header must contain the field Authorization: Bearer <your_token>.

Example

Here is a Python script retrieving an access token, and using the service to create a candidate

import requests

# Retrieve the access token
credentials = {
    'client_id': 's0u2c72bman19nm2c45oi1fpea',
    'client_secret': '1mio0273po6si9tvt2f3ld5t6o4hsg02epq71rlfdhlkombkv8ro',
}
auth_url = 'https://auth.isograd.com/oauth2/token?grant_type=client_credentials&scopes=usage'

r_token = requests.post(auth_url, data=credentials)
access_token = r_token.json()['access_token']

# Use the service
headers = {'Authorization': 'Bearer ' + access_token}
url_dev = 'https://recette.isograd.com/api/usage'

payload = {
    'act_id': 1,
    'gen_id': 3,
    'ema': 'test@isograd.com',
    'fst_nam': 'John',
    'lst_nam': 'Doe',
}

r_action = requests.post(url_dev, data=payload, headers=headers)
print(r_action.json())

The returned JSON object is like so:

{
    'error_message': null,
    'success': true,
    'can_id': 1381134,
    'lgn_url': 'https://recette.isograd.com/continuelogin/CandidateContinueLogin?param=UVR1WjgwRXBwU0'
}

Actions

All your actions must contain a parameter act_id that contains the action you want to do: these actions and the parameters that must be sent are described in this section. For every parameter, there will be an indication of whether or not it is required:

• 🟩 Required parameter
• 🔷 API: Required parameter LTI: parameter already sent via the LTI protocol, do not include it in the additional parameters
• 🟠 Optional parameter

The answer will be a JSON object, containing a boolean success: if true, additional properties are sent depending on the action. If false, an error_code and an error_message will be included. Here are the general error messages (additional codes specific to each actions are provided later in this document)

Candidate and tests

Create a candidate

The response is a JSON object containing the following properties:

• can_id: unique integer id of the created candidate on Isograd’s platform
• lgn_url: a url that can be used by the candidate to login into the platform without entering any credentials. This url is only valid for 30 minutes

Errors

Add a test to a candidate

The response will be a JSON object (unless html or redirect are set to 1) containing the following properties:

• tst_url: the URL that will automatically start the specified test
• pla_tst_id: integer ID of this test for this candidate in Isograd’s platform

Note: if the candidate has an unfinished test and act_id is set to 2, the response will contains the unfinished test’s details.

Errors

💡 Note: Most systems connecting to the Isograd platform will set the optional redirect parameter to true as it allows to have the standard expected behaviour: the candidate clicks on a link in the LMS and the test starts automatically.

Create a candidate and take test

The system will perform successively the Create Candidate and Add a Test actions described above. Consequently, the return structure will be similar to Add a Test action and all the parameters required or optional in the Add Test and Create Candidate actions may be provided.

Add/remove online proctoring to a test

The response will be a JSON object containing no specific property.

Errors

Delete a test

The response will be a JSON object containing no specific property.

Errors

Add a confirmation test to a completed test

The response will be a JSON object (unless redirect is set to 1) containing the following properties:

• tst_url: the URL to start the confirmation test.

Update a candidate

Delete a candidate

The response will be a JSON object containing only a success property.

Emails

Send registration email

This action enables to send a registration email to the candidate immediately or in the future. A specific email sender may be provided.

A can_id or a pla_tst_id must be provided, if both are provided, the pla_tst_id will be used.

The response JSON only includes a success field

Results

Get PDF results

The response will be a JSON object (unless redirect is set to 1) containing the following properties:

• pdf_url: the URL of the PDF report

Errors

Get results as a JSON

The response will be a JSON object containing the following properties:

• gra_typ_id: an integer representing the grade type (see the possible values below)
• num_val: a number representing the numeric value of the grade
• max_val: a number representing the maximum value corresponding to the gra_typ_id
• txt_des: a text description of the grade (e.g. “550/1000” or “Intermediate – 3/5”)
• no_sto_tim_spe: the difference expressed in seconds between the start time and the end time of the test. (This time may not correspond to the time spent by the candidate on the test as he or she may have the option in some cases to stop the test and restart it later).

The potential values for gra_typ_id are:

Get results details as a JSON

The response will be a JSON object containing the following properties:

• des_lan_id: the language used the result details. If no description is available in the requested language, English will be used by default.
• result_details: an array where the keys are the skill IDs and values are an array composed of values whose keys are:
  • des: skill description
  • (for tests based on IRT) level: Decimal number representing the level obtained by the candidate. A value of -1 means the candidate has not been tested on this skill.
  • (for tests based on IRT) level_des: Brief text description of the candidate’s skills at this level.
  • (for tests based on IRT) scalemin: Minimum value of level
  • (for tests based on IRT) scalemax: Maximum value of level
  • (for tests NOT based on IRT) successrate: Success rate on questions belonging this skill. This is a decimal value equal to -1 or between 0 and 1. A value of -1 means the candidate has not been tested on this skill.

Get test status

The response will be a JSON object containing the following properties:

• sta_id: an integer representing the status of the test:
  • 1: not started
  • 2: started
  • 3: completed
  • 4: marking pending (for tests that include manual marking)

Errors

Administration

Create a session

The response will be a JSON object containing the following properties:

• ses_id: An integer representing the unique ID of the session

Anonymize a candidate

Their first name, last name and email address will be replaced by numbers in Isograd’s database. This also affects their diploma(s).

The response will be a JSON object containing no specific property.

Log-in as an administrator

⚠️ Be very careful not to provide access to this request to candidates as they would access your account on the platform and would be able to create candidates, see results, add tests, etc.

⚠️ This method, like all others, includes an optional sub_com_id parameter for customers who use sub accounts. If the parameter sub_com_id is not provided, the sub account administrator will be logged as a master account administrator which could raise serious data confidentiality issue.

The response will be a HTTP redirection to the Admin module

Log-in as a candidate

The response will be a HTTP redirection to the candidate’s account page, where they can access their:

• Tests to take
• Diplomas
• Assessment reports
• Questions and correct answers for assessment tests.

Get available tests list

The response will be a JSON object containing the following properties:

• tests: An array of the IDs of the allowed tests.

Get available credits

The response will be a JSON object containing the following properties:

• credits: an array of that contains for each type of credits the following properties:
  • des: credit type description
  • amount: credit amount

Appendices

Language codes

The following values must be used to specify languages:

• 1: French
• 2: English
• 3: German
• 4: Dutch
• 5: Spanish
• 6: Italian
• 7: Greek
• 8: Arabic

Distributor accounts

Distributor accounts can perform actions on sub accounts that belong to them using the credentials of the distributor account. In such case an additional parameter sub_com_id can be added to the request to specify on which sub account the action should be performed.

This integer sub_com_id can be added to all actions described in the section Action.

LTI - Grades via Basic Outcome Service

Isograd LTI provider service can return grades through the LTI 1.1 Basic Outcome Service. This allows your system to receive the grade of the candidate automatically at the end of the test. If you wish to receive the grade through Basic Outcome Service, please contact Isograd support to request its activation on your account.

LTI Basic Outcome Service only allows a grade as a decimal number between 0 and 1. The different grade types are converted into a decimal number between 0 and 1 according to the below rules:

• LEVEL_GRADE_TYPE = 1, the level divided by 10
• SCORE_GRADE_TYPE = 2, the score divided by 1000
• AVERAGE_GRADE_TYPE = 3, the score divided by 1000
• NUM_CORRECT_GRADE_TYPE = 4, the percentage of correct answers that is: number of correct answers / number of questions
• RANGE_GRADE_TYPE = 5, the middle value of the relevant range divided by 1000
• ON_100_AVERAGE_GRADE_TYPE = 15, the score divided by 1000 </div>