Before you start on the Tool Contract, make sure you familiarise yourself with LAMS through reading the Overview and new Architecture.

The LAMS Tool Contract is basically a set of expected behaviours, registered URLs and API calls that a LAMS Tool has to implement to "talk" to LAMS Core.

A tool which interacts with the LAMS core via URL calls and direct Java calls. It implements interfaces defined in the LAMS core, and makes use of known LAMS services supplied by the core. Tools need to be written using the Spring framework to allow the LAMS core to be able to communicate with the tool.

Each tool interacts with the following four core modules.




Calls the tool to create/update or delete tool content. Uses the tool's authoring screens.


Uses the tool's monitoring screens.


Uses the tool's administration screen, which may be used to configure the tool


Calls the tool to duplicate tool content and set up tool sessions. Uses the tool's learner and export portfolio screens.

Tool Overview

Tool Meta Data

A tool will supply some basic meta data. This is required for both the running of the tool within LAMS and for the export of learning designs.

  1. Tool Vendor details: Required for the export
  2. Tool Full name and details: Required for the export, possibly for upgrading scripts.
  3. Tool Signature: Required for jar, war and table name uniqueness.
  4. Tool Content Compatibility: Required for the export and for upgrading scripts.
  5. Tool Licensing: Licensing details for this tool.
  6. Tool Version: Code and database version in the format YYYYMMDD.

Tool Content

While tool's manage their own content, the LAMS core and the tools work together to create and use the content. The tool content id (toolContentID) is the key by which the tool and the LAMS core discuss data - it is generated by the LAMS core and supplied to the tool whenever content needs to be stored. The LAMS core will refer to the tool content id whenever the content needs to be used.

Tool content will be covered in more detail in following sections.

Each tool will have one piece of content that is the default content. The tool content id for this content is created as part of the installation process. Whenever a tool is asked for some tool content that does not exist, it should supply the default tool content. This will allow the system to render the normal screen, albeit with useless information, rather than crashing.

Tool Session

A tool session is the concept by which which the tool and the LAMS core manage a set of learners interacting with the tool. The tool session id (toolSessionID) is generated by the LAMS core and given to the tool.

A tool session represents the use of a tool for a particulate activity for a group of learners. So if an activity is ungrouped, then one tool session exist for for a tool activity in a learning design.

More details on the tool session id are covered under monitoring.

When thinking about the tool content id and the tool session id, it might be helpful to think about the tool content id relating to the definition of an activity, whereas the tool session id relates to the runtime participation in the activity.

Grouped and Non-Grouped Tools

A tool may support grouping in a number of different ways:

  1. NONE

This bit to be done - at present, tools are all OPTIONAL. NONE isn't supported.

Tool Activity and Library

A learning design is made up of activities. Some activities are tool activities, that is they are an activity that relates to just one tool.

A tool must supply the details of the tool activity to be store in the lams_learning_activity table. This is the "prototype" activity that is created when the tool is selected in authoring. This activity forms part of the tool library, which is presented to the user in the authoring module.

The set up of the tool activity is done via a script at tool installation time. See Tool Installation below.

Tool User Interface

The tools developed by the core LAMS team use JSPs. Tool writers may use other technologies (e.g. Flash) if they wish. Tool must meet the functional requirements specified in this tool contract. The user interface will need to support the selected browsers.

If you want your tool to become part of the main LAMS build, it will need to support the standard LAMS "look and feel", including the LAMS skins.

All tool screens must be able to run two copies at the same time. For example, your tool may be running in both Preview and Learner at the same. Some tools use the reuse part of their authoring screen for monitoring and again, these could both be open at the same time. It is crucial that you do not just put your data into Session variables in the "normal" manner of JSP programming as these will clash when the same screen runs twice at the same time for a single user. Use either the Request or our shared session map.

Differences between Tools in LAMS 2.0 and Tools in LAMS 1.0.1

In LAMS 1.0.1, the tools were much more tightly integrated with the core. While there was a "tool interface" for the call to trigger the tool to run, pass it information, etc., the authoring and monitoring was managed by the core. Only the learner interaction part was really managed by the tool. So creating a new tool required changes to the core code and a Flash user interface change.

In LAMS 2.0, a tool is responsible for part of authoring, monitoring as well as the learner interaction. Creating a new tool should not require any core code changes or Flash changes. This is what we mean by a tool being "pluggable".

Tool Structure

A Tool in 2.0 consists of 3 required elements:

