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:
- A user called "Bill" starts from external LMS "Moodle" logged in as a teacher
- User clicks on the LAMS "Open Author" link which is controlled by the integration.
- 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.
- User is authenticated in LAMS as "moodle_Bill".
- User drags a moodle forum tool in LAMS author onto the authoring frame and opens the authoring page for the tool.
- User is redirected to the moodle forum tool author page which is located on the external "Moodle" server.
- 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.
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.
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.