LAMS Integrations API
Last updated
Was this helpful?
Last updated
Was this helpful?
Recommendation!
We strongly recommend to use IMS LTI 1.3 or above as the main integration specification. While this integration works fine, standardasing is a better idea now that IMS LTI has proper extensions.
LAMS provides the API described in this page to create rich and powerful interaction with any 3rd party system. The aim for this integration is to make LAMS appear into an LMS system like yet another native tool of the LMS.
LAMS has natively been integrated with:
Blackboard
Moodle | Check out the LAMS-Moodle demo
Sakai
And any other that uses IMS LTI.
In this document, we present a technical overview on how these integrations are implemented. Although each 3rd party applications are different (even they are in different programming languages) the principles that we follow are essentially the same.
The following diagrams give the overview and the details of the LAMS and 3rd party app SingleSignOn implementation:
Every time a LMS user attempts to access LAMS and there's no personal details passed, LAMS will check to see if the user exists in its database. If the user has not been created in LAMS, LAMS will make a call to the external application to retrieve user information and create the user on the fly. Therefore you will need to set up a user information servlet on the LMS side that will return user information to LAMS.
Note that the callback URL will only take place if the firstName, lastName parameters were not passed with the LoginRequest, LearningDesignRepository or LesssonManager (join method). See below.
If you are passing the user details as parameters in the requests, then there will be no call back to the LMS and the user will be created with the details passed.
Request format
The user information url is defined in the LAMS System Administration page and contains three parameters: username, timestamp and hash.
For example, the url for moodle is given by:
http://localhost/moodle/mod/lamstwo/userinfo.php?ts=%timestamp%&un=%username%&hs=%hash%
The hash value is generated using the SHA1 algorithm on the following (all in lower case) [ timestamp + username + serverID + serverKey ]
Response Format
The response from the external application is a comma separated list of 14 values
<Title>,<First name>,<Last name>,<Address>,<City>,<State>,<Postcode>,<Country>,<Day time number>,<Mobile number>,<Fax number>,<Email>,<Locale language>,<Locale country>
In order to enable import and usage of the groups created on the integrated server (Blackboard only), one needs to go to the LAMS System Administration page and enter External groups URL property following the next format:
https://<BB_SERVER>:8443/webapps/lams-lamscontent-BBLEARN/GroupData
After this one be able to select and use external groups at the monitoring page of the lesson created via that integrated server.
Request for author, learner and monitor are directed through the LoginRequest servlet. For example:
http://localhost/lams/LoginRequest?....
The parameters are:
Parameter
Description
Restriction/conditions
uid
The username on the external system
Must be unique. Only alphanumeric characters and these symbols allowed "_" "-")
ts
Number of milliseconds since January 1, 1970, 00:00:00 GMT (known as "the epoch") till the time when the call is made
Required if according integrated server has "Enforce time limitation" setting ON. And if it's OFF it can be a random String.
sid
serverID (see integration configuration)
method
Either author, monitor, learner or learnerStrictAuth; it sets permissions and redirects user to requested content
Must match one of the methods' name
hash
A SHA1 hash of [ts + uid + method + serverID + serverKey] (Note: all lower case before hashing) If you are using the learnerStrictAuth, you must include the lsId in the hash (see below)
mode
Additional directive: "preview" for previewing lesson in learner, "gradebook" to access user gradebook after logging in
courseid
the id of the course from the LMS
Must be unique for each LMS course
lsid
Used for monitor, learner and gradebook to tell LAMS the lesson id you want to open
Required if requesting access to monitor, learner or gradebook UIs
firstName
Used if a new user is created
No numbers or special characters permitted
lastName
Used if a new user is created
No numbers or special characters permitted. Only single quotes and spaces allowed ie: O'Harries or Garcia Marquez)
Used if a new user is created
Correctly validated email address required
country
lang
isUpdateUserDetails
"true" in case user details should get updated with new information, "false" (or no parameter) otherwise
requestSrc
String to identify who is making the call, this is only used in authoring to display on the close button.
notifyCloseURL
Callback URL to refresh the page after a sequences has been added.
You can use either http method POST or GET.
POST highly preferred!
LAMS course roles are learner, monitor and author.
Therefore passing a method with one of these roles will assign the user the following LAMS course roles
Method
Grants roles
Author
learner, monitor and author
Monitor
monitor
learner
learner
learnerStrictAuth
learner
The learnerStrictAuth method Use the learnerStrictAuth method when launching students into lessons
While you can use the method=learner to launch learners into a LAMS lesson, it is strongly recommended that you use the method=learnerStrictAuth instead.
When you use learnerStrictAuth, you also include the lessonID (lsId) that the user is being launched to into the authentication hash. This prevents any tampering and ensures that the user always goes to the correct lesson.
The main difference within the LoginRequest as explained before is that you use the method "learnerStrictAuth" and include the lsId in the hash as follows:
hashText = ToLowerCase([ts + uid + method + lsId +serverID + serverKey])
Then use sha1 to hash the hashText.
n order for LMS to provide correct timestamp when making a call to LoginRequest it can use this servlet to acquire current LAMS server time.
It can be achieved by making a request to the GetServerTime servlet on the LAMS side. For example:
http://localhost/lams/services/getServerTime
Servlet will return the number of milliseconds since January 1, 1970, 00:00:00 GMT POSIX time. For example, 1417535668074 (which stand for Dec 02 11:24:28 VET 2014).
No parameters are expected.
You can use either http method POST or GET.
Why do I need to know the LAMS server time?
Good question, in LAMS 2.5+ we wanted to add another level of security in case a user attempts to hijack a LoginRequest URL. On LAMS 2.5+ there are two new options when creating an integrated server:
Enforce time limitation for integration requests (checkbox) and
Time to live for integration requests (in minutes)
If you enforce a time limitation, then the LoginRequest have a set number (say 5 mins) for this LoginRequest URL "to live". After that time, the URL will be rejected.
So you use getServerTime to find out the POSIX time that the LAMS app is using and then you can calculate the delta with yours. So next time you send a LoginRequest, if you have the "Enforce time limitation" checked, then you send the ts with the LAMS server time.
You will need to get a List of existing learning designs so the LMS user can choose which ones they wish to start. You can get a list of learning designs by making a request to the LearningDesignRepository servlet on the LAMS side. For example:
http://localhost/lams/services/xml/LearningDesignRepository?
The parameters are:
To start, stop, schedule or clone a lesson in LAMS you need request another servlet:
http://localhost/lams/services/xml/LessonManager?
The parameters are:
username - the username of the current user
serverId - the server id
datetime - timestamp
hashValue - SHA1 hash of [timestamp + username + serverID + serverKey] (Note: all lower case)
courseId - the id of the course from the LMS (excluding removeLesson)
country - Country (must use 2 letter code as ISO 3166-1 alpha-2 code for country)
lang - Language code or locale code. In case of just passing language use "es" for Spanish or locale as "es_ES" (see list of available locales in LAMS)
method - "start", "stop", "schedule", "removeLesson"/"removeAllLessons" or "clone"
ldId - the id of the learning design (for start and schedule methods)
lsId - the id of the lesson (for stop, removeLesson, clone)
title - the title of the lesson (for start and schedule)
desc - the description of the lesson (for start and schedule)
learnerEnableExport - enables exporting portfolio by learners. Optional, default value: false (for start and schedule)
learnerSeeOnline - enables learner presence in the lesson. Optional, default value: false (for preview, start and schedule)
learnerInstantMessaging - enables learner instant messaging in the lesson. Optional, default value: false (for preview, start and schedule)
enableNotifications - enables "email notifications" link for the lesson. Optional, default value: false (for start and schedule)
allowLearnerRestart - whether learners are allowed to restart the lesson. Optional, default value: according LAMS ExtServer's default setting _(for start and schedule)
This servlet returns an xml response depending on the method ('start', 'schedule' or 'stop').
Start - An xml node called "Lesson" with an attribute "lessonId" which contains the lesson id.
Schedule - An xml node called "Lesson" with an attribute "lessonId" which contains the lesson id.
Stop - An xml node called "Lesson" with an attribute "deleted" which informs you whether the lesson was successfully deleted in LAMS
Clone - An xml node called "Lesson" with an attribute "lessonId" which contains the new lesson id.
You can use either http method POST or GET.
By default, the LoginRequest servlet will add students/monitors to an existing lesson automatically. But in some cases you might want/need to pre-add the students/monitors to the lesson
For this, you can use the LessonManager servlet and make only one call passing all usernames for all the students and monitors:
http://localhost/lams/services/xml/LessonManager?
The parameters are:
username - the username of the current user
serverId - the server id
datetime - timestamp
hashValue - SHA1 hash of [timestamp + username + serverID + serverKey] (Note: all lower case)
courseId - the id of the course from the LMS
country - Country (must use 2 letter code as ISO 3166-1 alpha-2 code for country)
lang - Language code or locale code. In case of just passing language use "es" for Spanish or locale as "es_ES" (see list of available locales in LAMS)
lsId - the id of the lesson
method - "join"
learnerIds - a comma separated string with all the students' usernames (ie: johnd,ernieg,fei,sarah)
monitorIds - a comma separated string with all the monitors' usernames
You can use either http method POST or GET.
If the learners and monitors are to be created in LAMS, you must pass their user details following a few conventions:
firstNames, lastNames, emails - these are comma separated parameters;
if there is a need to create even only one user it is required to supply comma separated list of all users going to be joined to lesson (i.e.: if learnerIds=user1,user1). Then each of the new parameters should have 2 values, like firstNames=name1,name2.
in case if you want to join monitors as well during one call - learner's parameters should go first, before monitor's ones
if any of these 3 parameters(firstNames, lastNames, emails) is provided it is expected that all of them have the same number of comma separated elements
LAMS will not create the users if the number of usernames, firstnames and lastnames is not the same.
While you can use GET to post this,
Removes user(s) completely from a lesson regardless of his/her role with it.
Call LessonManager servlet: http://localhost/lams/services/xml/LessonManager?
The parameters are:
username - the username of the current user
serverId - the server id
datetime - timestamp
hashValue - SHA1 hash of [timestamp + username + serverID + serverKey] (Note: all lower case)
lsId - the id of the lesson
method - "removeUser" or "removeAllUsers"
userIds - a comma separated string with all the users' usernames (ie: johnd,ernieg,fei,sarah) (for removeUser only)
In LAMS version 2.3.5+ (that's the latest on the lams2_3_release branch), you are able to get a learning design image (the learning design activity drawing) from an integration.
http://localhost/lams/services/LearningDesignSVG? The parameters are:
serverId - the server id
datetime - timestamp
hashValue - SHA1 hash of [timestamp + username + serverID + serverKey] (Note: all lower case)
username - the username of the current user
ldId - the id of the learning design (for starting or scheduling)
svgFormat - image format (svgFormat can be either 1 for SVG or 2 for PNG)
The response is the image content (bytes), so you can set it as "src" attribute of a <img> tag.
You need to use http method GET.
To get a user progress for a lesson, you must also request the LessonManagerServlet. You can either get a specific progress for a user, or a list of progresses for an entire lesson.
The parameters are:
username - the username of the current user
serverId - the server id
datetime - timestamp
hash - SHA1 hash of [timestamp + username + serverID + serverKey] (Note: all lower case)
method - singleStudentProgress or studentProgress for the list of progresses
lsId - the lesson id
courseId - the course id
There are 3 additional parameters for single user progress (method=singleStudentProgress)
firstName - first name of the user who's progress you wish to retrieve
lastName - last name of the user who's progress you wish to retrieve
email - email of the user who's progress you wish to retrieve
You can use either http method POST or GET.
You will receive an xml response in the following form:
To get a list of lesson for which the given user has Monitor role you must request LessonManagerServlet.
The parameters are:
username - the username of the current user
serverId - the server id
datetime - timestamp
hash - SHA1 hash of [timestamp + username + serverID + serverKey] (Note: all lower case)
method - use "listMonitor"
courseId - the course id
You will receive an xml response in the following form:
At times you might want to get the marks that the student(s) got in a LAMS activity -for instance the mark of a multiple choice.
For that you need to change the methods as follows:
method=toolOutputsAllUsers: This one gets all outputs for all activities and for all users, see toolOutputsAllUsers.xml
method=authoredToolOutputsAllUsers: This one gets the requested outputs (which were pre-defined in author in the learning design) for each activity and prints them out for each user. See authoredToolOutputsAllUsers.xml
method=toolOutputsUser: This one gets all the outputs for an activity, but only for the specified user, see toolOutputsUser.xml
method=authoredToolOutputsUser: This one gets the requested outputs (which were pre-defined in author in the learning design)for each activity, but just for the specified user, see authoredToolOutputsUser.xml
You can use either http method POST or GET.
Calling: http://<lams-server>:8080/lams//services/xml/LessonManager?&serverId=xxx&courseId=xxx&username=test1&datetime=xxx&hashValue=xxx&lang=en&country=AU&method=toolOutputsAllUsers&lsId=1
you get: toolOutputsAllUsers.xml
Calling: http://<your-lams>:8080/lams//services/xml/LessonManager?&serverId=xxx&courseId=xxx&username=test1&datetime=xxx&hashValue=xxx&lang=en&country=AU&method=authoredToolOutputsAllUsers&lsId=1 You get: authoredToolOutputsAllUsers.xml
You can use either http method POST or GET.
Calling: http://<your-lams>:8080/lams//services/xml/LessonManager?&serverId=xxx&courseId=xxx&username=test1&datetime=xxx&hashValue=xxx&lang=en&country=AU&method=toolOutputsUser&lsId=1&outputsUser=testXYZ
You get: toolOutputsUser.xml
Calling: http://<your-lams>:8080/lams//services/xml/LessonManager?&serverId=xxx&courseId=xxx&username=test1&datetime=xxx&hashValue=xxx&lang=en&country=AU&method=authoredToolOutputsUser&lsId=1&outputsUser=testXYZ
You get: authoredToolOutputsUser.xml
To get Gradebook for a particular lesson or a whole course you need to send a request Gradebook servlet:
http://localhost/lams/services/Gradebook?
The parameters are:
uid - the username of the current user
method - either author, monitor or learner; see description below
ts - timestamp
sid - the server id
hash - SHA1 hash of [ts + uid + method + serverID + serverKey] (Note: all lower case)
country - Country (must use 2 letter code as ISO 3166-1 alpha-2 code for country)
lang - Language code or locale code. In case of just passing language use "es" for Spanish or locale as "es_ES" (see list of available locales in LAMS)
courseid - the id of the course from the LMS
lsid - the id of the lesson
courseName - the LMS's course name
You can use either http method POST or GET.
Gradebook content can be obtained two ways:
if the user is already logged in, a direct call to Gradebook servlet will return the desired content; "method" parameter is still required for hash, but has no meaning in processing
Gradebook content can be also delivered by calling LoginRequest servlet, which will log the user in first; in this case the request to LoginRequest servlet needs to have "method" and "courseid" parameters set (same as in a plain call to this servlet), plus "mode" parameter set to "gradebook"
If ID of an external course is provided (it must be in case of calling LoginRequest, but it is not required when calling Gradebook servlet directly), it is translated into internal LAMS organisation ID and user is redirected to Gradebook for this course. If lsId is provided, it has higher priority than courseid and user is redirected to Gradebook for this particular lesson.
It's possible to get either a lesson total mark for one specified user, or lesson total marks for all users in a lesson, or lesson total marks for all users in all lessons in a course.
To get total user marks from LAMS you need to make a call to the following servlet: http://localhost/lams/services/xml/LessonManager? The parameters are:
username - the username of the current user
serverId - the server id
datetime - timestamp
hashValue - SHA1 hash of [timestamp + username + serverID + serverKey] (Note: all lower case)
method - gradebookMarksUser for lesson total mark for a specified user or gradebookMarksLesson for all users in a lesson or gradebookMarksCourse - for all users for all lessons in a course
lsId - the lesson id (only for method=gradebookMarksUser and method=gradebookMarksLesson)
courseId - the course id (only for method=gradebookMarksCourse)
outputsUser - the username of the user who's progress you wish to retrieve (only for method=gradebookMarksUser)
You will receive an xml response in the following format:
For single user total mark:
In case of method=gradebookMarksLesson there will be multiple <Learner> elements. And in case of method=gradebookMarksCourse there will be multiple <Lesson> elements.
Use the locale_id according to the language and country you want to choose for a user:
locale_id
language_iso_code
country_iso_code
language name
locale_id
language_iso_code
country_iso_code
language name
1
en
AU
English (Australia)
2
es
ES
Espanol
3
mi
NZ
Maori
4
de
DE
Deutsch
5
zh
CN
Chinese (China)
6
fr
FR
French (France)
7
it
IT
Italiano
8
no
NO
Norsk
9
sv
SE
Svenska
10
ko
KR
Korean
11
pl
PL
Polski
12
pt
BR
Portugues (Brasil)
13
hu
HU
Magyar
14
bg
BG
Bulgarian
15
cy
GB
Cymraeg (Cymru)
16
th
TH
Thai
17
el
GR
Greek
18
nl
BE
Nederlands (Belgium)
19
ar
JO
Arabic (Jordan)
20
da
DK
Dansk
21
ru
RU
Russian
22
vi
VN
Vietnamese
23
zh
TW
Chinese (Taiwan)
24
ja
JP
Japanese
25
ms
MY
Malay (Malaysia)
26
tr
TR
Turkish
27
ca
ES
Catalan
Check out Integration example to get a quick overview on how you can integration your LMS to LAMS.
This is a manual integration example that would hopefully help you to create an integration with LAMS quickly.
First, I created an integration server in LAMS (login as sysadmin and then go to the syadmin menu) with these settings:
Obviously, change the URLS according to yours.
Creates a user, the course, adds the user as author into it and then redirects the user directly to the Author UI
Prepare hash: [ts + uid + method + serverID + serverKey] sha1(1roger01authorlmslms) = 2694cbe4a627b9798824453e65d0f13f8dc1f5e3
Result: open LAMS author, create a sequence called "Some sequence" and saved
Prepare hash: [timestamp + username + serverID + serverKey]
sha1(1roger01lmslms) = a8c722c31ac21e719145d15febf6df246ea16d16
URL:
Result:
Shows me all the lessons available for Roger to create lessons. You can see "Some sequence" within Roger Moore's personal folder.
Prepare hash: [timestamp + username + serverID + serverKey]
sha1(1roger01lmslms) = a8c722c31ac21e719145d15febf6df246ea16d16
URL:
Returns:
The lessonId ready to be used
Prepare hash:
sha1(1roger01monitorlmslms) = 81079e7430329662ba19050e6d5d80395a7fab53
URL:
Result:
Opens Monitor UI for that lesson
Roger goes into the lesson as learner. Note that learnerStrictAuth is only available for LAMS 2.5+
Prepare hash: [ts + uid + method + lsId +serverID + serverKey]
sha1(1roger01learnerstrictauth1537lmslms) = 109cf9886c6fcb926a29a6d10d217de7c524016d
URL:
Result:
Open Learner UI
This will create the user, added to the course and also the lesson as leaner. Note that this method works with 2.4 and 2.5+
Prepare hash: [ts + uid + method +serverID + serverKey]
sha1(1daniel007learnerlmslms) = c86882105c7db67e438be44919e6113fa17b4596
URL:
Result:
Open Learner UI, creates the user, adds it to the course and lesson just as leaner.
Prepare hash:
sha1(1sean007monitor1537lmslms) = bbbf4b5f8b63291ee10c32d7e9181024d2326fa7
URL:
Result:
Opens Monitor UI. You can see on the sequence tab that there's two students (Roger and Daniel)
I think by now you pretty much get the idea how the integration works and how to get all the other API calls to work.
Country (must use 2 letter code as for country)
Language code or locale code. In case of just passing language use "es" for Spanish or locale as "es_ES" (see in LAMS)
This is the same as starting a lesson. The only thing that changes here is that the title and the method is to be set to preview. Once you get the lessonId, just compose the LoginRequest as usual with mode = preview. That's all