(1) A JDK 1.5 (Java 5) compliant jar file which includes the Tool's implementation of it's required API elements which is copied to the LAMS EAR (so LAMS can access it).

In order to avoid name collisions between this Tool and LAMS (and any other deployed tools) the jar file should be called tool-<tool signature>.jar. Additionally tool creators should ensure that there are no name collisions between classes by using the Java standards for package and class naming.

(2) A J2EE Compliant Web Application which is deployed into the LAMS EAR as component web application. In order to avoid name collisions between this Tool and LAMS (and any other deployed tools) the jar file should be called tool-<tool signature>.war.

This web application will need to declare a dependency to its own jar file, the lams.jar and lams_learning. It may declare dependencies to other jars in amongst the common jar files. If your tool requires jar files that are not in the common jar files, then include them in the lib area of your web application.

LAMS CANNOT guarantee that this does not cause problems with other deployed Tools!

Please do not include copies of the common jar files in your webapp. Please use the common jar files. This may give you a problem in the future if we upgrade the common jar files but sharing jar files will give us less problems with classloaders, etc.

(3) Database Data including tool record, library, and activity data.

Tools may also have:

  1. Database tables, which should use the LAMS database with tool_<sig>_ naming convention, and code should use the tool-ds DataSource.

Tool Behaviour

API elements

Tool Deployment Tool will be deployed using the tool deployment utility . This includes installing the jar and war files and updating the database with the tool's details, such as the authoring URL.

Tool path The URL path for the tool should be <lamsroot>/tool/$TOOL_SIG.

Package Name

Your tool package name should be: <organisation path>.lams.tool.<toolname>.

For example: org.lamsfoundation.lams.tool.survey

Service Bean and Java Interfaces

In your tool package, you should create a package "service", and in this package include a a single Spring defined service bean. The name of this bean is one of the initial configuration details.

This service bean must implement the two interfaces org.lamsfoundation.lams.tool.ToolContentManager and org.lamsfoundation.lams.tool.ToolSessionManager.

We suggest that you also create an interface for your own service bean methods and use a proxy decouple your user interface code (e.g. Struts Actions) from your service bean.


The tool needs to supply a tool icon. The path to the icon is defined in the lams_learning_activity table (library_activity_ui_image column).

Authoring URL

The tool must supply an authoring module, which will be called to create new content or edit existing content. It will be called by an authoring URL using the following format:

The initial data displayed on the authoring screen for a new tool content id may be the default tool content.

Authoring UI data consists of general Activity data fields and the Tool specific data fields.

The authoring interface will have three tabs. The mandatory (and suggested) fields are given. Each tool will have its own fields which it will add on any of the three tabs, as appropriate to the tabs' function.

Basic: Displays the basic set of fields that are needed for the tool, and it could be expected that a new LAMS user would use. Mandatory fields: Title, Instructions.
Advanced: Displays the extra fields that would be used by experienced LAMS users. Optional fields: Lock On Finish, Make Responses Anonymous
Instructions: Displays the "instructions" fields for teachers. Mandatory fields: Online instructions, Offline instructions, Document upload. See Instructions.

