< Previous | Contents | Next >

4.2.3. Comments From LMS

The cmi.comments_from_lms data model element contains comments and annotations intended to be seen by all learners for the SCO for which they are defined. These comments are intended to be a mechanism for adding information of interest to all learners in a particular community, instructor notes, etc. SCORM does not define a mechanism for how these comments are initialized. LMSs are free to provide a mechanism to support the creation and initialization of this data. This support is not required for SCORM conformance.

How this information is presented or used is outside the scope of SCORM. One such use would be for the ability to retrieve the comments and display them to the learner upon launch of the SCO (or during some point in the learner session).

The value of cmi.comments_from_lms is intended to provide information about the SCO or the learning experience with the SCO. The structure of this data is not specified by SCORM.

The LMS shall support at least the SPM of 100 comments from the LMS. The LMS is free to support more than the SPM.


Table 4.2.3a: Dot-notation Binding for the Comment from LMS Data Model Element


Dot-Notation Binding

Details

cmi.comments_from_lms._children

The cmi.comments_from_lms._children data model element represents a listing of supported data model elements. This data model element is typically used by a SCO to determine which data model elements are supported by the LMS. The characterstring returned may be used by the SCO to dynamically build parameters for the GetValue() and SetValue() requests.

Data Model Element Implementation Requirements:

Data Type: characterstring

Value Space: ISO-10646-1 [5]

Format: A comma-separated list of all of the data model


Dot-Notation Binding

Details


elements in the Comments From LMS parent data model element that are supported by the LMS. Since all data model elements are required to be supported by the LMS, the characterstring shall represent the following data model elements:

o comment

o location

o timestamp

LMS Behavior Requirements:

This data model element is mandatory and shall be implemented by an LMS as read-only.

The LMS is responsible for returning a comma-separated list of all of the data model elements (refer to Data Model Element Implementation Requirements above).

SCO Behavior Requirements:

This data model element is required to be implemented by an LMS as read-only. The SCO is only permitted to retrieve the value of the cmi.comments_from_lms._children data model element.

API Implementation Requirements:

GetValue(): The LMS shall return a comma-separated list of data model elements supported by the LMS (refer to Data Model Element Implementation Requirements above) and set the error code to 0 – No Error. The ordering of elements is not important. The characterstring returned shall adhere to the requirements identified in the Data Model Element Implementation Requirements.

SetValue(): If the SCO invokes a SetValue() request to set the cmi.comments_from_lms._children, then the LMS shall set the error code to 404 – Data Model Element Is Read Only and return “false”.

Example:

GetValue(“cmi.comments_from_lms._children”)

cmi.comments_from_lms._count

The cmi.comments_from_lms._count keyword is used to describe the current number of comments from the LMS that are currently being stored by the LMS. The total number of entries currently being stored by the LMS shall be returned.

Data Model Element Implementation Requirements:

Data Type: integer

Value Space: Non-negative integer

Format: The characterstring representing the number of comments that the LMS is currently persisting.

LMS Behavior Requirements:

This data model element is mandatory and shall be implemented by the LMS as read-only.

If the LMS receives a request to get the cmi.comments_from_lms._count value prior to any comments being set by the SCO, then the LMS shall adhere to the requirements listed below for API Implementation Requirements.

SCO Behavior Requirements:

The data model element is required to be implemented by an LMS as read-only. The SCO is only permitted to retrieve the value of the cmi.coments_from_lms._count data model element.

API Implementation Requirements:

GetValue(): The LMS shall return the number of comments


Dot-Notation Binding

Details


currently stored by the LMS and set the error code to 0 – No Error.

o If there are no comments defined for this element, then the LMS shall return 0 and set the error code to 0.

SetValue(): If the SCO invokes a SetValue() request to set the cmi.comments_from_lms._count, then the LMS shall set the error code to 404 – Data Model Element Is Read Only and return “false”.

Example:

GetValue(“cmi.comments_from_lms._count”)

cmi.comments_from_lms.n.comment

The cmi.comments_from_lms.n.comment data model element shall describe comments or annotations associated with a SCO [1]. The characterstring value represents the localized characterstring.

Data Model Element Implementation Requirements:

Data Type: localized_string_type (SPM: 4000)

Value Space: A characterstring (defined by ISO-10646-1) with localization information

Format: Refer to Section 4.1.1.7: Data Types for more information on the requirements for the format of the localized_string_type data type.

LMS Behavior Requirements:

The data model element is mandatory and shall be implemented by an LMS as read-only.

How this data model element is initialized is outside the scope of SCORM. The LMS may provide a means to allow the author/instructor to provide the comments and these comments may then be used to initialize this value. If a GetValue() request is made prior to the comment being set or initialized by the LMS, then the LMS shall behave according to the API Implementation Requirements below.

SCO Behavior Requirements:

The data model element is required to be implemented by an LMS as read-only. The SCO is only permitted to retrieve the value of the cmi.comments_from_lms.n.comment data model element.

During a GetValue() request, the SCO should be aware that the delimiter may be part of the characterstring returned by the LMS (depending on the LMS implementation). What the SCO does with the characterstring returned by the LMS is dependent on the implementation of the SCO. If no delimiter is provided the SCO shall assume the default language of “en”.

API Implementation Requirements:

GetValue(): The LMS shall return the value stored for the cmi.comments_from_lms.n.comment data model element and set the error code to 0 – No Error. The characterstring returned shall adhere to the requirements identified in the Data Model Element Implementation Requirements.

o The data model binding for collections is represented as packed arrays. If the SCO invokes a GetValue() request where the index (n) is a number larger than what the LMS is currently maintaining (e.g., the request indicated an n value of 5 when there are only 3 comments in the array), then the LMS shall set the error code to 301 – General Get

