TABLE OF CONTENTS
- Scope and target audience
- Prerequisites
- Definitions
- Request header
- Overview
- Using API together with Single Sign On
- User Identification
- Tags
- HTTP Status Codes
- Parsing JSON response format
- Information about phone number format
- Users
- Courses
Scope and target audience
This document describes the technical details of communicating with GO+ LMS.
Prerequisites
Contact TicTac support to enable the REST API for your portal. You authenticate with a basic key (X-API-KEY) added in the request header. This key will be given to you by TicTac Support.
Definitions
Your portal - the customized GO+ LMS portal for your organisation. In the examples below it’s described as https://x.onlineacademy.se where x is to be substituted by your portal’s name.
Request header
All request headers should be of the following content-type:
Content-type: application/x-www-form-urlencoded
The header shall also contain the X-API-KEY for authentication.
Overview
The REST API consists of a set of functions for automating and managing different areas of the GO+ LMS System; Users, Courses and Tag Trees. Users can either be uniquely identified based on email or username.
Using API together with Single Sign On
If GO+ LMS SSO (Single Sign On) is in being used together with the GO+ LMS REST API it is good to be aware that the ‘username’ mentioned in this document will correspond to what is referred to as the ‘id’ in the GO+ LMS SSO API documentation. So, both API and SSO will handle unique management and login of a user based on either email or username.
User Identification
Users can either be uniquely identified based on email or username. You can however still set and use both email and username. So, even if username is used as unique identifier the user can have an email set. However two users cannot have the same email. When making a request only one of email or username can be passed as a parameter in the call to identify the user.
Tags
User tags are referenced using the api id for the tag tree (a.k.a tag set) in combination with the tag id in the following format tagSetApiId:tagApiId (for example “org:production”). The tag name can be either the readable name or the tag api id. However, in order to guarantee unique reference the api id for the tag should be used.
Tag trees and tags can also be viewed and managed in the admin UI inside the online academy portal (https://x.onlineacademy.se where x is to be substituted by your portal’s name)
HTTP Status Codes
The main status codes used in the return values are listed below. The return data is in JSON format
For successful results:
200 - OK
In case of errors:
400 - Bad request
404 - Not found
Parsing JSON response format
The structure of the JSON in the responses is based on properties with values, objects or arrays. Properties that does not have a value will be an empty string or null.
For example "company": "" or "nextPage": null
Objects with no content will be null.
For example "passedDate": null
Empty Arrays will be empty square brackets
For example "tags": []
Information about phone number format
The phone number shall be using the E.164 format. E.164 is a standard for the phone number structure used for international telecommunication. Phone numbers that follow this format can have a maximum of 15 digits, and they are preferably prefixed with the plus character (+) and the country code.
NOTE: Country code is required if using SMS service in the portal.
Users
List all users
Description: Gets a list of all users in the system.
The level of details returned for each user can be configured. In order to manage listing of users in systems with more than 1000 users the output is paginated and callers need to make several calls to the list function.
Request method: GET
Request URL: https://x.onlineacademy.se/api/v2/users/list
Parameters:
|
Parameter name |
Type |
Required |
Description |
|
info |
string |
NO (default to “basic” if omitted) |
Level of detail for the result. Set to "basic" or "detailed". Basic will return the user’s properties. If set to details it will also include course status and the tags assigned to the user. |
|
page |
int |
NO (default is set to 0) |
Page to get if paginated result (0 index based) |
|
limit |
int |
NO (default is set to max value) |
Limit to use per page. The max value is 1000 users per page. |
Returns: Array of the users data. Depending on the info value it will be basic or detailed info. The result contains information about the total number of users and values to use in case the data is paginated. If there are more users to get the hasMore value will be set to true. Use the value of nextPage as the value of the page parameter in the next call to list users until the hasMore is returned with the value false.
Example:
{
"total": 168,
"hasMore": true,
"limit": "100",
"nextPage": 1,
"results":
[
{
"username": "username1",
"email": "email1@tictac.se",
"firstname": "Firstname1",
"lastname": "Lastname1",
"title": "Title1",
"company": "Company1",
"city": "City1",
"country": "Country1",
"phone": "+12345678901",
"language": "sv",
"active": true,
"additional1": "",
"additional2": "",
"courses": [
{
"id": 1,
"externalUid": "",
"name": "Course Name1",
"passed": false,
"passedDate": null,
"started": false,
"startedDate": null,
"addedDate": {
"date": "2018-10-18 12:55:24",
"timezone_type": 3,
"timezone": "UTC"
},
"mandatory": false
},
{
"id": 42,
"externalUid": "",
"name": "Course Name42",
"passed": true,
"passedDate": {
"date": "2018-01-10 15:25:33",
"timezone_type": 3,
"timezone": "UTC"
},
"started": true,
"startedDate": {
"date": "2018-01-10 15:24:48",
"timezone_type": 3,
"timezone": "UTC"
},
"addedDate": {
"date": "2018-01-10 15:24:48",
"timezone_type": 3,
"timezone": "UTC"
},
"mandatory": false
}
],
"tags": [
{
"tag": "org:tag1"
"name": "Tag 1",
"apiId": "tag-1",
"tagSetApiId": "org"
}
]
},
{
"username": "username2",
"email": "email2@tictac.se",
"firstname": "Firstname2",
"lastname": "Lastname2",
"title": "Title2",
"company": "Company2",
"city": "City2",
"country": "Country2",
"phone": "+12345678902",
"language": "en",
"active": true,
"additional1": "",
"additional2": "",
"courses": [
{
"id": 1,
"externalUid": "",
"name": "Course Name1",
"passed": false,
"passedDate": null,
"started": false,
"startedDate": null,
"addedDate": {
"date": "2018-10-18 12:55:24",
"timezone_type": 3,
"timezone": "UTC"
},
"mandatory": false
],
"tags": [
{
"tag": "org:tag1",
"name": "Tag 1",
"apiId": "tag-1",
"tagSetApiId": "org"
},
{
"tag": "org:tag2",
"name": "Tag 2",
"apiId": "tag-2",
"tagSetApiId": "org"
},
{
"tag": "tree2:tag3",
"name": "Tag3",
"apiId": "tag3",
"tagSetApiId": "tree2"
}
]
}
]
}
View user
Description: List a user's properties.
The level of details returned for the user can be configured. The detailed level will show tags assigned to the user and status about course progress in addition to the basic user info level.
Request method: GET
Request URL: https://x.onlineacademy.se/api/v2/users/user
Parameters:
|
Parameter name |
Type |
Required |
Description |
|
|
string |
YES (if username is not set) |
User email |
|
username |
string |
YES (if email is not set) |
Username. This could for example be the unique employee number or unique username string used in your system to identify users in case email is not used. |
|
info |
string |
NO (default to “basic” if omitted) |
"basic" or "detailed" |
NOTE: Only one of email or username can be passed as a parameter in the call to identify the user.
Returns: The users data. Depending on the info value it will be basic or detailed info.
Example:
{
"username": "username1",
"email": "email1@tictac.se",
"firstname": "Firstname1",
"lastname": "Lastname1",
"title": "Title1",
"company": "Company1",
"city": "City1",
"country": "Country1",
"phone": "+12345678901",
"language": "sv",
"active": true,
"additional1": "",
"additional2": "",
"courses": [
{
"id": 1,
"externalUid": "",
"name": "Course Name1",
"passed": false,
"passedDate": null,
"started": false,
"startedDate": null,
"addedDate": {
"date": "2018-10-18 12:55:24",
"timezone_type": 3,
"timezone": "UTC"
},
"mandatory": false
},
{
"id": 42,
"name": "Course Name42",
"passed": true,
"passedDate": {
"date": "2018-01-10 15:25:33",
"timezone_type": 3,
"timezone": "UTC"
},
"started": true,
"startedDate": {
"date": "2018-01-10 15:24:48",
"timezone_type": 3,
"timezone": "UTC"
},
"addedDate": {
"date": "2018-01-10 15:24:48",
"timezone_type": 3,
"timezone": "UTC"
},
"mandatory": false
}
],
"tags": [
{
"tag": "org:tag1",
"name": "Tag 1",
"apiId": "tag-1",
"tagSetApiId": "org"
}
]
}
Create user
Description: Adds a new user.
To update an existing user use the Update request instead.
Request method: POST
Request URL: https:/x.onlineacademy.se/api/v2/users/create
Parameters:
|
Parameter name |
Type |
Required |
Description |
|
|
string |
YES (if username is not set) |
User email |
|
username |
string |
YES (if email is not set) |
Username. Note: You can use both email and username. So even if the username is used as unique identifier the user can have an email set. However two users cannot have the same email. |
|
password |
string |
NO |
The password |
|
firstname |
string |
NO |
User first name |
|
lastname |
string |
NO |
User last name |
|
title |
string |
NO |
User title |
|
company |
string |
NO |
User company |
|
city |
string |
NO |
User city |
|
country |
string |
NO |
User country |
|
phone |
string |
NO |
User phone |
|
language |
string |
NO |
User language code. Can be used to set menu language initially.(It should be in two letter format like this: en, sv, no, dk fi, de etc.). |
|
active |
int |
NO |
If active = 1, inactive = 0 |
|
tags |
string |
NO |
Comma separated string with the user’s student tags in format tagSetApiId:tagApiId1, … , tagSetApiId:tagApiIdN. The tag groups govern which courses the user shall have access to. Ex: org:production, role:team-leader Api id:s for tags and tag sets can be edited in the Tags section in admin view of the portal when the “Show advanced settings” option is checked. Note: Tagset and tagApiId must not contain ‘,’ or ‘:’ as it is used as separators of the groups string. |
|
additional1 |
string |
NO |
Custom parameter that can be used for storing string data. On agreement with TicTac it can be connected to custom properties and logic in the portal. |
|
additional2 |
string |
NO |
Custom parameter that can be used for storing string data. On agreement with TicTac it can be connected to custom properties and logic in the portal. |
Returns: Successful return code listing the username and email for the user that was added.
Example:
{
"status": "User added",
"user": {
"username": "username1",
"email": "email1@tictac.se"
}
}
In case of an error instead, the following will be displayed:
{
"error": "User already exists"
}
Update user
Description: Updates an existing user.
Use the username or email parameter to identify the user. Parameters not passed will be ignored and its value will remain unchanged. To clear a string value set the parameter to an empty value in the request body. Note that tags can not be set to an empty value they can only be replaced via the API. To clear all tags set on a user you can use the admin UI.
To change the unique identifiers username and email it need to be done in the following way. Use one of the identifiers, i.e. current username or email, to identify the user. Then pass in new values in the newUsername and/or newEmail. Only use these parameters if you are actually changing them.
Note: In some cases users might need to be edited through the admin UI instead. If for example there are conflicting email with another user.
Request method: PUT
Request URL: https:/x.onlineacademy.se/api/v2/users/update
Parameters:
|
Parameter name |
Type |
Required |
Description |
|
|
string |
YES (if username is not set) |
User email |
|
username |
string |
YES (if email is not set) |
Username |
|
newEmail |
string |
NO |
New user email |
|
newUsername |
string |
NO |
New username |
|
password |
string |
NO |
The password |
|
firstname |
string |
NO |
User first name |
|
lastname |
string |
NO |
User last name |
|
title |
string |
NO |
User title |
|
company |
string |
NO |
User company |
|
city |
string |
NO |
User city |
|
country |
string |
NO |
User country |
|
phone |
string |
NO |
User phone |
|
language |
string |
NO |
Menu language code. Can be used to set menu language initially.(It should be in two letter format like this: en, sv, no, dk fi, de etc.) |
|
active |
int |
NO |
If active = 1, inactive = 0 |
|
tags |
string |
NO |
Comma separated string with the user’s student tags in format tagSetApiId:tagApiId1, … , tagSetApiId:tagApiIdN. The tag groups govern which courses the user shall have access to. Ex: org:production, role:team-leader Api id:s for tags and tag sets can be edited in the Tags section in admin view of the portal when the “Show advanced settings” option is checked. Note: Tagset and tagApiId must not contain ‘,’ or ‘:’ as it is used as separators of the groups string. |
|
additional1 |
string |
NO |
Custom parameter that can be used for storing string data. On agreement with TicTac it can be connected to custom properties and logic in the portal. |
|
additional2 |
string |
NO |
Custom parameter that can be used for storing string data. On agreement with TicTac it can be connected to custom properties and logic in the portal. |
NOTE: Only one of email or username can be passed as a parameter in the call to identify the user.
Returns: Successful return code listing the username and email for the user that was updated.
Example:
{
"status": "User updated",
"user": {
"username": "username1",
"email": "email1@tictac.se"
}
}
In case of an error instead, the following will be displayed:
{
"error": "User not found"
}
Delete user
Description: Deletes a user, this also removes all history for that user. This is irrevocable.
IMPORTANT: A user needs to be inactivated (via update user) before it can be removed.
Request method: DELETE
Request URL: https://x.onlineacademy.se/api/v2/users/delete
Parameters:
|
Parameter name |
Type |
Required |
Description |
|
|
string |
YES (if username is not set) |
User email |
|
username |
string |
YES (if email is not set) |
Username |
NOTE: Only one of email or username can be passed as a parameter in the call to identify the user.
Returns: Successful response if all was OK.
Example:
{
"status": "User deleted",
"user": {
"email": "email1@tictac.se"
}
}
Delete user by Username in Url
Description: Deletes a user by username, this also removes all history for that user. This is irrevocable.
IMPORTANT: A user need to be inactivated (via update user) before it can be removed.
Request method: DELETE
Request URL: https://x.onlineacademy.se/api/v2/users/deletebyusername
Url: https://x.onlineacademy.se/api/v2/users/deletebyusername/<username>
Returns: Successful response if all was OK.
Example: https://x.onlineacademy.se/api/v2/users/deletebyusername/user1
{
"status": "User deleted",
"user": {
"username": "user1"
}
}
Delete user by Email in Url
Description: Deletes a user by Email in url, this also removes all history for that user. This is irrevocable.
IMPORTANT: A user need to be inactivated (via update user) before it can be removed.
Request method: DELETE
Request URL: https://x.onlineacademy.se/api/v2/users/deletebyemail
Url: https://x.onlineacademy.se/api/v2/users/deletebyemail/<email>
Returns: Successful response if all was OK.
Example: https://x.onlineacademy.se/api/v2/users/deletebyemail/email1@tictac.se
{
"status": "User deleted",
"user": {
"email": "email1@tictac.se"
}
}
Courses
List courses
Description: Lists all courses in the system.
Request method: GET
Request URL: https://x.onlineacademy.se/api/v2/courses/list
Returns: Returns an array of all courses available in the system.
The estimatedTime is in number of minutes.
The externalUid is an optional value that can be enabled for the online academy admin UI. It enables the administrator to set an external id on the courses to reference to external systems. It can be a string of up to 128 alphanumeric characters.
The mandatory is an optional value that can be enabled for the online academy admin UI. It enables the administrator to set a value on the courses to reference to indicate to external systems if a course is mandatory or not. By default it is set to false.
Note: The directLink is only intended to be used together with regular log in to the onlineacademy. If using direct linking in combination with single sign on refer to separate description in the GO+ LMS SSO documentation.
Example:
[
{
"id": 1,
"externalUid": "",
"name": "Course Name1",
"description": "This text describes Course One",
"active": true,
"directLink": "http://x.onlineacademy.se/course/direct/1",
"estimatedTime": 60,
"externalUid": "",
"mandatory": false
},
{
"id": 42,
"externalUid": "",
"name": "Course Name42",
"description": "Course Description Text.",
"active": true,
"directLink": "http://xl.onlineacademy.se/course/direct/42",
"estimatedTime": 15,
"externalUid": "",
"mandatory": false
}
]