The standard LAMS tools will use a DHTML layout for the Authoring tabs. For consistency of look and feel, we prefer all tools to use the DHTML, or at least make the tabs look and behave like the DHTML layout. The javascript for the tabs is available as "/include/javascript/tabcontroller.js" from the central web app (e.g.

The "Define Later" and "Run Offline" options are set on the Flash authoring part, and not on the tool's authoring screens.

Preview The tool must be able to show the specified content as if it was running in a lesson. During preview the author steps through the design as if they were a student, so the preview mode must have the normal Finished button and handle "Run Offline". The core will take care of "Define Later".

Normally tools act exactly the same as they do for normal learner. The exception to this is tools that require interaction between users or would take a long time (e.g. a week) to complete. For example, if we had a tool that needed two people to do something before either of them could finish, then that would have to work differently in preview as there is only one person in preview.

The preview URL has a separate entry in the tool table to the learner screen, but the core LAMS tools implement it by using the normal learner URL with a "mode" parameter set to ToolAccessMode.AUTHOR. The mode is added as a parameter in the preview URL entry in the database.

Export The tool must be able to export its tool content for part of the overall learning design export.

The format of the serialization for export is XML. Tool will define extra namespace inside the <Content> element to add a new data element (type). Inside the data element, it can further define more structures and types as it seems fit.

The data elements must be "version" aware. The data elements must be "type" aware if they are to be shared between Tools.

Help URL

The tool should supply help information page(s) which will enable the user to find useful information. It will be called by a help URL that can be your own custom URL or a LAMS wiki URL in the format:

A anchor is appended to the help URL for language (locale) purposes. The anchor is in the following format:

note: <locale> is in the form xxYY instead of xx_YY (no underscore) e.g. enAU

Help URL Example: Noticeboard Tool

The entry in the database field is the page that will be displayed to the user is at (with en_AU as their locale).

LAMS Xpress (Ernie, could you put something in here. You explain it better than I do!)

Data Exchange At present, there is no data exchange format between tools. Therefore if a tool needs to work with another tool, they will need to be combined in a new tool. We plan to have a data exchange method in a future version of LAMS.


The overall monitoring screen is implemented in Flash. The flash interface makes three calls to the tool:

Learner Progress URL

The learner progress allows the teacher to monitor the contribution of a particular student. The userID is the userID of the learner, not the userID of the teacher. This screen is read only - the monitoring user should see what the learners sees but not be able to change anything on the screen. It should not have a finished button.

The learner progress URL has a separate entry in the tool table to the learner screen, but the core LAMS tools implement it by using the normal learner URL with a "mode" parameter set to ToolAccessMode.TEACHER. The mode is added as a parameter in the learner progress URL entry in the database.

Monitor URL

The screen given by the Monitor URL is the main monitoring screen for the tool. As with the authoring screen, there are a series of tabs which allow the user to select from various functions.

The input to the monitoring screen will be the tool content id.

The Monitoring screen will have the following tabs:

Summary displays a summary of all the learner's responses grouped by toolSessionID and allows learner entries to be modified.

When the summary tab is displayed, the tool should find all the toolSessionIDs relating to the supplied toolContentID. If no learners have started the activity, then no toolSessionIDs will relate to the toolContentID. If the activity is not grouped, then the toolContentID will relate to one toolSessionID. If the activity is grouped, then the toolContentID will relate to one or more toolSessionIDs (depending on which groups have actually started the activity).

If no matching toolSessionIDs are found then no entries should be displayed.

If one matching toolSessionID is found then all the entries for that toolSessionID can be displayed together. The teacher should be able to "manage" the entries. For example, in the question and answer tool, each learner's answer is listed and the teacher must be able to edit the learner's answers and hide particular answers. In the chat tool, the teacher should be able to edit or hide individual comments made by learners. When a teacher edits, hides or shows a hidden answer or comment, then this must be logged in the Audit Log.

If more than one toolSessionID is found then all the entries should listed, grouped by their toolSessionID. On the right hand side of the screen there should be a list of toolSessionIDs. The teacher should be able to select one or more toolSessionIDs and then refresh the screen. This will allow a teacher to only view some of the groups. Note: A list of toolSessionIDs won't be a lot of help - we need to add some description that should be shown to the teacher. This is a "to do" - for the moment do tool session ids.

See the attached file monitor_summary.jpg for an example.

Instructions displays the online and offline instructions, entered during authoring. The instructions should be displayed for viewing only - they should not be editable. See the attached file monitor_instructions.jpg for an example. See Instructions for more details.

Edit Activity allows staff to set the tool content. Initially it should display the tool content as read only and have a button to click to go into editing mode. Once in editing mode, it should look and act the same as the authoring screen. You may wish to reuse your authoring URL.

See the attached file monitor_editactivity.jpg for an example.

The standard LAMS tools will use a layout which looks like the Authoring tabs. For consistency of look and feel, we prefer all tools to use same look and feel. We are not necessarily using DHTML (although you may if you want) for monitoring as the amount of data on the tabs is different to authoring. For example, if the calculation of the statistics is very intensive, then we don't want to calculate them until the user actually asks for them (by clicking on the statistics tab).

See the section "Define Later and Modifying Tool Content" below for more details.

Statistics displays the statistics for a tool e.g. the number of users completed, the percentage of correct answers. If more than one toolSessionID then the statistics should be displayed for each toolSessionID and then an overall set for all toolSessionIDs at the end. See the attached file monitor_statistics.jpg for an example.

Tools may include other tabs if it wishes to display something that does not fit on one of the standard four tabs.

Editing Students Contributions from Monitor. In some cases, a teacher/monitor might need to Edit the content of a student posting for whatever reason. If such edition takes place, we should make sure that event is properly logged. Although we don't need versioning, we need to make sure that the student entry gets logged when the teacher's change it. In the case of Forum, for instance, if the teacher edits the content of a student posting, then this event should be logged including the original student posting text.

Need to look into having a shared message area in lams_central, or a resource file in lams_common, for this like the "no values available" messages - so they are consistent across tools.

Export Portfolio URL

This screen allows the user to export in plain HTML the contribution of one or all participating students for the supplied toolSessionIDs. The concept is to record what the learners' have seen on their screens. The portfolio may be for an individual learner, or may be for the whole class.

For example, in Q&A the portfolio export is basically the summary report that in presented in Monitor. That is, an HTML file with the Questions and all the Answers for all the users.

If the export is being done by a teacher then the mode parameter will be set to teacher and the toolContentID will be supplied. This version should display the learner responses for all the groups.

If the export is being done by a learner then the mode parameter will be set to learner, and the toolSessionID will be supplied. This version should ONLY display the responses for their group (that is, the responses for the supplied toolSessionID) and not all the groups as it happens with the teacher's export.

Define Later and Modifying Tool Content

Tool content can be modified until the first learner starts using the tool. The modification of tool content is controlled by three flags DefineLater in the sequence definition, DefineLater in the tool and the tool's own ContentInUse flag. (The tool doesn't need to call the flags DefineLater and ContentInUse - it could call them Flag1 and Flag2. But it needs to have the two flags and we suggest using these names.)

