Support

Integration

Walkthroughs

About the OPEN ELMS API

About the OPEN ELMS API

The Open Elms API is a RESTful web service and uses token authenticate 3rd party applications. Before starting to use the Open ELMS API you will need to contact support@e-learningwmb.co.uk to obtain a key in order to access this service.

The API enables third party applications to control Open Elms features by communicating between the systems.

The API can be used for a variety of purposes such as:

  • The management of users (add/remove/delete) from HR systems
  • Assigning user to learning resources within Training Management Systems
  • Listing learning resources in the system
  • Editing learning from within a third party Learning Management System
  • Running and recording elearning from a third party Learning Management System

Use the menu on the right hand side to access the instructions for authenticating and then using the API. Open eLMS staff are on stand-by to help with any queries you may have, contact support for further details.

A summary of HTTP Response Codes returned is shown below:
HTTP Code Summary Description
200 OK Successful API call.
400 Bad Request A validation exception has occurred.
401 Unauthorized Invalid authorization credentials.
404 Not Found The resource you have specified cannot be found
412 Precondition Failed One or more conditions given in the request header fields were invalid.
500 Internal Error An unhandled error. Contact the Open Elms team if problems persist
501 Not Implemented The method you have called has not been implemented (e.g. POST Organisation)
503 Rate Limit Exceeded The API rate limit for your organisation/application pairing has been exceeded.
503 Not Available API is currently unavailable – typically due to a scheduled outage – try again soon.

Getting the authentication token

Access is controlled is token based. The value of the token is configured in Open LMS at System Setup/Defaults/Configuration/APITokenAccess.

When calling the API, you need to pass the token value in an HTTP “Authorization” header – the value of the header should be “Basic ####”, where #### is the value of the APITokenAccess configuration option (see screenshot below). A 403 (Forbidden) error will be thrown if authentication fails. Below is a screenshot of a REST API which is used to invoke the API

An example of calling the API with a REST client. The value of the token (‘12345’) is given in the HTTP Authorization header.

User Commands

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/users/
Method
POST
Description
Creates a new user account.
Note: groups_id can be a comma separated string of group ids to assign multiple groups, if groups_id is set to an empty string then it will remove that user from all groups. If the user is assigned to a group which has learning assigned to it, then the new user will automatically have that learning assigned to their account.
Form Data

We have separated the form data into different categories for ease of use:

Required fields

  • fname – User’s first name
  • lname – User’s last name
  • username – User’s username
  • email – User’s email
  • password – User’s password

Optional fields

  • department – User’s department (created if not found in the database)
  • department_address – Department address
  • department_postcode – Department post code
  • city – User’s city (created if not found in the database)
  • company – User’s company (created if not found in the database)
  • country – User’s country (created if not found in the database)
  • job – Job title (created if not found in the database)
  • groups – groups can be a comma separated string of group ids to assign multiple groups.
  • phone – User’s phone
  • week_hours – Working Week hours
  • manager_name – Manager’s name
  • manager_job_title – Manager’s job title
  • manager_email – Manager’s email

ILR main fields

  • AddLine1
  • AddLine2
  • AddLine3
  • AddLine4
  • Postcode
  • Sex (M or F)
  • Ethnicity – ethnicity (a numeric id, * check to see how to retrieve the id value)
  • LLDDHealthProb – disability status (a numeric id, * check to see how to retrieve the id value)
  • DateOfBirth
  • NINumber – National Insurance number

ILR Employment Status fields

  • EmployerX_EmpStat – Employment status
  • EmployerX_DateEmpStatApp – Date employment status applies (date, will try to parse any format)
  • EmployerX_EmpId – Employer identifier
  • EmployerX_AgreeId – Agreement identifier

