Skip to end of metadata
Go to start of metadata

Introduction

The authoring package in the lams_central project authoring module supports the Flash authoring client. It primarily stores and retrieves learning designs and activity libraries.
For the moment, it also supports the definition of styles. This functionality may move to the central area.

For detailed explanation on each of the following methods listed below please refer to lams_central\src\java\org\lamsfoundation\lams\authoring\service\ IAuthoringService.java

LEARNING DESIGN AND RELATED NOTES

In general there is an UI ID for the Flash client and also an equivalent (database) primary key ID. Flash matches up objects using the UI ID and Java converts that to ID. The UI ID is unique within a learning design, the primary key ID is unique across a LAMS installation (ie in the database). It is done this way so that Flash doesn't have to keep calling the server to get a new unique ID.

This is a rough list of entities used in authoring and their properties. The notes on the entities refers to changes from LAMS 1.0 to LAMS 2.0.

Key:
+ =  property added
- = property removed
# = property altered
??? = property that doesn't exist right now but probably should
//<blah> = a comment or question by me
pk = primary key = db identifier
[f] = needed by flash

Learning Design
learning_design_id (integer, 20 figures, DB PK - supplied at save time) [f]
id (int, nullable - used by flash?) [d.c: shoulc not be needed anymore]
description (text, nullable) [f]
title (255 characters, nullable)[f]
first_activity_id (int, PK of first activity, nullable)
first_id(flash generated id to indicate which is first activity, as above but not pk version)[f]
max_id (int, nullable - used by flash) [f]
valid_design_flag( 1 = true or 0 = false - indicates if this LD can be run as a lesson)[f]
read_only_flag(1 = true or 0 = false) [f][d.c: depends on how workspace/folder stuff works out]
date_read_only (date time nullable) [f?]
user_id (int, pk of creating user) [f?]
help_text (text, nullable) [f]
lesson_copy_flag ( 1 = true, 0 = false - indicates if this LD is a copy created for a lesson) [d.c:should not appear to authoring, lesson/monitor only]
create_date_time (datetime) [f]
# version (56 characters, nullable) //changed to nullable [f?]
parent_learning_design_id (int, nullable: pk of parent LD - could be the LD this is a copy of, or the previous version of the LD) [f?]
- open_date_time (datetime, nullable - first datetime when learners can begin the LD) //in lesson now
- close_date_time (datetime, nullable - last datetime when learners can being LD) //in lesson now
duration (int, nullable: milleseconds indicating how long the LD should run for)
workspace_folder_id (int, pk of folder where this LD resides) //replace by a join table instead?
??? some more metadata fields (ernie?)[f??]

Transition
learning_transition_id (int pk supplied at save time)
id (int nullable, used by flash) [f]
description (text nullable) [f]
title (255 characters nullable)[f]
to_acitivity_id (int nullable, pk of the activity this transition leads to) //why is this nullable?
from_activity_id (int nullable, pk of the activity this transition leads to) //why is this nullable?
learning_design_id (int, pk of LD this transition belongs to)
create_date_time (datetime)
+ to_id (int nullable used by flash)[f]
+from_id (int nullalbe used by flash)[f]

Activity
activity_id (int pk supplied at save time)
id (int, nullable, used by flash) [f]
description (text, nullable) [f]
title (255 characters, nullable)[f]
xcoord (int, nullable) [f]
ycoord (int, nullable) [f]
parent_activity_id (pk of parent activity, nullable - this will be set if this activity is inside a complex
activity which will be the parent activity)
parent_id (int, nullable used by flash ti indicate parent relationship)[f]
learning_activity_type_id (int enumeration: values indicate type of activity(sad) 1='TOOL', 2='GROUPING_RANDOM',  3= 'GROUPING_CHOSEN', 4= 'GATE_SYNCH', 5='GATE_SCHEDULE', 6='GATE_PERMISSION', 7='PARALLEL', 8='OPTIONS', 9='SEQUENCE') [f]
grouping_id (int nullable: the pk of the grouping to be applied to this activity)
grouping_ui_id(?new name? Need some consistent way to identify the flash generated id system)[f]
order_id (int nullable, activities within a complex activity use this field to show order) [f]
define_later_flag (1 = true, 0 = false, default false) //not currently used [f: will need some way of flagging this to flash if this is not used]
learning_design_id (int nullable ,pk of learning design this activity is part of, activity must have either this or the learning_design_id set) <<?chris should this be library?  
learning_libary_id (int nullable, pk of learning library this is part of, see above) [f]
create_date_time (datetime)
offline_instructions (text, nullable, instructions for use offline) [f]
 
GroupingActivity
createGroupingID (int, pk of grouping to be created by this activity)
createGroupingUIID (int) [f]

PermissionGateActivity
as Activity plus
gate_activity_level_id (int enumeration: 1 = learner, 2 = group, 3 =
class) [f]