The sequence value of DefineLater is set using the activity inspector in authoring.

When the lesson is started, each tool is asked to copy its content. If the DefineLater flag is turned on in the sequence, then the DefineLater flag in the tool is set by calling the setAsDefineLater() method on the tool. The ContentInUse flag should start as false.

While the lesson is in progress the tool content can be in a number of states:

Tool's DefineLater flag set to true: Staff may edit the tool content (using the Edit Activity tab in the Monitoring screen). If a learner reaches the tool with DefineLater set to true, the learner should see a "Please wait for the teacher to define this part...." style message. In this case, ContentInUse flag should still be false - if it is not then there is a bug.

Tool's DefineLater flag set to false, ContentInUse flag set to false: Staff may edit the tool content. When the staff member brings up the Edit Activity tab and clicks the "Edit" button, the DefineLater flag should be set to true, so that learners cannot start using the content while the staff member is editing it. When the staff member finishes editing the content, the DefineLater flag should be set back to false. (Note: the DefineLater flag is only changed when the "Edit" button is clicked. This allows the staff member to select the Edit Activity tab, look at the contents and then decide "no, I don't need to change this after all" without the DefineLater being affected.

If the teacher closes the window without finishing editing, the DefineLater flag will stay set to true. The teacher will need to go back to the Edit Activity screen and save it (with or without making changes) to set the flag to false.

If a learner reaches the tool with DefineLater set to false, the learner should see the normal learner screen. The first time a learner views the content, the tool's ContentInUse flag should be set to true.

ContentInUse flag set to true: The staff can no longer edit the tool content. The tool's DefineLater flag should be false - if it is not then there is a bug.

The content can be modified two ways - either via the Edit button in the Monitoring tabs or by a direct call to the Define Later URL (as given in the tool table in the database). To make it easier for the user, the Edit screen, the Define Later direct call and Authoring should all look as similar as possible, except that the Edit/Define Later options should only show the values from the "basic" tab - Edit/Define Later should not allow the staff to modify the online/offline instructions or the advanced options.

The LAMS standard tools will usually do this by reusing the same authoring screen for all three possibilities, with only the basic tab showing for Edit/Define Later. When the Define Later URL is called, the authoring tabs will appear in a specified frame. When the user clicks on the Edit button then it will pop up a new window containing the authoring tabs.

If reusing the authoring URL is not suitable then the editing mode may be done by changing the read only display to editable fields rather than popping up a new window. However if you do this, you must still ensure that the look and feel of the editing mode is the same as authoring.

Note: When the tool content is modified via monitoring, it is not the content created during authoring that is modified. It is the copied content (created when the lesson started) that is modified.


Learner URL

It is the responsibility of the tool to record the progress of the user. If the tool is a multistage tool, for example asking a series of questions, the tool must keep track of what the learner has already done. If the user logs out and comes back to the tool later, then the tool should resume from where the learner stopped.

When the user is completed with tool, then the tool notifies the progress engine by calling org.lamsfoundation.lams.learning.service.completeToolSession(Long toolSessionID, User learner).

If the tool's content DefineLater flag is set to true, then the learner should see a "Please wait for the teacher to define this part...." style message.

If the tool's content RunOffline flag is set to true, then the learner should see a "This activity is not being done on the computer. Please see your instructor for details."