ILR Employment Status Monitoring fields

  • EmployerX_SEI – Is the learner self employed? (set to 1 if yes)
  • EmployerX_PEI – Was the learner in full time education or training prior to enrolment? (set to 1 if yes)
  • EmployerX_SEM – Small Employer (set to 1 if yes)
  • EmployerX_LOU – Length of unemployment (a numeric id, * check to see how to retrieve the id value)
  • EmployerX_BSI – Benefit status indicator (a numeric id, * check to see how to retrieve the id value)
  • EmployerX_EII – Employment intensity indicator (a numeric id, * check to see how to retrieve the id value)
  • EmployerX_LOE – Length of employment (a numeric id, * check to see how to retrieve the id value)

Note: X can be any number between 1 and 5. In other words you can up to five employment status records by using Employer1_{field_name}, Employer2_{field_name}, etc.

* Retrieving valid values for numeric ids

Possible values of numeric ids can be retrieved through the following service:

GET backend/user/fields

It results in a JSON which contains all the possible values for each user field, as well as their labels

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/users/{USER_ID}
Method
PUT
Description
Updates new user account
Note: groups_id can be a comma separated string of group ids to assign multiple groups, if groups_id is set to an empty string then it will remove that user from all groups. If the user is assigned to a group which has learning assigned to it, then the new user will automatically have that learning assigned to their account.
Form Data

We have separated the form data into different categories for ease of use:

Required fields

  • fname – User’s first name
  • lname – User’s last name
  • username – User’s username
  • email – User’s email
  • password – User’s password

Optional fields

  • department – User’s department (created if not found in the database)
  • department_address – Department address
  • department_postcode – Department post code
  • city – User’s city (created if not found in the database)
  • company – User’s company (created if not found in the database)
  • country – User’s country (created if not found in the database)
  • job – Job title (created if not found in the database)
  • groups – groups can be a comma separated string of groups to assign multiple groups.
  • phone – User’s phone
  • week_hours – Working Week hours
  • manager_name – Manager’s name
  • manager_job_title – Manager’s job title
  • manager_email – Manager’s email

ILR main fields

  • AddLine1
  • AddLine2
  • AddLine3
  • AddLine4
  • Postcode
  • Sex (M or F)
  • Ethnicity – ethnicity (a numeric id, * check to see how to retrieve the id value)
  • LLDDHealthProb – disability status (a numeric id, * check to see how to retrieve the id value)
  • DateOfBirth
  • NINumber – National Insurance number

ILR Employment Status fields

  • EmployerX_EmpStat – Employment status
  • EmployerX_DateEmpStatApp – Date employment status applies (date, will try to parse any format)
  • EmployerX_EmpId – Employer identifier
  • EmployerX_AgreeId – Agreement identifier

ILR Employment Status Monitoring fields

  • EmployerX_SEI – Is the learner self employed? (set to 1 if yes)
  • EmployerX_PEI – Was the learner in full time education or training prior to enrolment? (set to 1 if yes)
  • EmployerX_SEM – Small Employer (set to 1 if yes)
  • EmployerX_LOU – Length of unemployment (a numeric id, * check to see how to retrieve the id value)
  • EmployerX_BSI – Benefit status indicator (a numeric id, * check to see how to retrieve the id value)
  • EmployerX_EII – Employment intensity indicator (a numeric id, * check to see how to retrieve the id value)
  • EmployerX_LOE – Length of employment (a numeric id, * check to see how to retrieve the id value)

Note: X can be any number between 1 and 5. In other words you can up to five employment status records by using Employer1_{field_name}, Employer2_{field_name}, etc.

* Retrieving valid values for numeric ids

Possible values of numeric ids can be retrieved through the following service:

GET backend/user/fields

It results in a JSON which contains all the possible values for each user field, as well as their labels

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/users/{USER_ID}
Method
GET
Description
Retrieves a list of user accounts. {USER_ID} is optional – if given, then only the details of the specified account are returned.
Return value

A list of user accounts, including the following fields:

Fields
usernameUsername
employee_idEmployee ID
emailEmail address
fnameFirst name
lnameLast name
countryCountry record
cityCity record
companyCompany record
departmentDepartment record
locationLocation record
jobJob record
groupsA collection of group records
learningA collection of learning resource records

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/users/?{FIELD_NAME1}={FIELD_VALUE1}&{FIELD_NAME2}={FIELD_VALUE2}..,
Method
GET
Description
Retrieves a list of user accounts which match the given criteria. Currently, the following search fields are supported: fname, lname, username, usercode, email, company_id, department_id, country_id, city_id, location_id, group_id
Return value

A list of user accounts, including the following fields:

Fields
usernameUsername
employee_idEmployee ID
emailEmail address
fnameFirst name
lnameLast name
countryCountry record
cityCity record
companyCompany record
departmentDepartment record
locationLocation record
jobJob record
groupsA collection of group records
learningA collection of learning resource records

Learning Commands

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/assign/{USER_ID}/{L_ID1, L_ID2, L_ID3 etc}
Method
PUT
Description
This adds to the learner the learning resource specified by the learning ID. Multiple learning IDs (L_ID1, L_ID2, L_ID3 etc.) can be added by using a CSV list as is shown above.

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/unassign/{USER_ID}/{L_ID1, L_ID2, L_ID3 etc}
Method
DELETE
Description
This removes from the learner the learning resource specified by the learning ID. Multiple learning IDs (L_ID1, L_ID2, L_ID3 etc.) can be added by using a CSV list as is shown above.
Return value
User id

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/{LEARNING_ID}
Method
GET
Description
List available learning resources. {LEARNING_ID} is optional – if given, then only the details of the specified learning resource are returned. If the learning resource is a SCORM one, then its download link is also returned.
Return value
A list of learning resources, including learning id, name, learning type and an optional download link.

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/download/{LEARNING_ID}
Method
GET
Description
Downloads a SCORM learning resource. Note that this service only works for e-learning (i.e. SCORM) learning resources.
Return value
The SCORM files compressed in a single ZIP file.

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/download-container/{LEARNING_ID}
Method
GET
Description
Downloads a SCORM learning resource container. Note that this service only works for e-learning (i.e. SCORM) learning resources. Container serves files directly from e-learningWMB servers. Container does not hold SCORM files. Configuration option “allowSCORMContainerPlayer” must be set to true to allow playing of containers
Return value
The SCORM container files compressed in a single ZIP file.

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/new-resource
Method
POST
Description
Create new e-learning resource, type is optional.
Form data
name*, type(audit, elearning, elearning_quiz, induction, mp4_quiz, quiz, skillscan, vimeo_quiz, youtube_quiz)
Return value
Learning resource ID(string)

Open eLMS Creator Command

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/creator-url/{LEARNING_ID}
Method
GET
Description
Returns a one time URL that can be opened in the browser and will load the jackdaw editor for a given resource. New requests will make earlier URL non functional.
Return value
Open eLMS Creator URL (string)

Learning progress

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/{LEARNING_ID}/trainees/{USER_ID}
Method
GET
Description
Returns the learning status of the trainees assigned to a given learning resource. If {USER_ID} is specified, then the learning status of just the trainee with the given user_id is returned.
Return value
JSON array containing the completion status (‘not attempted’, ‘in progress’, ‘completed’ or ‘failed), numeric score (null if not completed) and the date of completion (null if not completed) of the corresponding learning result

URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/{LEARNING_ID}/{USER_ID}/{ACTION}/{SCORE}
Method
PUT
Description
Updates the learning status of the given user for the given course. There are two possible updates which are determined by the type of action. If action is ‘start’, then the learning resource is marked as ‘in progress’. If the action is ‘complete’, then the resource is marked as ‘complete’. If the action is ‘fail’, then the course is marked as failed. The score is an option numeric parameter, which is only used for ‘complete’ and ‘fail’.
Return value
JSON array containing the completion status (‘not attempted’, ‘in progress’, ‘completed’ or ‘failed), numeric score (null if not completed) and the date of completion (null if not completed) of the corresponding learning result