ScheduleGateActivity
as Activity plus
- gate_activity_level_id:  Possible Values: (int enumeration: 1 = learner,2 = group, 3 =
class) . Will always be  3 = class at present as the server can't support learner or group.
- gate_start_time_offset: long int, not null, number of minutes from start of lesson to open gate. If the gate should start open, then this should be set to 0.
- gate_end_time_offset: long int, nullable, number of minutes from start of lesson to close gate. If not set, then the gate will stay open once it has passed the gate_start_time_offset.

SynchGateActivity
as Activity plus
gate_activity_level_id (int enumeration: 1 = learner, 2 = group, 3 =
class) //only 2 and 3 make sense for this one [f]

ToolActivity
as Activity plus
tool_id (int, pk of tool this activity uses)
tool_content_id (int, key used to identify content to tool)
tool_ui_id[f]
tool_content_ui_id[f]

ComplexActivity
<complext activities include an ordered set of other activities -    in the db this is indicated by parent_activity_id and order_id>

ParallelActivity
as ComplexActivity

SequenceActivity
as ComplexActivity

OptionsActivity
as ComplexActivity plus
max_number_of_options (int 5 figures, default 0) [f]
max_number_of_options (int 5 figures, nullable) [f]
+ option instructions (text, nullable)[f]

Grouping
groupingID (integer pk supplied at save time)
groupingUIID [f]
groupingTypeId (int enum: 1 = RandomGrouping, 2 = ChosenGrouping [f]
+ id (int nullable used by flash)[f]

ChosenGrouping
as Grouping
 
RandomGrouping
as Grouping plus
numberOfGroups (int, number of groups to create, one of either
this one or the following) [f]
learnersPerGroup (int, number of learners in each created group,
see above) [f]

LearningLibrary
[f:each library activity is contained within one LearningLibrary. Should this be represented in the flash WDDX??]
learning_library_id (integer pk)
description (text)
title (255 characters)
create_date_time (datetime)

Workspace
workspace_id (integer pk supplied at save time)
root_folder_id (pk of root folder: should be created when workspace is created)
+ name field (255 characters)

WorkspaceFolder
workspace_folder_id (integer pk supplied at save time)
parent_folder_id (pk of parent folder, nullable)
name (64 characters)

Grouping Examples

The grouping is a bit hard to understand, so a couple of examples are given below to illustrate the structure. Each grouping activity creates a grouping. An activity that is grouped is related to a grouping - and not to the grouping activity.

Example 1: Q&A activity done with a Random Grouping. This is would be like splitting a high school class into groups to answer the question. Initial data on client. The UIID fields are used to link the objects.
 
When the data is sent from the client to the server, only the grouping activities should include the createGroupingUIID, createGroupingID fields.
When the data is sent back from the server to the client, only the grouping activities should include the createGroupingUIID, createGroupingID fields. In the current example packet learning_design.xml, it shows all activities with the createGrouping* fields - this is not correct. While these fields exist in our flattened AuthoringActivityDTO, the fields should be null and hence should not be included in the wddx packet (null fields not sent from server to client).

The details required to make up the groups (numberOfGroups, leanersPerGroup) are in the grouping, not in the grouping activity. The grouping activities are in an array of their own - the groupings are not stored as part of the activity structure.

Example 2: Noticeboard, done with a Random Grouping. After saving onto server (which sets the ID fields).
 
Example 3: Two levels of grouping. The entire lesson is split into groups using a chosen grouping, and then the chosen groups are further split using random grouping. The Q&A activity is done with the Random Grouping. This is would be like splitting an entire course (e.g. 600 people) into 6 streams, and then randomly grouping student from a stream into a tutorial size group. The diagram below shows the initial data on client. The UIID fields are used to link the objects.

Authoring Server Calls

Typical sequence of calls from the Flash client to the server:

Store Learning Design Servlet

POST Body: Learning Design packet
URL: http://<server>/lams/authoring/authoring/storeLD
Returns:
    A WDDX packet containing the
design id Unique id for this design.
Sample Input Packet:
See storeLearningDesignDetails.xml for a sample packet.

See Learning Design Validation for details on the server validation of learning designs.

Sample Output Packet:
<wddxPacket version='1.0'><header/><data>
<struct type='Lorg.lamsfoundation.lams.util.wddx.FlashMessage;'>
<var name='messageKey'><string>storeLearningDesignDetails</string></var>
<var name='messageType'><number>3.0</number></var>
<var name='messageValue'>
<struct type='Lorg.lamsfoundation.lams.authoring.dto.StoreLearningDesignResultsDTO;'>
<var name='learningDesignID'><number>22.0</number></var>
<var name='valid'><boolean value='true'/></var>
</struct></var></struct></data></wddxPacket>

Authoring Action: getLearningDesignDetails(Long learningDesignID)

Get a learning design.
Parameters: learningDesignID
URL: http://<server> /lams/authoring/author.do?method=getLearningDesignDetails&learningDesignID=<value>
Returns: A WDDX packet containing the learning design.
Sample Output Packet:
See learning_design.xml for a sample packet.

Authoring Action: getAllLearningLibraryDetails()

Get the library activities, to be displayed in the toolkit on the left hand side.
Parameters: None
URL: http://<server> /lams/authoring/author.do?method=getAllLearningLibraryDetails
Returns: A WDDX packet containing the learning design.
Sample Output Packet:
See all_learning_designs.xml and all_library_details.xml .

Authoring Action: copyToolContent(Long toolContentID)

Calls an appropriate tool to copy the content indicated by toolContentId. Returns a string representing the new tool content id in WDDX format.
Parameters: toolContentID
URL:
http://<server>/lams/authoring/author.do?method=copyToolContent&toolContentID=<value>
Returns:
    A WDDX packet containing the
        toolContentID the new tool content id required

Sample Output Packet:
<wddxPacket version='1.0'><header/><data>
<struct type='Lorg.lamsfoundation.lams.util.wddx.FlashMessage;'>
<var name='messageKey'><string>copyToolContent</string></var>
<var name='messageType'><number>3.0</number></var>
<var name='messageValue'><number>6.0</number></var></struct></data></wddxPacket>

Copy Multiple Tool Content Servlet

Calls all the appropriates tool to copy the content indicated by toolContentIds. Batch version of copyToolContent(). Returns a string representing the old and new tool content ids in WDDX format.

Parameters: toolContentIDs

URL:
http://<server>/lams/servlet/authoring/copyMultipleToolContent

Sample Input Packet:

<wddxPacket version="1.0"><header /><data><struct><var name="toolContentIDs"><string>86,87,90</string></var></struct></data></wddxPacket>

Sample Output Packet:

<wddxPacket version='1.0'><header/><data><struct type='Lorg.lamsfoundation.lams.util.wddx.FlashMessage;'>
<var name='messageKey'><string>copyMultipleToolContent</string></var><var name='messageType'><number>3.0</number></var>
<var name='messageValue'><string>86=106,87=107,90=108</string></var></struct></data></wddxPacket>

If the input packet has invalid ids, such as:

<wddxPacket version="1.0"><header /><data><struct><var name="toolContentIDs"><string>,,</string></var></struct></data></wddxPacket>

<wddxPacket version="1.0"><header /><data><struct><var name="toolContentIDs"><string> </string></var></struct></data></wddxPacket>

Then the return packet is:

<wddxPacket version='1.0'><header/><data><struct type='Lorg.lamsfoundation.lams.util.wddx.FlashMessage;'>
<var name='messageKey'><string>copyMultipleToolContent</string></var><var name='messageType'><number>3.0</number></var>
<var name='messageValue'><string></string></var></struct></data></wddxPacket>

If the input packet has an id that doesn't exist in the database (ie not recorded in the tool content id table) then the output packet will be the error:

<wddxPacket version='1.0'><header/><data><struct type='Lorg.lamsfoundation.lams.util.wddx.FlashMessage;'>
<var name='messageKey'><string>copyMultipleToolContent</string></var><var name='messageType'><number>1.0</number></var>
<var name='messageValue'><string>Invalid Object in WDDX packet. Error was The toolContentID 101 is not valid. No such record exists on the database..</string>
</var></struct></data></wddxPacket>

Note: any toolContentID returned by the server in the call to get a tool content id is recorded in the tool content id table, irrespective of whether or not the tool actually has any data. If the tool doesn't have any content for that id, it should be copying the default content.

Insert Learning Design Servlet

URL to call: http://<server>/lams/servlet/authoring/insertLearningDesign

This is a servlet and the input is a WDDX packet.

This can be used in two ways. Only Case 1 (insert into a design) will be supported in the Authoring client.

Case 1: Insert one learning design into another learning design, updating the latter learning design.

learningDesignId: Id of a learning design to be updated.
learningDesignIDToImport: Id of a the design to be inserted (this one won't be changed).
createNewLearningDesign: false

When the server is called, the contents of learningDesignIDToImport design is copied into the design learningDesignId, with the UIIDs, etc in the learningDesignIDToImport portion updated so that they don't conflict.

Sample packet:

<wddxPacket version="1.0"><header /><data><struct><var name="learningDesignID"><number>4</number></var>
<var name="learningDesignIDToImport"><number>16</number></var>
<var name="createNewLearningDesign"><boolean value="false" /></var></struct></data></wddxPacket>

Case 2: Insert one learning design into another learning design, creating a new learning design.

learningDesignID, learningDesignIDToImport: Ids of two learning designs to be combined. Neither design will be updated
workspaceFolderID: Destination folder for the new design.
title: Title for the new design.
createNewLearningDesign: true.

Sample packet:

<wddxPacket version="1.0"><header /><data><struct><var name="learningDesignID"><number>14</number></var>
<var name="learningDesignIDToImport"><number>15</number></var><var name="createNewLearningDesign"><boolean value="true" /></var>
<var name="workspaceFolderID"><number>5</number></var><var name="title"><string>Two Branches</string></var>
</struct></data></wddxPacket>

When the server is called, the contents of learningDesignId design is copied to a new design in the specified folder, and the contents of the learningDesignIDToImport design are added to the new design, with the UIIDs, etc in the learningDesignIDToImport portion updated so that they don't conflict.

CLIENT UPDATES

The following values will be used to trigger client updates (avoid problems with the browser caching client), dictionary updates and clear the local Flash cache.
The following values are stored in the configuration file:
?    Authoring client version
?    Monitor client version.
?    Learner client version.
?    Server Version Number
?    The date that each dictionary was created.
?    Server language - the language in use for this server
The versions are the overall LAMS version and a build number based on cvs (e.g 1.1 build 1.25)
When the client is started, the call (in the jsp) will be something like:
.swf?build=<client version #>&lang=<lang code>&date=<dictionary date for language>

A sample extract of the configuration file representing the values stated above are:
<AuthoringClientVersion>1.0</AuthoringClientVersion>
<MonitorClientVersion>1.1</MonitorClientVersion>
<LearnerClientVersion>1.2</LearnerClientVersion>
<ServerVersionNumber>1.1</ServerVersionNumber>
<ServerLanguage>en_AU</ServerLanguage>
<DictionaryDates>
    <Dictionary>
        <language>en_AU</language>
        <createDate>2006-01-02</createDate>
    </Dictionary>
    <Dictionary>
        <language>en_US</language>
        <createDate>2006-01-03</createDate>
    </Dictionary>
</DictionaryDates>

METADATA & LICENSES

The "Save As" dialog in the Flash client will be a tabbed dialog, with the second tab containing all the metadata for a design (including versions). The same dialog will be used for Saving and for editing the properties. The button will be either "Save" to save to the server or "Okay" to update the local copy depending on how the dialog box is triggered.
LAMS will have a fixed set of licenses and sites will not be able to update the license table - if they have their own then they need to go into the OTHER license. If sites put other entries in the table then compatibility with other systems and future versions is not supported.

Each version of a license from Creative Commons will be a separate license (i.e. another row in the database) so the "Names" of the licenses should contain the version numbers.
The license id, code and text will all be included in the import/export file. On importing, the license will be selected based on id and cross checked against the name. They do not match, then design will be marked with an "OTHER" license and the text from the import file used as the license text. The method License.isSameLicenseType() will do this check. For the purposes of importing/exporting, it may be used to set up a LicenseService. If this is done, then the getAvailableLicenses() call in AuthoringService should be moved to the new LicenseService.

Authoring Action: getLicenses()

Get all the available licenses
Parameters: None
URL: http://<server>/lams/authoring/author.do?method=getAvailableLicenses
Returns: WDDX Packet with a list of LicenseDTOs in the messageValue field.
Sample WDDX Packet: Note - currently we have 6 licenses, not 2. Only 2 shown for brevity.
<wddxPacket version='1.0'><header/><data>
<struct type='Lorg.lamsfoundation.lams.util.wddx.FlashMessage;'>
<var name='messageKey'><string>getAvailableLicenses</string></var>
<var name='messageType'><number>3.0</number></var><var name='messageValue'>
<array length='2'>
<struct type='Lorg.lamsfoundation.lams.learningdesign.dto.LicenseDTO;'>
    <var name='code'><string>by-nc-sa</string></var>
    <var name='defaultLicense'><boolean value='true'/></var>
    <var name='licenseID'><number>1.0</number></var>
    <var name='name'><string>Attribution-Noncommercial-ShareAlike 2.5</string></var>
    <var name='pictureURL'><string>http://localhost:8080/lams//images/license/byncsa.jpg</string></var>
    <var name='url'><string>http://creativecommons.org/licenses/by-nc-sa/2.5/</string></var>
</struct>
<struct type='Lorg.lamsfoundation.lams.learningdesign.dto.LicenseDTO;'>
    <var name='code'><string>other</string></var>
    <var name='defaultLicense'><boolean value='false'/></var>
    <var name='licenseID'><number>2.0</number></var>
    <var name='name'><string>Other Licensing Agreement</string></var>
    <var name='pictureURL'><string></string></var>
    <var name='url'><string></string></var>
</struct>
</array></var></struct></data></wddxPacket>

Main Flash Components

This diagram shows the main components of the Flash authoring environment. The look is out of date but the overall components are much the same.

  • No labels