Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

LAMS Integrations

Table of Contents

Introduction

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.

...

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.

...

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 seperated 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> 

...

Request for author, learner and monitor are directed through the LoginRequest servlet.  For example:

http://localhost/lams/LoginRequest?....

The parameters are:

Parameter

Description

Restrictions/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)

email

Used if a new user is created

Correctly validated email address required

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)

 

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.

 

...

Note
titleImportant!


Use the learnerStrictAuth method when launching students into lessons

(only available for LAMS 2.5+)

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.

...

Info
titleNote!


This feature is only available for LAMS 2.5+

In order for LMS to provide correct timestamp when making a call to LoginRequest it can use this servlet to acquire current 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:

Parameter

Description

username

The username of the current user. Must be unique

datetime

timestamp

serverId

the server id

hashValue

SHA1 hash of [timestamp + username + serverID + serverKey]  (Note: all lower case before hashing)

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)

mode

"1" returns all learning designs being monitored by the current user, "2" returns all learning designs authored by the user

firstName

used if a new user is created

lastName

used if a new user is created

email

used if a new user is created

...

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)

...

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

...

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)

...

For single user progress:

No Format
Code Block
themeEclipse
languagehtml/xml
linenumberstrue
<LearnerProgress
    lessonComplete="true"
    activityCount="4"
    activitiesCompleted="4"
    attemptedActivities="4"
    studentId="304"
    courseId="MATH101"
    username="testUser"
    lessonId="13"
>
</LearnerProgress>

For multiple user progresses:

No Format
Code Block
themeEclipse
languagehtml/xml
linenumberstrue
<LessonProgress>

<LearnerProgress
    lessonComplete="true"
    activityCount="4"
    activitiesCompleted="4"
    attemptedActivities="4"
    studentId="304"
    courseId="MATH101"
    username="testUser"
    lessonId="13"
>
</LearnerProgress>

<LearnerProgress
    lessonComplete="false"
    activityCount="4"
    activitiesCompleted="2"
    attemptedActivities="3"
    studentId="114"
    courseId="MATH101"
    username="stephenh"
    lessonId="13"
>
</LearnerProgress>

 
</LessonProgress>

...

You will receive an xml response in the following form:

No Format
Code Block
themeEclipse
languagehtml/xml
linenumberstrue
<Lessons>
  <Lesson lessonId="5" name="myLesson1"       description="math lesson" state="3" />
  <Lesson lessonId="8" name="someOtherLesson" description="eng lesson"  state="5" />
</Lessons>

...

toolOutputsAllUsers.xml

Code Block
xmlthemeEclipse
languagehtml/xml
linenumberstrue
<?xml version="1.0" encoding="UTF-8"?> 
<ToolOutputs lessonId="1" name="mc"> 
<LearnerOutput completedLesson="false" firstName="Mary" lamsUserId="4" lamsUserName="mmm" lastName="Morgan" userName="mmm"> 
<Activity activityId="6" attempted="true" completed="true" title="MC1"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="true" type="boolean" /> 
</Activity> 
<Activity activityId="5" attempted="true" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
<LearnerOutput completedLesson="false" firstName="Two" lamsUserId="6" lamsUserName="test2" lastName="Test" userName="test2"> 
<Activity activityId="6" attempted="true" completed="false" title="MC1" /> 
<Activity activityId="5" attempted="false" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
<LearnerOutput completedLesson="true" firstName="Four" lamsUserId="8" lamsUserName="test4" lastName="Test" userName="test4"> 
<Activity activityId="6" attempted="true" completed="true" title="MC1"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="false" type="boolean" /> 
</Activity> 
<Activity activityId="5" attempted="true" completed="true" title="MC2"> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
<Activity activityId="7" attempted="true" completed="true" title="MC3"> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
</LearnerOutput> 
<LearnerOutput firstName="Jacky" lamsUserId="3" lamsUserName="lamskh01" lastName="Fang" userName="lamskh01"> 
<Activity activityId="6" attempted="false" completed="false" title="MC1" /> 
<Activity activityId="5" attempted="false" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
<LearnerOutput completedLesson="true" firstName="One" lamsUserId="5" lamsUserName="test1" lastName="Test" userName="test1"> 
<Activity activityId="6" attempted="true" completed="true" title="MC1"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="true" type="boolean" /> 
</Activity> 
<Activity activityId="5" attempted="true" completed="true" title="MC2"> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
<Activity activityId="7" attempted="true" completed="true" title="MC3"> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
</LearnerOutput> 
<LearnerOutput firstName="Three" lamsUserId="7" lamsUserName="test3" lastName="Test" userName="test3"> 
<Activity activityId="6" attempted="false" completed="false" title="MC1" /> 
<Activity activityId="5" attempted="false" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
<LearnerOutput firstName="Testing" lamsUserId="2" lamsUserName="test" lastName="LDAP" userName="test"> 
<Activity activityId="6" attempted="false" completed="false" title="MC1" /> 
<Activity activityId="5" attempted="false" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
</ToolOutputs> 

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