Failure and return an empty characterstring (“”).


Dot-Notation Binding

Details


Refer to Section 3.1.7.6: SCORM Extension Error Conditions for further recommendations on processing this request.

o If the SCO attempts to retrieve the cmi.comments_from_lms.n.comment and the record of data has been created but the comment data model element has not been set by the LMS, then the LMS shall set the error code to 403 - Data Model Element Value Not Initialized and return an empty characterstring (“”).

SetValue(): If the SCO invokes a SetValue() request to set the cmi.comments_from_lms.n.comment, then the LMS shall set the error code to 404 – Data Model Element Is Read Only and return “false”. The LMS shall not alter the state of the data model element based on the request.

Example:

GetValue(“cmi.comments_from_lms.0.comment”)

cmi.comments_from_lms.n.location

The cmi.comments_from_lms.n.location data model element indicates the point in the SCO to which the comment applies. This data model element is implementation-defined by each SCO. If no value is specified for location, then the comment is applicable to the entire SCO (as a whole) [1].

Data Model Element Implementation Requirements:

Data Type: characterstring (SPM: 250)

Value Space: ISO-10646-1

Format: Refer to Section 4.1.1.7: Data Types for more information on the requirements for the format of the characterstring data type.

LMS Behavior Requirements:

The data model element is mandatory and shall be implemented by the LMS as read-only.

How this element is initialized is outside the scope of SCORM. The LMS may provide a means to allow the author/instructor to provide the comments (along with a location and date) and these comments may then be used to initialize this value. If a GetValue() request is made prior to the location being set or initialized by the LMS, then the LMS shall behave according to the API Implementation Requirements below.

SCO Behavior Requirements:

The data model element is required to be implemented by an LMS as read-only. The SCO is only permitted to retrieve the cmi.comments_from_lms.n.location data model element.

API Implementation Requirements:

GetValue(): The LMS shall return the value stored for the cmi.comments_from_lms.n.location data model element and set the error code to 0 – No Error. The characterstring returned shall adhere to the requirements identified in the Data Model Element Implementation Requirements.

o The data model binding for collections is represented as packed arrays. If the SCO invokes a GetValue() request where the index (n) is a number larger than what the LMS is currently maintaining (e.g., the request indicated an n value of 5 when there are only 3 comments in the array), then the LMS shall set the error code to 301 – General Get

Failure and return an empty characterstring (“”).


Dot-Notation Binding

Details


Refer to Section 3.1.7.6: SCORM Extension Error Conditions for further recommendations on processing this request.

o If the SCO attempts to retrieve the cmi.comments_from_lms.n.location and the record of data has been created but the location data model element has not been set by the LMS, then the LMS shall set the error code to 403 - Data Model Element Value Not Initialized and return an empty characterstring (“”).

SetValue(): If the SCO invokes a SetValue() request to set the cmi.comments_from_lms.n.location, then the LMS shall set the error code to 404 – Data Model Element Is Read Only and return “false”. The LMS shall not alter the state of the data model element based on the request.

Example:

GetValue(“cmi.comments_from_lms.0.location”)

cmi.comments_from_lms.n.timestamp

The cmi.comments_from_lms.n.timestamp data model element indicates the point in time at which the comment was created or most recently changed. Implementation shall support, minimally, time periods in the range of January 1, 1970 through January 1, 2038 [1].

Data Model Element Implementation Requirements:

Data Type: time(second,10,0)

Value Space: The data type denotes that the value for time is a number expressed as a real data type with values that are accurate to one second and optionally accurate to one hundredth of a second (0.01). The number of seconds in the time value is the number of seconds since 00:00 on January 1, 1970 [1].

Format: Refer to Section 4.1.1.7: Data Types for more information on the requirements for the format of the time (second,10,0) data type.

LMS Behavior Requirements:

The data model element is mandatory and shall be implemented by the LMS as read-only.

How this element is initialized is outside the scope of SCORM. The LMS may provide a means to allow the author/instructor to provide the comments (along with a location and date) and these comments may then be used to initialize this value. If a GetValue() request is made prior to the timestamp being set or initialized by the LMS, then the LMS shall behave according to the API Implementation Requirements below.

SCO Behavior Requirements:

The data model element is required to be implemented by an LMS as read-only. The SCO is only permitted to retrieve the value of the cmi.comments_from_lms.n.timestamp data model element.

API Implementation Requirements:

GetValue(): The LMS shall return the value stored for the cmi.comments_from_lms.n.timestamp data model element and set the error code to 0 – No Error. The characterstring returned shall adhere to the requirements identified in the Data Model Element Implementation Requirements.

o The data model binding for collections is represented as packed arrays. If the SCO invokes a GetValue() request where the index (n) is a number

larger than what the LMS is currently maintaining


Dot-Notation Binding

Details


(e.g., the request indicated an n value of 5 when there are only 3 comments in the array), then the LMS shall set the error code to 301 – General Get Failure and return an empty characterstring (“”). Refer to Section 3.1.7.6: SCORM Extension Error Condition for further recommendations on processing this request.

o If the SCO attempts to retrieve the cmi.comments_from_lms.n.timestamp and the record of data has been created but the timestamp data model element has not been set by the LMS, then the LMS shall set the error code to 403 - Data Model Element Value Not Initialized and return an empty characterstring (“”).

SetValue(): If the SCO invokes a SetValue() request to set the cmi.comments_from_lms.n.timestamp, then the LMS shall set the error code to 404 – Data Model Element Is Read Only and return “false”. The LMS shall not alter the state of the data model element based on the request.

Example:

GetValue(“cmi.comments_from_lms.0.timestamp”)