Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »


Tool adapter tools follow the same tool contract as all the other native tools which come packaged with LAMS, with a few slight variations. As with these native tools, a tool adapter tool must have author, learner and monitor interfaces, as well managing user and collaborative content through several tool sessions. The main difference when it comes to tool-adapter tools is that the content is and business logic for the tool is all managed by the external LMS tool.

The tool adapter tool is (in simple terms) a gateway that points the user to the correct page and content on the external server based on their role and the content they ask for. For example when the teacher opens a tool adapter author page, they are merely redirected to the tool's authoring page on the external server and when the user is done, they click the finish button and the external LMS returns the user to LAMS having saved their content. Of-course it is not as simple as this statement may seem, but that covers the general idea of the tool adapter. In the later sections there are detailed explanations of how it all works and how to create your own tool adapter tools


Tool adapter tools need to have an external server mapping, because the external tool almost always needs to know user and course information before it will save any content, also there needs to be an authenticated session or the user will not see anything. So the sequence of events goes something like this:

  1. A user called "Bill" starts from external LMS "Moodle" logged in as a teacher
  2. User clicks on the LAMS "Open Author" link which is controlled by the integration.
  3. A request is made to LAMS to open author for a user, LAMS looks for a user called "Bill" from the list of "Moodle" users, if it cannot find one, it creates one on the fly.
  4. User is authenticated in LAMS as "moodle_Bill".
  5. User drags a moodle forum tool in LAMS author onto the authoring frame and opens the authoring page for the tool.
  6. User is redirected to the moodle forum tool author page which is located on the external "Moodle" server.
  7. User's session credentials are maintained on external Server.

Course/User Mapping - CustomCSV

One of the key differences betweens LAMS and other LMS systems is that learning designs and activities do no sit in the context of a course or a group. LAMS learning designs are completely independent, and are not applied to a group/course until they are used to start a lesson. In most other LMS systems this is not the case, to create an instance of an activity you must save it in a course, and also save it with a user who has permissions to do so for that course. The permissions for viewing/editing/monitoring are managed by the course that the activity is saved in.

So here in lies one of the main difficulties in developing a tool adapter tool, when the the user drags the tool adapter tool onto the canvas and clicks on it to open author, how will the external tool know which course it is supposed to be made for on the external LMS, or which external user? The LAMS tool by default does not know this sort of information. Somehow this information has to get from the original author call from the external LMS.

The way this problem has been resolved in LAMS is to create a new class of tool called the tool_adapter tool that expects an extra parameter called "customCSV". This parameter is a comma-seperated-value string that is created by the external LMS tool and passed to LAMS when the user clicks author, or another LAMS action. Since the requirements to create a new tool activity instance may vary between each tool adapter tool, and the external LMS requirements may also vary, the customCSV can contain whatever parameters are needed in order to make the tool adapter work in each situation. For example in .LRN to create a new Forum instance, you need to have a user ID, a course ID, and you need to know the course URL to get to the authoring page, so the form of the customCSV is (userId, courseId, courseUrl). Moodle on the other hand does not require a course URL, but to create a new Forum instance there you need both the user and course ID as well as a section ID so moodle knows where to display the activity on the main course page. So the customCSV was made in the form (userId, courseId, sectionId).

CustomCSV is used in alot of the extension points in the tool adapter so take note of it when reading the next sections.

Extension Points

There are a couple of key points where the LAMS server will have to talk to the external integrated server in order for the tool adapter to work. Many of the calls will be made to the tool adapter servlet which will handle the special functions required for LAMS tools that are not often directly implemented by other LMS tools. The tool adapter servlet should be in a freely accessible location on the external LMS server open to external calls,

For all the extension points to work for a tool_adapter tool, it is imperative that the tool's service implements the special org.lams.lamsfoundation.tool.ToolAdapterContentManager interface. This interface not only identifies to Java that this is a tool adapater type tool, but also implements special methods to pass the customCSV where it is required.


As was discussed earlier, in order for this tool adapter concept to work, we need to pass the authoring page the customCSV parameter so it can correctly create the activity instance on the external LMS. There are a few steps to follow before we can get to this point.

External LMS ID Mapping

One of the key concerns with a tool adapter tool is when to display it or allow it. We only really want to see the tool in the tool kit view in authoring when the authoring call originated from the external LMS, otherwise we wont have the required customCSV parameter and the tool will not perform correctly. So the way this has been implemented is to add an extra collumn to the lams_tool table called ext_lms_id. This property does two things: it identifies it as a tool_adapter type tool in flash, as well as mapping the tool directly to a integrated server id, so if the call does not appear from the integrated server (like for instance if the user goes directly to LAMS and opens author), the tool will not appear in the toolkit view. If the call does originate from the external LMS and the serverId in the authoring call matches the ext_lms_id stored in the tool's lams_tool table row, then the tool will be displayed. This allows for multiple integrations on one LAMS instance with tool_adapter tools mapping to separate integration instances.

To make this ext_lms_id configurable, the tool will need a admin page accessible through the sysadmin interfaces, you may need to add further configuration items to this page as your tool adapter requires including a external tool adapter servlet url which will be discussed later in this document.

