In this article
In this article you find the following information:
About assessmentQ
Before starting to integrate with assessmentQ, it's recommended to understand how assessmentQ works. If you're new to assessmentQ, you might want to start with this article to understand the flow of an exam in assessmentQ.
About the assessmentQ API
In general
The assessmentQ API is a REST API that can be used to integrate your own platform with assessmentQ. To facilitate this, some modules of assessmentQ are partially made available via the API. For example, the API can be used to schedule assignments, retrieve results, manage users and more. The REST API only works over HTTPS.
The assessmentQ API is designed according to the OData (Open Data Protocol) specifications. OData is an ISO/IEC standard that outlines best practices for building and using REST APIs. More information about OData can be found on the OData website: https://www.odata.org. Whenever the API returns a list, such as when retrieving all users, the response is limited to a maximum of 100 entities. In line with the OData specifications, it is possible to retrieve the next page by providing the correct OData parameters. The URL to retrieve the next page with up to 100 more entities is automatically generated in the API response by OData if there are more results.
Typically, development is not done on the assessmentQ production environment, but instead, a new environment is created for development in the assessmentQ demo (staging) environment. If a separate staging environment has not yet been set up for you, please contact the Televic Education Support team via support@televic-education.com.
Each organization using assessmentQ has a unique and dedicated subdomain, allowing access to assessmentQ at https://<subdomain>.assessmentq.com. Different parts of assessmentQ can be accessed through variations of this URL, where the subdomain is part of the URL in some cases. For instance, the API can be accessed at https://<subdomain>.api.assessmentq.com. The Swagger documentation for our API can also be found on this page. Every call described further in this document will work relative to this URL. For instance, if we mention "GET /v2/users", this means you should make a GET HTTP call to https://<subdomain>.api.assessmentq.com/v2/users, with your subdomain replaced in this URL.
Rate limiting
The assessmentQ API employs rate limiting. This means that only a limited number of requests can be made to the API within a certain time period. This is done to prevent overloading the API or its underlying components.
Rate limit information can be found in every API response, using four headers:
- X-Rate-Limit-Limit: The duration of the rate limit period, e.g., 1 hour or 1 minute.
- X-Rate-Limit-Remaining: The number of API requests that can still be made within this period.
- X-Rate-Limit-Reset: The UTC date and time when the rate limit will be reset.
- Retry-After: When no more API requests can be processed, this header will indicate how many seconds must be waited before making the next request.
It is strongly recommended to implement proper handling for these headers. If this is not implemented, and if there is no correct error handling, it may result in incomplete information flowing into assessmentQ.
Authentication
The assessmentQ API uses the Client Credentials Grant Flow to obtain an access token. You always need to provide a valid token with every call to the API. This token can be obtained from the assessmentQ Identity Provider. To obtain a token, an API key and secret must be provided in a token request to the Identity Provider.
Once a token has been retrieved, it must be included as an Authorization header in every API request. This token is a Bearer token. These tokens are only valid for a few minutes. The token's validity period can be read from the response of the Identity Provider when the token is obtained. When the token is expired, you need to request a new token using the same flow.
Overview of the authentication process
The necessary information (API key, secret, and Identity Provider URL) will be provided by the Televic Education Support team when initiating an API integration.
To request a token, you should add the scope "assessmentQApi" in your token request, next to your client ID and secret. This is a standard OAuth token request.
Error codes
In many API requests, exceptions, validation errors, etc., are possible. In the event of such errors, the API will always return an HTTP 422 code (Unprocessable Entity). The assessmentQ API will include an error code and reason in the response body. These reasons are documented in the Swagger documentation and should be handled correctly.
Example in our Swagger documentation of error codes and their reasons on a HTTP 422 response
Entities available through the API
Below, we briefly describe the capabilities of the API. In general, when retrieving a list of results, filtering and sorting can be done using OData.
Users
It is possible to create, update and delete users as well as manage their roles, retrieve their results and much more. For the full list, refer to our Swagger API documentation available at the root URL of the assessmentQ API.
Groups
It is possible to create, update and delete groups, assign to or remove users from groups, and more. For the full list, refer to our Swagger API documentation available at the root URL of the assessmentQ API.
Roles
It is possible to get a list of roles, and to assign to or remove a role from a user.
Items
The API calls around items are situated in our Authoring module and are related to items in your itembank. Items are used to create assignments. It is not possible to create, update or remove items through our API. The limited possibilities are to retrieve a list of items in your itembank, get the metadata linked to an item and to add, update or remove metadata keys to items.
Metadata
Metadata is a way to add extra information to items. This happens with metadata keys which can have one or more different values when you link them to your item. Metadata keys are managed in metadata libraries. Through our API it is possible to retrieve a list of all metadata keys, retrieve a list of all metadata libraries, retrieve a list of all values for a metadata key of the type "dropdown" and to retrieve a list of all items which have a certain metadata key linked to it.
Assignments (Publications)
An assignment is a set of items that are grouped into a test or exercise. This assignment can then be scheduled for one or more participants. It is possible to manage assignments through the assessmentQ API, but there are a few specific limitations. These are also documented on our Swagger API documentation page.
Note: It's important to note that assignments were called publications in early versions of assessmentQ. In the assessmentQ API you might still see references to publications, these refer to an assignment.
Tags
Tags provide a way to link extra information to an assignment or schedule. This can be useful in an integration as well. For instance, you could add topics like "Maths", "Physics", etc. as a tag to an assignment or schedule. This could then be used to filter assignments or schedules with your API. It is not possible to assign tags through the API, but they can be read to get extra information about your assignments or schedules.
Schedules
A schedule can be used to plan one or more assignments (publications) for one or more users during a certain period. All assignments should be planned through a schedule. There are different types of schedule available in assessmentQ. Depending on your use case, you might have a preference for a certain type of schedule. The API enables the retrieval, creation, updating, etc. of a schedule.
Sessions
A session is one attempt of one participant for one assignment. A session has for example information on the score of the participant on the assignment for this attempt, how much time was spent, etc. Sessions can be managed through our API. It is possible to retrieve sessions, get a detailed report of a session, get the items that were offered in a session, and more.
Logging
During a session, assessmentQ has extensive logging of what happens in the session. For example, all navigations between questions are logged, when an answer has been changed, if any of the helping tools has been opened, and more. You can retrieve all of this logging through our API as well.
Resthooks
Finally, our API also offers resthooks to be used. These hooks serve as a sort of notification which we can send to your systems, e.g. when a session has been finished. This can enable you to get the results as soon as a session finishes without having to poll our API constantly. This approach is recommended.
Example API integration
Description of the example setup
For the purpose of this example, we assume a fictional integration with a Learning Management System (LMS). We want to retrieve user data from the LMS, we want to schedule assignments through our integration, and we want to collect results. This will end up in a basic integration example, but a lot of variations are possible. Feel free to contact the Televic Education Support team via support@televic-education.com if you need more guidance on which flow works best for your integration needs.
Global view on where the API is situated
We will assume that the LMS users want to schedule an assignment in assessmentQ directly. To do this, they will get a list of possible assignments which exist in assessmentQ in their LMS. Once scheduled, the assignment should appear in assessmentQ for all candidates. After the session has been finished, the LMS should be able to get the results.
1. Get the available assignments
In a first step, we need to feed the LMS with the possible assignments. This way, the LMS knows which assignments can be scheduled for its users. To do this, we would use the following API call:
GET /v2/publications
In assessmentQ an assignment has a status which indicates if the assignment is ready to use, already has sessions, etc. It's only possible to schedule an assignment if the assignment has been approved or has the status Live. When we perform this call, a list of all available assignments is returned. We can use OData to filter this list further so that only the assignments with the relevant statuses are returned. To do this, we can use:
GET /v2/publications?$filter=(status eq 'Validated' or status eq 'Live')
With this information, the LMS now knows which assignments can be offered to the participants. Optionally we could for example also retrieve the tags linked to the assignments if this would contain extra information which can be used to filter the assignment list for some users.
2. Create or update the candidate
When the decision has been made in the LMS to schedule a certain assignment for one or more users, we need to make sure those users exist in assessmentQ. We can create a user with the following API call:
POST /v2/users
This call will only create the user if he don't exist already. This check happens based on the e-mail address. This means it's not really necessary to check if the user already exists before executing this call, but optionally it could be done using:
GET /v2/users?$filter=email eq 'johndoe@televic-education.com'
If you were to use an own identifier to keep track of your users in assessmentQ, you could use the ExternalId field. You can then also use that field to retrieve the user via the API:
GET /v2/users?$filter=externalId eq 'yourExternalIdHere'
Please note that the ExternalId field is also used for a Single-Sign-On. If you also use a Single-Sign-On, make sure you use the same identifiers as your identity provider.
3. Create a schedule
Now you know which assignment to schedule and for which users. You have the assignment ID and the user ID's that apply for assessmentQ. This is enough information to go to our next step: creating the schedule in assessmentQ. To do this, we can use the following API call:
POST /v2/schedules
In this call, you need to provide the assignment(s) you wish to schedule, and for which user(s) this schedule applies. There are some optional parameters as well, like e-mail notifications or if the results should be available to the participants after finishing their session(s) in the schedule.
An important setting you should also pass here is the "Delivery Type". This matches with the type of schedule you would choose if you were to create this schedule manually in the assessmentQ backoffice. You can for example choose "Portal" as a delivery type, and then the schedule will be visible on the portal after the participant signs in to assessmentQ. An other option would be to use our sign-in codes, and then retrieve those sign-in codes with the API call:
GET /v2/schedules/{id}/signincodes
When using this flow, these personal sign-in codes can be used by the candidate to start their assignment(s) immediately without having to sign in. The code signs the participants in and brings them immediately to the schedule. Sign-in codes should always be treated very carefully because of this. A participant has to navigate to https://<subdomain>.assessmentq.com/code to use their sign-in code.
4. Retrieval of results
The retrieval of the results can happen in a couple of ways. The essence is that you can retrieve a detailed report of the session using the following call:
GET /v2/sessions/{id}/report
This API call will return by default the score, duration, score per part and much more. As you can see, the API call requires you to have the session ID. There are two possible ways to get this ID.
The first and most recommended way to do this would be to use our resthooks. This is a way to subscribe to events in assessmentQ, much like an instant notification when something happens. You can use this, to get notified whenever a session is finished by a participant. When the resthook is triggered, you will receive an API call from us, which contains the session ID. Based on that, you can then call the API call above to get detailed reporting on that session. It's possible to register a resthook with the API call:
POST /v2/subscriptions
For the purpose of retrieving the results immediately after a session has been finished by the participant, you would need to subscribe to a resthook of the type "SessionFinished".
A second possibility to get the session ID's which exist in a certain schedule, would be to use the following API call:
GET /v2/schedules/{id}/sessions
This approach is only recommended if you know when results are available. If you don't know when results are available, this approach would need to call our API at regular intervals to check if there are results available. This would be much more inefficient compared to the approach with the webhooks described above.
Possible additions to this example integration
The use of group responsibles for reporting
The example integration described above can serve as some inspiration for a very basic integration with assessmentQ. A lot more possibilities are available.
Imagine you have a setup where one person is responsible for a group of participants, and you wish to make the results of this group of participants available to their responsible in assessmentQ itself. However, this assignment is used throughout the organisation, and you do not wish to make all results of all participants available, they should only see the results of the participants they're responsible for. To do this, you can make use of groups. These groups can get one or more "group responsibles" assigned to them. These group responsibles have access to the reporting modules in the assessmentQ backoffice, they will see the results of the participants in the group(s) they're responsible for, and this for all the assignments they have access to. It's also possible to configure access to all assignments, this depends on the rights assigned to the backoffice user through their roles. Even then, they will only see results of the participants in the groups they're responsible for.
If you were to extend your integration with this feature, you'd need a couple of things. First off, you would need to link the correct role in assessmentQ to these backoffice users. This can easily be done with the following API call:
PUT /v2/users/{userId}/role/{roleId}
Note that it's not possible to create or edit roles through the API. You will need to create needed role beforehand, and then use this role to assign to the users. You can either get the role ID out of assessmentQ manually, or retrieve a list of roles through our API.
When the backoffice user has the necessary role to see the reporting, we should create the groups and assign the group responsibles. We can easily create groups in assessmentQ with the API call:
POST /v2/groups
After creating the group, you can add users in the group with:
POST /v2/groups/{id}/users/{userId}
The same applies to add a group responsible. To add a group responsible, you can use:
POST /v2/groups/{groupId}/responsibles/{userId}
This should make the reporting available to the responsible user for the assignments they have access to.