Code Block
xmlthemeEclipse
languagehtml/xml
linenumberstrue
<?xml version="1.0" encoding="UTF-8"?> 
<ToolOutputs lessonId="1" name="mc"> 
<LearnerOutput completedLesson="false" firstName="Mary" lamsUserId="4" lamsUserName="mmm" lastName="Morgan" userName="mmm"> 
<Activity activityId="6" attempted="true" completed="true" title="MC1"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="true" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="1" type="long" /> 
</Activity> 
<Activity activityId="5" attempted="true" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
<LearnerOutput completedLesson="false" firstName="Two" lamsUserId="6" lamsUserName="test2" lastName="Test" userName="test2"> 
<Activity activityId="6" attempted="true" completed="false" title="MC1" /> 
<Activity activityId="5" attempted="false" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
<LearnerOutput completedLesson="true" firstName="Four" lamsUserId="8" lamsUserName="test4" lastName="Test" userName="test4"> 
<Activity activityId="6" attempted="true" completed="true" title="MC1"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="false" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
<Activity activityId="5" attempted="true" completed="true" title="MC2"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="false" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
<Activity activityId="7" attempted="true" completed="true" title="MC3"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="false" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
</LearnerOutput> 
<LearnerOutput firstName="Jacky" lamsUserId="3" lamsUserName="lamskh01" lastName="Fang" userName="lamskh01"> 
<Activity activityId="6" attempted="false" completed="false" title="MC1" /> 
<Activity activityId="5" attempted="false" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
<LearnerOutput completedLesson="true" firstName="One" lamsUserId="5" lamsUserName="test1" lastName="Test" userName="test1"> 
<Activity activityId="6" attempted="true" completed="true" title="MC1"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="true" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="1" type="long" /> 
</Activity> 
<Activity activityId="5" attempted="true" completed="true" title="MC2"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="false" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
<Activity activityId="7" attempted="true" completed="true" title="MC3"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="false" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
</LearnerOutput> 
<LearnerOutput firstName="Three" lamsUserId="7" lamsUserName="test3" lastName="Test" userName="test3"> 
<Activity activityId="6" attempted="false" completed="false" title="MC1" /> 
<Activity activityId="5" attempted="false" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
<LearnerOutput firstName="Testing" lamsUserId="2" lamsUserName="test" lastName="LDAP" userName="test"> 
<Activity activityId="6" attempted="false" completed="false" title="MC1" /> 
<Activity activityId="5" attempted="false" completed="false" title="MC2" /> 
<Activity activityId="7" attempted="false" completed="false" title="MC3" /> 
</LearnerOutput> 
</ToolOutputs>

...

You get:
toolOutputsUser.xml

Code Block
xmlthemeEclipse
languagehtml/xml
linenumberstrue
<?xml version="1.0" encoding="UTF-8"?> 
<ToolOutputs lessonId="1" name="mc"> 
<LearnerOutput completedLesson="true" firstName="One" lamsUserId="5" lamsUserName="test1" lastName="Test" userName="test1"> 
<Activity activityId="6" attempted="true" completed="true" title="MC1"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="true" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="1" type="long" /> 
</Activity> 
<Activity activityId="5" attempted="true" completed="true" title="MC2"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="false" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
<Activity activityId="7" attempted="true" completed="true" title="MC3"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="false" type="boolean" /> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
</LearnerOutput> 
</ToolOutputs>

...

You get:
authoredToolOutputsUser.xml

Code Block
xmlthemeEclipse
languagehtml/xml

<?xml version="1.0" encoding="UTF-8"?> 
<ToolOutputs lessonId="1" name="mc"> 
<LearnerOutput completedLesson="true" firstName="One" lamsUserId="5" lamsUserName="test1" lastName="Test" userName="test1"> 
<Activity activityId="6" attempted="true" completed="true" title="MC1"> 
<ToolOutput description="Are learner's answers all correct?" name="learner.all.correct" output="true" type="boolean" /> 
</Activity> 
<Activity activityId="5" attempted="true" completed="true" title="MC2"> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
<Activity activityId="7" attempted="true" completed="true" title="MC3"> 
<ToolOutput description="Learner's total mark" name="learner.mark" output="0" type="long" /> 
</Activity> 
</LearnerOutput> 
</ToolOutputs> 

...

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)

...

For single user total mark:

No Format
Code Block
themeEclipse
languagehtml/xml
linenumberstrue
<GradebookMarks>
    <Lesson
        lessonId="13"
        lessonName="Big lesson"
        lessonMaxPossibleMark="4"
    >
        <Learner
            extUsername="alex"
            userTotalMark="3"
        >
        </Learner>
    </Lesson>
</GradebookMarks>

...