Authoring Action

Once you have your ext_lms_id happening, you need to manage actually redirecting to the external tool's authoring page. When the user clicks on the activity to open author, a request is made to the tool's authoring action. If you have configured the ext_lms_id correctly, and you have passed the customCSV from the original author login request call, then the customCSV will be passed in the request to the authoring action. You can decode it here and then construct the authoring url based on the parameters. If the base authoring URL is static and unchanging (minus parameters) as with the moodle forum tool, then you may wish to store a server URL in the tool's admin page and hard-code the relative URL. If the author URL is dynamically changing as is the case with the .LRN Forum tool, you may need to include a author URL in the customCSV passed form the external server.

In your call to the external tool's authoring page, you will need to add a parameter that tells the external server the return or save-content url. That way when the user clicks save on the external tool, they can be returned to LAMS to save the tool. The external tool should add a extra parameter for the external content id, so it can be saved in the LAMS content instance and used for future references to this tool content. 

Excerpt from Moodle Forum Tool's Authoring Action:

String customCSV = WebUtil.readStrParam(request, "customCSV", true);

String splitCSV[] = customCSV.split(",");
if (splitCSV.length != 3)
	logger.error("mdlForum tool customCSV not in required (user,course,courseURL) form: " + customCSV);
	throw new ToolException("mdlForum tool cusomCSV not in required (user,course,courseURL) form: " + customCSV);
	userFromCSV = splitCSV[0];
	courseFromCSV = splitCSV[1];
	sectionFromCSV = splitCSV[2];
String responseUrl = mdlForumService.getConfigItem(MdlForumConfigItem.KEY_EXTERNAL_SERVER_URL).getConfigValue();