Core LAMS tools have a "mode" parameter set to ToolAccessMode.LEARNER. This allows the URL to be reused for learner progress and preview. The mode is added as a parameter in the learner URL entry in the database.

If the tool has a LockOnFinish flag, then the tool should lock learner's entries once they have completed the activity. If they return to the activity (e.g. via the progress bar) then the entries should be read only.

Export Portfolio URL

This screen allows the learner to export in plain HTML the contributions of the learners in this learner's group(s). See Export Portfolio under Monitoring for details.


Administration URL All tools define some basic meta data on installation. Tools must also supply a URL which may be used for updating this information, along with any tool specific configuration details e.g. the chat port number.

The administration URL should also allow access any administrative tasks e.g. reviewing a tool log, runtime stop/start of the chat server, or a monitor method which shows which Chat rooms are active.

There is no support for exporting a complete tool. If you wish to share a tool that you have been given by someone else (after checking that you have this privilege under the tool's license), you will need to pass on the original tool installation package and export any designs that you have made with this tool separately.

Screen sizes

LAMS 2.0. is designed to run on 800x600 monitor. Therefore tools should have screens that fit into the following sizes:

Authoring window (which will be a pop-up window): 800 x 600
Monitoring window (will be part of an overall frameset): ??? x 600
Learning window (will be part of an overall frameset): ??? x 600

Tools should be designed so that the screen scales. That it, if the user has a larger screen and makes the window larger, the tool should make use of the extra space.


All MySQL tables should use InnoDB tables, as InnoDB tables support transactions.

The LAMS database uses UTF-8 as the default character set. Tools must support UTF-8 characters.

Database access is to be done using Hibernate, through Spring.

Transactions should be defined declaratively using Spring, rather than hard coding transactions.

All the Spring defined beans must have a name that is unique to your tool, as the Spring context for your tool will be loaded into a combined context. If the bean names (including any DAO classes, Hibernate definitions, etc) that are not unique may overlap with another tool and cause either your tool or another tool to fail. We suggest that all your beans are defined as <mmtttt><beanname> where <mmtttt> comes from your tool signature. For example, say you have a quiz tool with the tool signature xxquiz10. Your service bean's class could be MyServiceBean but the bean name in the Spring context should be xxquizMyServiceBean to ensure uniqueness in the context. Note: this has not been done for the core LAMS tools written to date, but it will be done for them in the future. We made the necessary bean names unique without really thinking about it when we wrote the core tools and hence didn't forsee the need for this naming convention!

All java package names should be unique. If you are using your own organisation's package name e.g. org.somegroup.lams.tool.blah then it won't be a problem but if you use org.lamsfoundation package names then you need to think about making your package name unique.

The LAMS stylesheets and other icons in the lams_central war are to be used to maintain the LAMS look and feel. If we change the stylesheet, we want the change to be reflected across all tools.

Struts is preferred as the user interface framework. If you use something else, your tool may or may not be able to certified - we will look at this on a case by case basis.

Tool Compliance and Certification

LAMS 2.0 has been designed so that tools can be developed by anyone in the LAMS community and distributed between LAMS users.

To make it easier for LAMS users to decide what tools to use, we will develop levels of "compliance" with this tool contract and a system for certifying tools. The method for certifying tools will be developed in the future.

The intention is that a fully certified tool (which may or may not be included in the main LAMS distribution), a tool will need to meet the FULL compliance level, will need to have the same look and feel as the main LAMS tools, will need to use the LAMS skins (or have suitable replacements) and will need to be shown to be "well-behaved" e.g. install properly, not chew up CPU, not conflict with the main LAMS tools, etc.

If you use libraries that are not part of the LAMS common libraries, we will consider issues such as licensing (must be GPL okay), maintenance (are you the only person that knows that library/framework and can do bug fixes?), does it affect the look and feel too much, will the framework co-exist happily with Struts, will we have class loader problems?


API+ Authoring (except define later, run offline), Learning (except portfolio export). Used for testing only.


TEST + Monitoring (except define later, run offline).


MINIMAL + define later, run offline, portfolio export.

LAMS Tool Deployment

Tools should be deployed using the tool deployment utility. The utility reads a series of sql and property files, inserts the sql data in the database, copies the jar and war files to the LAMS Ear and updates the application.xml (in the LAMS Ear).

Tool upgrades are not currently supported by the utility so upgraders must be written manually by tool authors.


At present, a tool is used at a specific point in a sequence. In the future, some tools may be available throughout the sequence e.g. chat room.