String returnUpdateUrl = URLEncoder.encode(
	TOOL_APP_URL + "/" + "&"
	+AttributeNames.PARAM_TOOL_CONTENT_ID + "=" + toolContentID.toString(), "UTF8"

responseUrl +=  "&lamsUpdateURL=" + returnUpdateUrl;	 

if (mdlForum.getExtSection() != null){
	responseUrl +=  "&section=" + mdlForum.getExtSection();
	responseUrl +=  "&section=" + sectionFromCSV;

if (mdlForum.getExtToolContentId()!=null){
	responseUrl += "&update=" + mdlForum.getExtToolContentId().toString();
	responseUrl += "&add=forum";

if (mdlForum.getExtCourseId() != null){
	responseUrl +="&course=" + mdlForum.getExtCourseId()
	responseUrl +="&course=" + courseFromCSV;

log.debug("Sending to moodle forum edit page: " + responseUrl);

Cloning Tool Content

For LAMS tools, there are several events that will trigger a request to clone the tool's content including starting a lesson, starting preview, copy-pasting an activity in author, and inserting a sequence in author. This is one of the most important extension points for a tool adapter tool as it takes care of a lot of the workflow and group implementation that LAMS is renowned for.

For native LAMS tools,  the normal implementation when starting a lesson is to go through each tool in the sequence and copy the tool content. This copy is then used the lesson so the original does not get altered. Then all the run time (learner) data generated is referenced by a tool session id generated for each group in the lesson. This serves two purposes: firstly, the tool session id ensures that data stored through the lesson is kept separate to tool content stored when the teacher authored the sequence (thus lessons can be re-used); and secondly, collaborative work done by a group will in a lesson will only be displayed to people in the group thus providing a real group based workflow.

This raises another difficulty with external tool adapter tools in that external LMS tools rarely have such a tool-content/tool-session implementation, they do not ordinarily keep authored content and run-time content separate. So when it comes time to create a tool session for our tool adapter, there is not much we can tell the external tool adapter tool about the tool session. Instead the way this can be fixed is to make another clone copy of the tool content for each tool session, that way for each group in a LAMS lesson, there will be a special run-time copy of the tool-content and the group-based workflow will be maintained. The downside of this is that the separation between authored content and learner content is lost. Subsequently some functionalities like editing existing activities in live edit will not produce desired results, however the main functionality of the tool in the context of LAMS can be maintained.

The customCSV is required here also to ensure the cloned external tool content is cloned in the correct course. Take this scenario for instance, if a teacher was to be teaching in two seperate courses and they created tool content in one of those courses. If they were to start a lesson with the learning design saved in the first course, then in the second course they would find that the learners not enrolled in the first course would not be able to see the content. Therefore when we clone a tool adapter activity for a lesson, the course the lesson is started from must also be saved.

So in order to implement this cloning, a call must be made to the external tool adapter servlet set up for this tool adapter. Here we simply pass the external content id of the tool, and the course id for the lesson, then the servlet clones the tool and returns a new external tool content id.The customCSV param should be added to any calls from the external servlet to start a new lesson. Check out the code below for the moodle/LAMS forum tool that calls the external servlet for cloning.

 /* ************ Methods from ToolSessionManager ************* */
public void createToolSession(Long toolSessionId, String toolSessionName,
		Long toolContentId) throws ToolException {
	if (logger.isDebugEnabled()) {
		logger.debug("entering method createToolSession:"
				+ " toolSessionId = " + toolSessionId
				+ " toolSessionName = " + toolSessionName
				+ " toolContentId = " + toolContentId);

	MdlForumSession session = new MdlForumSession();

	// learner starts
	MdlForum mdlForum = mdlForumDAO.getByContentId(toolContentId);

		// Get the required params, then call the eternal server
		HashMap<String, String> params = getRequiredExtServletParams(mdlForum);
		params.put(EXT_SERVER_PARAM_EXT_TOOL_CONTENT_ID, mdlForum.getExtToolContentId().toString());
	catch(Exception e)
		logger.error("Failed to call external server to copy tool content" + e);
		throw new ToolException("Failed to call external server to copy tool content" + e);


 * Calls the external server to copy the content and return a new id
 * @param extToolContentId
 * @return
public Long copyExternalToolContent(HashMap<String, String> params)
throws ToolException, Exception

 	String cloneServletUrl = mdlForumConfigItemDAO.getConfigItemByKey(MdlForumConfigItem.KEY_EXTERNAL_TOOL_SERVLET).getConfigValue();

 	// add the method to the params

	// Make the request
 	InputStream is = WebUtility.getResponseInputStreamFromExternalServer(cloneServletUrl, params);
	BufferedReader isReader = new BufferedReader(new InputStreamReader(is));
	String str = isReader.readLine();
	if (str == null) {
	    throw new UserInfoFetchException("Fail to clone forum in .LRN:"
	            + " - No data returned from external server");

	return Long.parseLong(str);

Learner Monitor

As you may have suspected another extension point that must be implemented is the learner and monitor interfaces. All the information you need to redirect to these pages should have been stored in the tool adapter's tables by the time you get to this point. So it should simply be a matter of constructing the learner and monitor URL based on the save parameters and then redirecting the user when the request is made.

Export Learning Design

How to implement export and import tool contentTo export a LAMS learning design, the authoring tool content needs to be serialised into a file so it can be imported again later in a different context. LAMS will go through a sequence and call each tool to output its tool content. This is made a bit more complicated for tool adapter tools, since they do not have the content stored locally, they only have an external content id. When the call is made to export the tool adapter content they have to call the external tool adapter servlet to request the content in a server to server call.

You will not need the customCSV for this so long as you saved the info in the customCSV in the LAMS tool content instance object, you will only need to retrieve the external tool adapter servlet url, and then add the parameters from the saved tool content.

Take note that you will need to handle the case where there is no external tool content (ie the authoring page for the external tool was never opened or saved).

Authentication (Required for all external server-to-server calls)

As with other integration server-to-server calls, the call to the tool adapter servlet will require a hash containing the timestamp, user, server id and secret server key. View the integrations page for more information on this.

Import Learning Design

Once you have handled the export correctly, you must handle the import. For this, the exported files that are stored on the user's hard drive will have to be transported in a multi-part post to the external server. Again, here we will need to set up an action in the external tool adapter servlet. When a tool adapter tool is called to import tool content, it will be sent the path to a file, and the customCSV parameter. The customCSV parameter is included here because it is often the case that to create a new instance of an external tool, the course and user information is required. With this parameters you can construct the multipart request using the file used for tool adapters.

Excerpt from MdlForumService.importToolContent()

File extExportFile = new File(toolContentPath + "/ext_tool.txt");

// if specially exported tooladapter file is found, send it to the external server
// otherwise, simply import an empty mdlForum
if (extExportFile.exists())

	try {

		String importServletUrl = mdlForumConfigItemDAO.getConfigItemByKey(MdlForumConfigItem.KEY_EXTERNAL_TOOL_SERVLET).getConfigValue();

		if (customCSV== null)
			logger.error("Could not retrieve customCSV required for importing tool adapter tool. CustomCSV: " + customCSV);
			throw new ToolException("Could not retrieve customCSV required for importing tool adapter tool. CustomCSV: " + customCSV);

		HashMap<String, String> params = getRequiredExtServletParams(customCSV);

		// Do the external multipart post to upload the file to external LMS (returns an extToolContentId)
		InputStream is = WebUtility.performMultipartPost(extExportFile, EXT_SERVER_PARAM_UPLOAD_FILE,  importServletUrl, params);
		DataInputStream inStream = new DataInputStream ( is );
		String str = inStream.readLine();
		Long extContentId = Long.parseLong(str);

		// Save the resulting mdl forum
		MdlForum mdlForum = new MdlForum();
		mdlForum.setCreateDate(new Date());

	} catch (Exception e) {
		logger.error("Problem passing mdlForum export file to external server", e);
		throw new ToolException(e);

Export Portfolio

Export Portfolio is another extension point that can be implemented although it is not essential as most LMS tool do not have a concept of export portfolio. Basically, another call should be made to the external servlet requesting the file, this request should pass the external tool content id and the user id.

Tool Outputs

Tool Outputs are also an options extension point that you may like to implement. Here you can follow the same steps as are outline in the tool outputs wiki page. But instead of the getToolOutputs() call being a local call, you will need to again call the tool adapter servlet and pass the external tool content id and the user id, then return any data you wish about what the student has achieved in the activity.

  • No labels