 |
1EdTech Shareable State Persistence SCORM® Application Profile Version 1.0 Final Specification |
Copyright © 2004 1EdTech Consortium, Inc. All Rights Reserved.
The 1EdTech Logo is a trademark of 1EdTech Consortium, Inc.
Document Name: 1EdTech Shareable State Persistence SCORM® Application Profile
Revision: 18 June 2004
IPR and Distribution Notices
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.
1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.
Copyright © 2004 1EdTech Consortium. All Rights Reserved.
If you wish to copy or distribute this document, you must complete a valid Registered User license registration with 1EdTech and receive an email from 1EdTech granting the license to distribute the specification. To register, follow the instructions on the 1EdTech website: http://www.imsglobal.org/specificationdownload.cfm.
This document may be copied and furnished to others by Registered Users who have registered on the 1EdTech website provided that the above copyright notice and this paragraph are included on all such copies. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to 1EdTech, except as needed for the purpose of developing 1EdTech specifications, under the auspices of a chartered 1EdTech project group.
Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/license.html.
The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.
THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.
Table of Contents
1. Introduction
1.1 Nomenclature
1.2 References
2. SCORM Application of the SSP XML Binding
2.1 <bucket> Element
2.2 <size> Element
3. SSP SCORM Runtime Behavior
3.1 Data Bucket Uniqueness
3.2 Contextualized Data Bucket Access
3.3 Static Declaration of Data Buckets
3.4 Dynamic Declaration of Data Buckets
3.5 Persistence of Data Buckets
3.6 Contextualized Access to Data Buckets
3.7 Anonymous Access to Data Buckets
4. SCORM Application of the SSP Information Model
4.1 Binding the SSP Abstract API to Dot-notation
4.1.1 Data Type
4.1.2 SCORM Extension Error Conditions
4.1.3 Reserved Delimiters
4.2 SCORM Dot-Notation
4.2.1 <dot-notation characterstring representation of the data model element>
4.3 Bucket Collection Manager Interface
4.3.1 ssp._count
4.3.2 ssp.allocate
4.3.3 ssp.n.id
4.3.4 ssp.n.allocation_success
4.3.5 ssp.n.bucket_state
4.3.6 ssp.n.data.{offset=<nonNegativeInteger>}{size=<nonNegativeInteger>}
4.3.7 ssp.n.data
4.3.8 ssp.n.appendData
4.4 Bucket Manager Interface
4.4.1 ssp.bucket_state
4.4.2 ssp.data.{bucketID=<GUID>}{offset=<nonNegativeInteger>}
{size=<nonNegativeInteger>}
4.4.3 ssp.data
4.4.4 ssp.appendData
About This Document
List of Contributors
Revision History
Index
1. Introduction
A common requirement of most interactive content is the need to store information about the "state" of the learning experience at a given time. State information is usually a collection of data about variables that are important to the content's function. In a flight simulator this would include information about the plane's speed, trajectory, altitude, fuel consumption, and the settings of various controls. In a sales simulation, variables would include things like the attitudes of customers, the facility of the salesperson in responding to customer objections, and a record of sales calls and other activities. In an executive information system, variables would be initiatives and change management tactics used to try to convince the managers to adopt a proposed innovation.
The Sharable Content Object Reference Model (SCORM®) defines how Sharable Content Objects (SCOs) can communicate and persist information regarding their state through the SCORM Run-Time Data Model, however these provisions have restrictions. For example, a SCO can load and store state information in Run-Time Data Model elements such as cmi.launch_data and cmi.suspend_data, but these elements are severely limited in size and cannot be accessed by other SCOs. The 1EdTech Shareable State Persistence Specification provides an interoperable way to resolve these restrictions. It defines an abstract service that enables content objects to declare and access data buckets - places to store and share arbitrary data.
This document describes an informative SCORM Version 2004 application profile of the 1EdTech Shareable State Persistence (SSP) Specification. Readers of this document should be familiar with the 1EdTech SSP Information Model and XML Binding. The scope of this document, depicted as the SSP Conceptual Model applied in a SCORM environment, consists of the following sections:
- SCORM Application of the SSP XML Binding - how explicit bucket requirements may be associated with a SCO resource - describes how the SSP XML Binding should be included in a SCORM Content Package.
- SSP SCORM Run-Time Behavior - what responsibilities an LMS has for applying explicit bucket requirements prior to launching a SCO - describes bucket persistence requirements and how a SCORM LMS should apply a SCO's explicit data bucket requirements.
- SCORM Application of the SSP Information Model - how SCOs can invoke the SSP Abstract APIs to access data buckets - describes how the SSP Information Model and its abstract API are bound to the SCORM Run-Time API using dot-notation.
This document should not be interpreted as being a part of SCORM 2004, but as a suggested extension to the SCORM 2004. Systems are not required to implement what is described here to be SCORM conformant. Several SSP use cases (detailed in the SSP Information Model) could occur within a SCORM environment. The primary goal of this document is to enable those use cases to be deployed across various SCORM systems that agree to implement this application profile.
1.1 Nomenclature
1.2 References
| [SSP, 04a] | 1EdTech Shareable State Persistence Information Model v1.0, A.Jackl, A.Panar, B.Towle, 1EdTech Consortium, Inc., June 2004. |
| [SSP, 04b] | 1EdTech Shareable State Persistence XML Binding v1.0, A.Jackl, B.Towle, 1EdTech Consortium, Inc., June 2004. |
| [SSP, 04c] | 1EdTech Shareable State Persistence Best Practice and Implementation Guide v1.0, A.Jackl, 1EdTech Consortium, Inc., June 2004. |
| [IEEE API] | IEEE 1484.11.2-2003, ECMAScript API for Content to Runtime Services Communication (http://ltsc.ieee.org). |
| [IEEE LOM] | IEEE 1484-12:2002, Standard for Learning Object Metadata, (http://ltsc.ieee.org). |
| [IMSBUND] | Using 1EdTech Content Packaging to Package Instances of LIP and Other 1EdTech Specifications v1.0, B.Olivier, M.McKell, 1EdTech Consortium, Inc., August 2001. |
| [IMSPLID] | 1EdTech Persistent, Location-Independent, Resource Identifier Implementation Handbook v1.0, M.McKell, 1EdTech Consortium, Inc., April 2001. |
| [SCORM CAM] | The SCORM Content Aggregation Model Version 1.3 (http://www.adlnet.org). |
| [SCORM RTE] | The SCORM Run-Time Environment Model Version 1.3 (http://www.adlnet.org). |
| [UNICODE] | The Unicode specification (http://www.unicode.org). |
| [URI] | IETF RFC 2396:1998, Universal Resource Identifiers (URI): Generic Syntax (http://www.ietf.org) |
| [URN] | IETF RFC 2141: 1997, URN Syntax ( http://www.ietf.org/ ) |
2. SCORM Application of the SSP XML Binding
SCORM content developers, who are utilizing the SCORM application profile to the SSP specification, may wish to explicitly describe the state storage requirements associated with the SCOs they create. Explicit state storage requirements may be most useful when content will be exchanged between systems and interoperability is a goal. As described in the SCORM Content Aggregation Model (SCORM CAM), the primary mechanism for interoperable exchange of content is the use of an 1EdTech Content Packaging. This section describes how to encode specific state storage and access requirements for SCOs in XML, using the SSP XML Binding, applied to a SCORM Content Package.
The SSPXML Binding describes an XML representation of the BucketAllocation data type defined in the SSP Information Model. Each set of BucketAllocation information is represented by a single XML element:
<imsssp:bucket>: The <imsssp:bucket> element encapsulates all of the information necessary to describe one of a content object's data bucket storage requirements.
2.1 <bucket> Element
State storage requirements are explicitly defined for a SCO by associating one or more <bucket> elements with the SCO's resource. In the context of a SCORM Content Package, this is accomplished by including <bucket> element(s) within a <resource> element that also has the ADL content package extension attribute "adlcp:scormType" equal to "sco". XML Namespace: http://www.imsglobal.org/xsd/imsssp
XML Namespace Prefix: imsssp
XML Binding Representation: <bucket>
Data Type: The <bucket> element is a parent element. Parent elements have no values associated with them. Parent elements act as "containers" for other elements and attributes. The <bucket> element contains the following elements and attributes: Attributes:
- bucketID (required) - The unique identifier associated with this data bucket.
XML Data Type: xs:anyURI
Note: The underlying date type for bucketID is GUID. Since an empty string does not provide sufficient semantic information to uniquely identify a bucket, the bucketID attribute cannot be empty and cannot contain all white space characters (which could be transcribed as an empty string by an XML parser).
Note: Although the data type for the bucketID is a unique identifier, the data type does not imply that bucketIDs must be unique across all <bucket> elements within a content package, but only unique within the scope the bucket will be accessed. For a given SCO resource, all of its bucketIDs must be unique to ensure unambiguous resolution during SSP method invocations. Two or more SCO resources may declare use of a bucket with the same bucketID.
- bucketType (optional) - Describes data type or organization of the information to be stored in this data bucket.
XML Data Type: xs:anyURI
Note: The underlying date type for bucketType is GUID. Since an empty string does not provide sufficient semantic information to uniquely identify the type of a bucket, the bucketType attribute cannot be empty and cannot contain all white space characters (which could be transcribed as an empty string by an XML parser).
- persistence (optional, default value = learner) - Describes the LMS's persistence requirements for this data bucket.
XML Data Type: xs:token. The following is a listing of the vocabulary tokens to be used for the persistence attribute:
Multiplicity: Occurs 0 or more times for each <resource> within an 1EdTech content package, when that <resource> also has the ADL content package extension attribute "adlcp:scormType" equal to "sco".
<resources>
<resource identifier="R_A1" type="webcontent" adlcp:scormType="sco" href="sco1.html">
<file href="sco1.html"/>
<imsssp:bucket bucketID="bucket1" persistence="course">
<imsssp:size requested="32768"/>
</imsssp:bucket>
</resource>
<resource identifier="R_A2" type="webcontent" adlcp:scormType="asset" href="pics\distress_sigs_add.jpg">
<file href="pics\distress_sigs_add.jpg"/>
</resource>
<resources>
2.2 <size> Element
State storage requirements for a bucket are defined in terms of a requested size, a minimum size, and an indication if the bucket is reducible. In the context of a SCORM Content Package, this is accomplished by including a <size> element within a <bucket> element XML Namespace: http://www.imsglobal.org/xsd/imsssp
XML Namespace Prefix: imsssp
XML Binding Representation: <size>
Data Type: The <size> element is a parent element. Parent elements have no values associated with them. Parent elements act as "containers" for other elements and attributes. The <size> element contains the following elements and attributes:
- minimum (optional) - Describes the minimum bucket size the content object will accept.
XML Data Type: xs: nonNegativeInteger
Note: The size of data buckets supported by SCORM must be an even number because the contents of data buckets will be communicated across the SCORM API. The contents will be encoded as an ECMAScript characterstring (see sub-section 4.1.1), which is a sequence of two byte (Unicode) characters.
- requested (required) - Describes the content object's desired bucket size.
XML Data Type: xs: nonNegativeInteger
Note: The size of data buckets supported by SCORM must be an even number because the contents of data buckets will be communicated across the SCORM API. The contents will be encoded as an ECMAScript characterstring (see sub-section 4.1.1), which is a sequence of two byte (Unicode) characters.
- reducible (optional, default value = false) - Identifies if the content object can accept a 'reduced' (minimum) sized bucket.
XML Data Type: xs:boolean
Multiplicity: Occurs exactly 1 time for each <bucket> element within an 1EdTech content package.
<resources>
<resource identifier="R_A3" type="webcontent" adlcp:scormType="sco" href="sco2.html">
<file href="sco2.html"/>
<imsssp:bucket bucketID="bucket2" bucketType="SIM:A9">
<imsssp:size requested="524288" minimum="131072" reducible="true"/>
</imsssp:bucket>
</resource>
<resource identifier="R_A4" type="webcontent" adlcp:scormType="sco" href="sco3.html">
<file href="sco3.html"/>
<imsssp:bucket bucketID="bucket3" bucketType="STATE:S1" persistence="session">
<imsssp:size requested="16384">
</imsssp:bucket>
</resource>
<resources>
3. SSP SCORM Runtime Behavior
One of the primary goals of SCORM is to enable interoperable deployment of content objects between systems. The following sections detail SCORM LMS responsibilities for the various aspects of the SSP conceptual model. Although the responsibilities are derived from the SSP Information Model, the sections that follow are SCORM specific and the behavioral refinements described therein take precedent over similar language found in the 1EdTech SSP Information Model. SCORM LMSs that implement this application profile must exhibit all of the behavior described in the following sections.
3.1 Data Bucket Uniqueness
Learners, within an LMS, will have their own data bucket for a given bucket ID. The LMS must ensure that one and only one bucket (for a given persistence, see section 3.5 below) with a given ID will be created for each learner. Once a bucket with a given ID exists, the state of that bucket will be used to determine the success or failure of subsequent bucket allocation requests.
3.2 Contextualized Data Bucket Access
Data bucket access is defined to be per learner, with no defined interoperable facility for multi-learner buckets. The LMS must ensure that SCOs requesting access to data buckets only gain access to the appropriate learner's data bucket.
3.3 Static Declaration of Data Buckets
Content developers may include explicit data bucket requirements for their SCOs when they package those SCOs. LMSs must be able to consume SCORM Content Packages that include XML declarations of data bucket requirements as described in SCORM Application of the SSP Abstract Binding (section 2).
Prior to launching a given SCO, the LMS must determine the successful allocation (or existence) of all of the SCO's explicitly declared data buckets, for the learner - this becomes the SCO's Managed Bucket.collection At runtime, the SCO will access its Managed Bucket collection through the Bucket Collection Manager Interface (sub-section 4.3).
3.4 Dynamic Declaration of Data Buckets
SCOs may request allocation of data buckets at runtime through the Bucket Collection Manager Interface (sub-section 4.3). Each request will either alter an existing bucket or add a new bucket to the SCO's Managed Bucket collection.
3.5 Persistence of Data Buckets
Each request, whether static or dynamic, for a data bucket allocation is accompanied with a declaration of that bucket's persistence requirement. Once allocated, a data bucket's persistence element will inform the LMS as to how long the bucket must be maintained. For the SSP SCORM Application Profile, LMSs must honor the data bucket's persistence values as defined below:
- session - until the current learner attempt on the SCO ends
- course - until the activity tree containing the SCO is removed from the LMS
- learner - until the learner is removed from the LMS
3.6 Contextualized Access to Data Buckets
Upon launch, a SCO will have a (possibly empty, if no static bucket allocations are defined for the SCO) collection of Managed Buckets. Each time a SCO makes dynamic allocation request, its set of Managed Buckets may be updated. LMSs must ensure that no two SCOs share the same Managed Bucket collection, although two SCOs may have the same buckets (with possibly different success statuses) in their Managed Bucket collection. At runtime a SCO may access its set of Managed Buckets as defined in the Bucket Collection Manager Interface (sub-section 4.3).
3.7 Anonymous Access to Data Buckets
Content developers are not required to include explicit data bucket requirements for their SCOs when they package those SCOs. Further, a SCO may attempt to directly access data buckets it did not first request allocation for - a bucket not in its Managed Bucket collection. In these cases, access to a data bucket must be accompanied with the requested bucket's ID as defined in the Bucket Manager Interface (sub-section 4.4).
4. SCORM Application of the SSP Information Model
The SCORM Run-Time Environment (SCORM RTE) defines an interoperable mechanism for SCOs to communication information to the LMS - the SCORM Run-Time API. It is assumed that once a SCO is launched, it can initiate communication (i.e "Initalize()") and then exchange (i.e., "GetValue" and "SetValue()") information with an LMS. All communication across the API is initiated by the SCO. In other words, the communication is always initiated in one direction, from the SCO to the LMS. The LMS cannot invoke any functions defined by the SCO;. there are currently no supported mechanisms for LMSs to initiate calls to functions implemented by a SCO.
The SSP Information Model defines a data model (buckets) and the means to access that data model (abstract API). Binding these to SCORM requires an additional level of indirection - SCORM will not directly bind to the SSP abstract API. Since the defined communication mechanism in SCORM is the Run-Time API, all operations defined in the SSP abstract API must be bound, through dot-notation, to the Run-Time API. All of the dot-notation bound names described in the following sections start with "ssp"; this signals to LMSs that these elements are part of the SCORM Application Profile to SSP. LMSs that do not implement this Application Profile will not understand the SSP dot-notation bound elements and return the appropriate error code - either 401, Undefined Data Model Element; or, 402, Unimplemented Data Model Element.
The table below enumerates the interfaces and methods defined in the SSP Information Model and their corresponding dot-notation bound SCORM Run-Time API calls.
| Bucket Collection Manager (including contextual access) | ||
|---|---|---|
| SSP Operation | SCORM API Operation | Dot-Notation Binding |
| allocate(bucketAllocation) | SetValue() | ssp.allocate (with {ID=<GUID>}{minimum=<min>} {requested=<req>}{reducible=<reduce>} {type=<GUID>}{persistence=<persist>} delimiters) |
| getAllocationSuccess() | GetValue() | ssp.n.allocation_success |
| appendData(data) | SetValue() | ssp.n.data |
| getData() | GetValue() | ssp.n.data |
| getDataOffset(offset, size) | GetValue() | ssp.n.data.{offset=<offset>}{size=<size>} |
| setData(data) | SetValue() | ssp.n.data |
| setDataOffset(data, offset) | SetValue() | ssp.n.data (with {offset=<offset>} delimiter) |
| getState() | GetValue() | ssp.n.bucket_state |
| getBucketsIDs1 | GetValue() | ssp._count ssp.n.bucket_id |
|
1
|
4.1 Binding the SSP Abstract API to Dot-notation
4.1.1 Data Type
All data model element names are bound to an ECMAScript characterstring using a dot-notation (e.g., ssp.data). During SetValue() method calls, all values used for setting the data model element are bound as ECMAScript characterstrings. The ECMAScript standard supports and is in conformance with the Unicode Standard (Unicode: Version 2.1 or later). SCOs and LMSs need to be aware that since these characterstrings are Unicode encoded they may include Unicode escape sequences. When dealing with any data that may be rendered in the browser, SCOs must be aware of the level of support for the Unicode in the different browsers and versions of browsers.
All data communicated across the SCORM API is also bound to an ECMAScript characterstring. Each character in the characterstring is represented as two bytes. For this reason the size of data buckets supported by SCORM must be an even size, and requests for bucket access (getData, getDataOffset, setData, setDataOffset, appendData) must be given or provided in an even number of octets.
4.1.2 SCORM Extension Error Conditions
Due to the nature of the SSP Information Model, it defines error conditions to cover exception scenarios that may occur within a system that implements the SSP Abstract API. Because there is no mechanism, defined by IEEE ECMAScript API for Content to Runtime Services Communication Standard (IEEE API), to permit extension error codes to be set by an API Instance, this application profile will define recommended diagnostic information related to several SSP error conditions. The SSP error conditions are listed in the following sections. If any of these error conditions are encountered, API Instance shall behave as follows:
- Set the error code to "301" (for GetValue() failures) and return an empty string (""), or "351" (for SetValue() failures) and return "false".
- If a SCO requests more information about the error encountered (GetDiagnostic()), it is recommended that the LMS return information detailing the error conditions that follow.
4.1.2.1 Bucket Does Not Exist
The Bucket Does Not Exist error condition indicates that a SCO attempted to access a data bucket that has not been allocated for the learner. This error condition typically occurs during anonymous bucket access where the bucket is specified using a bucketID delimiter. The Bucket Does Not Exist error condition should be used by an API Instance if access to a bucket that has not been allocated for the learner is requested.
If a bucket access request retrieves (GetValue()) data, the API Instance shall set the error code to "301" and return an empty characterstring (""). This error condition can only happen if the conceptual communication state is "Running" (see SCORM RTE Book). If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the requested bucket does not exist, such as, "The requested bucket does not exist".
If a bucket access request stores (SetValue()) data, the API Instance shall set the error code to "351" and return "false". This error condition can only happen if the conceptual communication state is "Running". If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the requested bucket does not exist, such as, "The requested bucket does not exist". Example:
GetValue("ssp.data.{bucketID=foobar}{offset=1025}");
SetValue("ssp.data", "{bucketID=foobar}Hello World");
In both examples, it is assumed that the bucket "foobar" does not exist for the learner.
4.1.2.2 Bucket Improperly Declared
The Bucket Improperly Declared error condition indicates that a SCO attempted to access a data bucket after an allocation request (either static or dynamic) failed - Success Status for the indicated bucket is failure. This error condition may occur during any bucket access, either contextual or anonymous. The Bucket Improperly Declared error condition should be used by an API Instance if access is requested to a bucket whose allocation request (for the SCO) has failed.
If a bucket access request retrieves (GetValue()) data, the API Instance shall set the error code to "301" and return an empty characterstring (""). This error condition can only happen if the conceptual communication state is "Running". If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the requested bucket was improperly declared, such as, "The requested bucket was improperly declared".
If a bucket access request stores (SetValue()) data, the API Instance shall set the error code to "351" and return "false". This error condition can only happen if the conceptual communication state is "Running". If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the requested bucket was improperly declared, such as, "The requested bucket was improperly declared". Example:
GetValue("ssp.data.{bucketID=foobar}{offset=1025}");
SetValue("ssp.data", "{bucketID=foobar}Hello World");
Assume that bucket "foobar" already exists for the learner and then SCO A attempts to allocate bucket "foobar" with different attributes than those used in the original allocation. If SCO A attempts to make the calls above, the LMS prevents SCO A from accessing or altering the contents of bucket "foobar", since the SCO does not 'know' the existing bucket's characteristics.
4.1.2.3 Offset Exceeds Bucket Size
The Offset Exceeds Bucket Size error condition indicates that a SCO attempted to access a data bucket using an offset that exceeds the total size of the bucket. This error condition may occur during contextual or anonymous bucket access where an offset is provided. The Offset Exceeds Bucket Size error condition should be used by an API Instance if the provided offset exceeds the bucket's total size.
If a bucket access request retrieves (GetValue()) data, the API Instance shall set the error code to "301" and return an empty characterstring (""). This error condition can only happen if the conceptual communication state is "Running". If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the offset exceeds the bucket's size, such as, "The offset exceeds the bucket size".
If a bucket access request stores (SetValue()) data, the API Instance shall set the error code to "351" and return "false". This error condition can only happen if the conceptual communication state is "Running". If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the offset exceeds the bucket's size, such as, "The offset exceeds the bucket size". Example:
GetValue("ssp.data.{bucketID=foobar}{offset=1024}");
SetValue("ssp.0.data", "{offset=1024}Hello World");
In both examples, it is assumed that the buckets have a size of 1000 octets.
4.1.2.4 Bucket Size Exceeded
The Bucket Size Exceeded error condition indicates that a SCO attempted to provide more data than the data bucket can currently hold (exceeds total size). This error condition may occur during contextual or anonymous bucket access where an offset may or may not be provided. The Bucket Size Exceeded error condition should be used by an API Instance if the amount of data being added to the bucket exceeds the total size of the bucket.
If a bucket access request stores (SetValue()) data, the API Instance shall set the error code to "351" and return "false". This error condition can only happen if the conceptual communication state is "Running". If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the bucket size has been exceeded, such as, "Exceeds bucket size". Example:
SetValue("ssp.1.data", "Hello World");
In this example, it is assumed that the bucket only has 10 available octets.
4.1.2.5 Requested Data Exceeds Available Data
The Requested Data Exceeds Available Data condition indicates that a SCO attempted to retrieve more data than the bucket has available. This error condition may occur during contextual or anonymous bucket access, where either a size or an offset (or both) delimiter is used. The Requested Data Exceeds Available Data error condition should be used by an API Instance if the size of the data requested, in combination with an offset and size, exceeds the bucket's available data.
If a bucket access request retrieves (GetValue()) data, the API Instance shall set the error code to "301" and return an empty characterstring (""). This error condition can only happen if the conceptual communication state is "Running". If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the requested data exceeds the bucket's available data, such as, "The requested data exceeds available data". Example:
GetValue("ssp.data.{bucketID=foobar}{offset=1024}");
In this example, it is assumed that the total amount of data in bucket "foobar" is less than 1024 octets.
4.1.2.6 Bucket Not Packed
The Bucket Not Packed error condition indicates that a SCO attempted to set information into the data bucket beyond the current amount of available data. This error condition may occur during either contextual or anonymous bucket access, where an offset delimiter is used. The Bucket Not Packed error condition should be used by an API Instance if the provided offset exceeds the amount of available data in the bucket.
If a bucket access request stores (SetValue()) data, the API Instance shall set the error code to "351" and return "false". This error condition can only happen if the conceptual communication state is "Running". If this error condition is encountered, the conceptual communication state shall remain unchanged ("Running"). If the SCO requests further information about the error (by invoking GetDiagnostic()), it is recommended that the LMS return a characterstring indicating that the bucket was not packed, such as, "The bucket was not packed." Example:
SetValue("ssp.0.data", "{offset=1024}Hello World");
In the example above, it is assumed that the SCO attempted to set the data "Hello World" into the bucket starting at offset 1024, but the bucket only had 512 bytes of available data.
4.1.3 Reserved Delimiters
Due to the nature of the dot-notation binding, some SSP abstract API operations require more information than can be represented in a straightforward way. In these cases, a reserved delimiter has been created to meet the requirements of the dot-notation binding, while conveying the information required to bind to the SSP abstract APIs. These reserved delimiters appear in either the value characterstring used in a SetValue() request or after a final dot (. - as an argument) to a GetValue() request. In the SSP application profile, reserved delimiters will never appear in the characterstring returned from a GetValue() request.
Reserved delimiters are not required to be used. If they do not exist in a given SSP operation invocation, no default value will be assumed. If the delimiters are used, then they must meet the following requirements on placement of the reserved delimiter and the delimiter syntax. Delimiter Syntax Requirements: The delimiter shall be treated as a constant set of characters with no white space permitted. The format of the delimiter shall be:
delimiter ::= { + name + = + value + }
The name represents the identifier of the delimiter. The name is represented by a set of reserved tokens in the SCORM SSP Application Profile:
- bucketID: (GUID) - Identifies a specific data bucket for anonymous access.
The bucketID must be represented as a valid URI as per RFC 2396 [URI], with one exception - an empty string ("") is not allowed. It is recommended that the URI be a Universal Resource Name (URN) as per RFC 2141 [URN]. - offset: (non-negative integer) - Identifies the starting (zero-based) octet for the bucket access.
- size: (non-negative integer) - Identifies the number of octets requested.
The following delimiters define a Bucket Allocation:
- bucketed: (GUID) - Identifies the data bucket to be allocated.
The bucketID must be represented as a valid URI as per RFC 2396 [URI], with one exception - an empty string ("") is not allowed. It is recommended that the URI be a Universal Resource Name (URN) as per RFC 2141 [URN]. - requested: (non-negative integer) - Identifies the desired size of the data bucket to be allocated.
- minimum: (non-negative integer) - Identifies the minimum acceptable size of the data bucket to be allocated.
- reducible: (boolean) - Indicates if the size data bucket is 'reducible' to its 'minimum'.
- type: (GUID) - Identifies the type (format) of the data bucket's content.
The bucket type must be represented as a valid URI as per RFC 2396 [URI], with one exception - an empty string ("") is not allowed. It is recommended that the URI be a Universal Resource Name (URN) as per RFC 2141 [URN]. - persistence: (token: one of "learner", "course", "session") - Indicates the expected persistence of the data bucket.
The value indicates the value provided for the named delimiter. The value portion of the delimiter is no permitted to contain Curly braces ({ and }).
Delimiter Placement Requirements: The delimiters are required to be placed in specific positions within the characterstring. In those cases where a combination of delimiters may be used, the order does not matter. Where more than one delimiter may appear, the delimiters shall be concatenated together with no white space permitted between the delimiters. For example:
{offset=1024}{size=16}
When a delimiter is used within a SetValue(), no white space or other characters are permitted prior to the first delimiter identified in the characterstring. When a delimiter is used within a GetValue(), the data model element should followed with a dot ("."), and no white space or other characters are permitted prior to the first delimiter.
4.2 SCORM Dot-Notation
The following sections define the requirements for implementation of the SCORM SSP Application Profile. Each SSP abstract API operation is presented in a new section. Each section describes the requirements for invoking that abstract API operation across the SCORM API. These requirements apply to both LMS and SCO implementations. Some requirements impact LMS implementations, some impact SCO implementations and some impact both LMS and SCO implementations.
4.2.1 <dot-notation characterstring representation of the data model element>
Data Element Implementation Requirements: This section of the table defines the data model element implementation requirements. This section outlines those requirements about the data type that both and LMS and SCO shall adhere to. The section of the table is broken up into three sub-sections Data Type, Value Space and Format.
Data Type: Describes the specific data type for the data model, if one exists.
Value Space: Represents the space of values that can be held by the data type.
Format: Describes any format restrictions placed on the value for the data type.
API Implementation Requirements:
GetValue(): This section outlines the specific behaviors that an LMS shall adhere to when processing GetValue() requests for the specified data model element. This section also outlines the error conditions that could occur using the specified data model element with a GetValue() request.
SetValue(): This section outlines the specific behaviors that an LMS shall adhere to when processing SetValue() requests for the specified data model element. This section also outlines the error conditions that could occur using the specified data model element with a SetValue() request.
Additional Behavior Requirements:
- This section outlines any additional behavior requirements that are specific to the data model element.
This section provides examples of valid API method calls using the data model element.
4.3 Bucket Collection Manager Interface
The LMS shall manage the set of data buckets that are either statically (through XML applied to a SCORM Content Package) or dynamically (through an ssp.allocate() operation), allocated for a given SCO; this is equivalent to the SSP Managed Bucket collection. The Managed Bucket collection and the Bucket Collection Manager Interface form the foundation for contextualized access to data buckets for a given SCO. In the SCORM Application Profile to SSP, access to the Managed Bucket collection is done through a packed array with a zero-based index. Contextual access to all operations of the SSP Bucket Collection Manager Interface and Bucket Manger Interface do not utilize data bucket GUIDs. Instead, an index of the data bucket's corresponding Managed Bucket is used.
4.3.1 ssp._count
The _count keyword describes the current number of data buckets being managed for the SCO. The total number of Managed Buckets currently being managed by the LMS shall be returned.
Data Element Implementation Requirements:
Data Type: integer
Value Space: Non-negative integer
Format: None.
- This element is mandatory and shall be implemented by the LMS as read-only.
- If the LMS receives a request to get the ssp._count value prior to any data bucket allocation requests, then the LMS shall adhere to the requirements listed below for API Implementation Requirements.
- The element is required to be implemented by an LMS as read-only. The SCO is only permitted to retrieve the value of the ssp._count data model element.
API Implementation Requirements:
- The LMS shall return the number of Managed Buckets currently stored by the LMS and set the error code to "0" No error.
- If no static or dynamic data bucket allocations have been made by or for the SCO, then the LMS shall return "0" (no managed buckets) and set the error code to "0" No Error.
SetValue(): If the SCO invokes a SetValue() request to set the ssp._count, then the LMS shall set the error code to "404" Data Model Element Is Read Only and return "false".
4.3.2 ssp.allocate
This data model element is used by a SCO to request allocation of a data bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The format of the characterstring shall consist of the following delimiters:
- {bucketID=<GUID>} required.
- {minimum=<nonNegativeInteger>} optional. If the minimum delimiter is included, its value must equal or exceed the value of the requested delimiter.
- {requested=<nonNegativeInteger>} required.
- {reducible=<boolean>} optional. If not included the LMS shall assume the value of false. If the reducible delimiter is included, it has no effect unless the minimum delimiter is also included.
- {persistence=<Persistence>} optional. If not included, the LMS shall assume the value of 'learner'. If the persistence delimiter is included, its value must be one of the following tokens:
- learner The LMS shall persist this bucket until the current learner is removed from the LMS.
- course The LMS shall persist this bucket until the activity tree containing the SCO is removed from the LMS.
- session The LMS shall persist this bucket until the current learner attempt on the SCO (making this request) ends.
- {type=<GUID>} optional. If not included, the LMS shall not assume any value for the bucket's type.
Note: LMSs have no requirements to understand or enforce the value of the type delimiter. It is provided so that SCOs that 'know' about the type may optimize their behavior.
This element is mandatory and shall be implemented by an LMS as write only.
The LMS shall attempt to reserve storage space for the SCO based on the values of the delimiters provided and the defaults for delimiters not provided.
An LMS is not required to "reserve" space in response to allocate() requests, but the LMS is required to respond to a properly formatted allocate() request as defined in LMS Behavior Requirements. In the case where the LMS cannot "reserve" space, for whatever reason, the allocation_success for the bucket will be failure.
Note: Successfully "reserving" space does not mean that the space must be physically allocated; the only requirement is that the space be available when the SCO attempts to write to it. This allows implementations to use various just-in-time allocation methods, should they desire.
If the SCO puts data in the bucket, the LMS shall persist that data as described by the persist delimiter provided upon allocation of the bucket.
The LMS has four options for how much space to assign, corresponding to the values of requested, minimum, and reducible provided upon allocation of the bucket:
1. If reducible = false and the LMS has sufficient storage to provide the requested amount of space, the requested amount of storage is assigned.
2. If reducible = true and the LMS does have sufficient storage to provide the requested amount of space, the requested amount of storage is assigned.
3. If reducible = true and the LMS does not have sufficient storage to provide the requested amount of space, but does have sufficient storage available for the reduced amount, the reduced amount of storage is assigned.
4. If none of the above cases are true, the LMS does not provide any space for the bucket.
If the value of the bucketID delimiter matches the identifier of a bucket that already exists for the learner and the specified values for reducible, minimum, requested, persistence, and type delimiters all match those associated with the existing bucket (supplied in the original allocation request), the LMS shall not allocate a new bucket. Rather, the SCO shall be given access to the bucket that already exists and the Success Status of the current allocation request shall match the Success Status of the original request. In addition, the requested bucket becomes a member of the Managed Bucket collection, if it is not already a member.
If the value of the bucketID delimiter matches the identifier of a bucket that already exists for the learner and the specified value of reducible, minimum, requested, persistence, or type delimiters are different than those associated with the existing bucket (supplied in the original allocation request), it is an error. In this case:
- The SCO is not given access to the existing bucket.
- The LMS shall not change the allocation of the existing bucket.
- Any attempted access to the existing bucket by the SCO shall indicate a "Bucket Improperly Declared" error.
- This element is implemented by the LMS as write only. The SCO is only permitted to invoke (SetValue()) this operation.
- All required delimiters must exist in the value string.
- All delimiters included in the value string must be formatted as described in Section 3.1.3 (Reserved Delimiters).
API Implementation Requirements:
GetValue(): If the SCO invokes a GetValue() request to get some value from ssp.allocate, then the LMS shall set the error code to "405" Data Model Element Is Write Only and return an empty string (""). SetValue():
- If the SCO invokes a SetValue() request to allocate a data bucket and any of the provided reserved delimiters do not meet the requirements described above (Data Element Implementation Requirements - format), the LMS returns "false", and the API Instance's error code becomes "406" Data Model Element Type Mismatch. The LMS shall ignore the request.
- If the SCO invokes a SetValue() request to allocate a data bucket and all of the provided reserved delimiters meet the requirements described above (Data Element Implementation Requirements - format), the LMS returns "true", and the API Instance's error code becomes "0" No Error. A SCO can determine the success of the bucket allocation by calling GetValue("ssp.n.allocation_success") with the appropriate index.
Example: SetValue("ssp.allocate", "{bucketID=foobar}{requested=1024}{minimum=512}{reducible=true}");
SetValue("ssp.allocate", "{bucketID=foobar}{requested=1024}")
4.3.3 ssp.n.id
This data model element is used by a SCO to request the bucket ID of the SCO's nth Managed Bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The format of the characterstring is not specified.
- This element is mandatory and shall be implemented by an LMS as read only.
- The LMS shall provide the bucketID of the SCO's nth Managed Bucket.
- This element is implemented by the LMS as read only. The SCO is only permitted to query (GetValue()) this operation.
API Implementation Requirements:
- The LMS shall return the bucketID of the SCO's nth Managed Bucket and set the error code to "0" No Error.
- If the SCO invokes a GetValue() request to get the bucketID of the SCO's nth Managed Bucket and the index (n) exceeds the number of Managed Buckets associated with this SCO, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to the SCORM RTE Book: Section 3.1.7.6.4 Data Model Collection Element Request Out Of Range for further recommendations on processing this request.
SetValue(): If the SCO invokes a SetValue() request to set the ssp.n.ID, then the LMS shall set the error code to "404" Data Model Element Is Read Only and return "false".
4.3.4 ssp.n.allocation_success
This data model element is used by a SCO to request the allocation status (Success Status) of the SCO's nth Managed Bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The format of the characterstring must be one of the following tokens:
- failure - the allocation request for the nth Managed Bucket failed. No access to that bucket will be permitted.
- minimum - the allocation request for the nth Managed Bucket succeeded, but its available size was reduced to the minimum requested size.
- requested - the allocation request for the nth Managed Bucket succeeded for its requested size.
- This element is mandatory and shall be implemented by an LMS as read only.
- The LMS shall provide the allocation status (Success Status) of the SCO's nth Managed Bucket.
- This element is implemented by the LMS as read only. The SCO is only permitted to query (getValue()) this operation.
API Implementation Requirements:
- If the SCO invokes a GetValue() request to get the allocation status (Success Status) of the SCO's nth Managed Bucket and the index (n) exceeds the number of Managed Buckets associated with this SCO, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to the SCORM RTE Book: Section 3.1.7.6.4 Data Model Collection Element Request Out Of Range for further recommendations on processing this request.
- The LMS shall return the allocation status (Success Status) of the SCO's nth Managed Bucket and set the error code to "0" No Error. The format of the returned characterstring shall adhere to the Data Element Implementation Requirements described above.
SetValue(): If the SCO invokes a SetValue() request to set the ssp.n.allocation_success, then the LMS shall set the error code to "404" Data Model Element Is Read Only and return "false".
GetValue("ssp.0.allocation_success");
4.3.5 ssp.n.bucket_state
This data model element is used by a SCO to request the current state of the SCO's nth Managed Bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The format of the returned characterstring shall consist of the following delimiters:
- {totalSpace=<nonNegativeInteger>} required. Describes the total space available in the bucket.
- {used=<nonNegativeInteger>} required. Describes the amount of space currently used in the bucket.
- {type=<GUID>} optional. Describes the type of information stored in the bucket. LMSs shall only return a value for the type delimiter if a non-default bucketType is defined for the bucket.
Note: LMSs have no requirements to understand or enforce the value of the type delimiter. It is provided so that SCOs that 'know' about the type may optimize their behavior.
- This element is mandatory and shall be implemented by an LMS as read only.
- The LMS shall provide the current state of the SCO's nth Managed Bucket.
- This element is implemented by the LMS as read only. The SCO is only permitted to query (GetValue()) this operation.
- The SCO is responsible to parse the returned characterstring to extract the delimiters defined above.
API Implementation Requirements:
- The LMS shall return the current state of the SCO's nth Managed Bucket and set the error code to "0" No Error. The format of the returned characterstring shall adhere to the Data Element Implementation Requirements described above.
- If the SCO invokes a GetValue() request to get the current state of the SCO's nth Managed Bucket and the index (n) exceeds the number of Managed Buckets associated with this SCO, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to the SCORM RTE Book: Section 3.1.7.6.4 Data Model Collection Element Request Out Of Range for further recommendations on processing this request.
SetValue(): If the SCO invokes a SetValue() request to set the ssp.n.bucket_state, then the LMS shall set the error code to "404" Data Model Element Is Read Only and return "false".
GetValue("ssp.0.bucket_state");
4.3.6 ssp.n.data.{offset=<nonNegativeInteger>}{size=<nonNegativeInteger>}
This data model element is used by a SCO to request some or all of the information currently stored in the SCO's nth Managed Bucket.
ssp.n.data.{offset=<nonNegativeInteger>}{size=<nonNegativeInteger>}
The following argument delimiters indicate where in the bucket data should be retrieved and how much data (relative to the starting octet) should be retrieved. The argument delimiters are both optional and shall immediately follow the final "." in the parameter of the GetValue() call.
- {offset=<nonNegativeInteger>} optional. Describes the starting offset (zero-based) to begin retrieving data from the bucket. If this delimiter is not provided, the offset is assumed to be zero (0).
Note: The value of the offset delimiter, if provided, must be an even number because information communicated across the Run-Time API is an ECMAScript characterstring and each character in the characterstring is represented as two bytes.
- {size=<nonNegativeInteger>} optional. Describes the amount of data (in octets) to be retrieved from the bucket.
Note: The value of the size delimiter, if provided, must be an even number because information communicated across the Run-Time API is an ECMAScript characterstring and each character in the characterstring is represented as two bytes.
Data Element Implementation Requirements: Data Type: characterstring
Value Space: ISO-10646-1
Format: The returned characterstring will consist of the requested number of octets (based on the specified offset and size delimiters) from the bucket.
- This element is mandatory and shall be implemented by an LMS as read only.
- If no size delimiter arguments are provided, the LMS shall provide all of the data contained in the SCO's nth Managed Bucket beginning at the specified offset.
- This element is implemented by the LMS as read only. The SCO is only permitted to query (GetValue()) this operation.
- The delimiters described above are argument delimiters which must be included in the GetValue() request.
API Implementation Requirements:
- The LMS shall return the number of requested octets (based on the specified offset and size delimiters) from the of the SCO's nth Managed Bucket and set the error code to "0" No Error. The encoding of the returned characterstring shall conform to the ECMA Script standard for String encoding.
- If the SCO invokes a GetValue() request to get data from the SCO's nth Managed Bucket and the index (n) exceeds the number of Managed Buckets associated with this SCO, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to the SCORM RTE Book: Section 3.1.7.6.4 Data Model Collection Element Request Out Of Range for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get data from the SCO's nth Managed Bucket and the SCO's nth Managed Bucket has a Success Status of failure, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to Section 3.1.2 Bucket Improperly Declared for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get data from the SCO's nth Managed Bucket and the provided offset delimiter exceeds the total size of the SCO's nth Managed Bucket, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to Section 3.1.2 Offset Exceeds Bucket Size for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get data from the SCO's nth Managed Bucket and the combination of the provided offset delimiter and the provided size delimiter exceeds the SCO's nth Managed Bucket available data, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to Section 3.1.2 Requested Data Exceeds Available Data for further recommendations on processing this request.
SetValue(): If the SCO invokes a SetValue() request to set the ssp.n.data, then the LMS shall enforce the behavior described in the next table entry.
Example: GetValue("ssp.0.data");
GetValue("ssp.0.data.{offset=1024}{size=512}");
GetValue("ssp.0.data.{offset=2048}");
4.3.7 ssp.n.data
This data model element is used by a SCO to set some or all of the information currently stored in the SCO's nth Managed Bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The format of the characterstring may include the following delimiters:
- {offset=<nonNegativeInteger>} optional. Describes the starting offset (zero-based) to begin storing data into the bucket. If this delimiter is provided, the data will overwrite any existing data in the bucket starting at the provided offset. Data currently stored in the bucket that is either before or after the provided data will not be affected. If this delimiter is not provided, no offset is assumed; the data will overwrite all existing data in the bucket.
Note: The value of the offset delimiter, if provided, must be an even number because information communicated across the Run-Time API is an ECMAScript characterstring and each character in the characterstring is represented as two bytes.
- This element is mandatory and shall be implemented by an LMS as write only.
- If no offset delimiter is provided, the LMS replace all of the data contained in the SCO's nth Managed Bucket.
- This element is implemented by the LMS as write only. The SCO is only permitted to invoke (SetValue()) this operation.
API Implementation Requirements:
GetValue(): If the SCO invokes a GetValue() on ssp.n.setData, then the LMS shall enforce the behavior described in the previous table entry.
- If the SCO invokes a SetValue() request to set data in the SCO's nth Managed Bucket and the combination of the provided offset delimiter and the provided data does not exceed the SCO's nth Managed Bucket total size, then the LMS shall set the error code to "0" No Error and returns "true". The LMS will assume the provided data is conformant to the ECMA Script standard for String encoding.
- If the SCO invokes a SetValue() request to set data in the SCO's nth Managed Bucket and the index (n) exceeds the number of Managed Buckets associated with this SCO, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to the SCORM RTE Book: Section 3.1.7.6.4 Data Model Collection Element Request Out Of Range for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the SCO's nth Managed Bucket and the SCO's nth Managed Bucket has a Success Status of failure, then the LMS shall set the error code to "351"General Set Failure and returns "false". Refer to section 3.1.2 Bucket Improperly Declared for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the SCO's nth Managed Bucket and the provided offset delimiter exceeds the total size of the SCO's nth Managed Bucket, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Offset Exceeds Bucket Size for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the SCO's nth Managed Bucket and the provided offset delimiter exceeds the available size of the SCO's nth Managed Bucket, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Not Packed for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the SCO's nth Managed Bucket and the combination of the provided offset delimiter and the provided data exceeds the SCO's nth Managed Bucket total size, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Size Exceeded for further recommendations on processing this request.
Example: SetValue("ssp.0.data", "Hello World");
SetValue("ssp.0.data", "{offset=16}Hello World");
4.3.8 ssp.n.appendData
This data model element is used by a SCO to append information to what is currently stored in the SCO's nth Managed Bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: n/a
- This element is mandatory and shall be implemented by an LMS as write only.
- The provided data will be appended to the bucket's existing data, provided the bucket's total space is not exceeded.
- This element is implemented by the LMS as write only. The SCO is only permitted to invoke (SetValue()) this operation.
API Implementation Requirements:
GetValue(): If the SCO invokes a GetValue() on ssp.n.appendData, then the LMS shall set the error code to "405" Data Model Element Is Write Only and return an empty string ("").
- If the SCO invokes a SetValue() request to append data to the SCO's nth Managed Bucket and the index (n) exceeds the number of Managed Buckets associated with this SCO, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to the SCORM RTE Book: Section 3.1.7.6.4 Data Model Collection Element Request Out Of Range for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to append data to the SCO's nth Managed Bucket and the SCO's nth Managed Bucket has a Success Status of failure, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Improperly Declared for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to append data to the SCO's nth Managed Bucket and the combination of the bucket's existing data and the provided data exceeds the SCO's nth Managed Bucket total size, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Size Exceeded for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to append data to the SCO's nth Managed Bucket and combination of existing and the provided data does not exceed the SCO's nth Managed Bucket total size, then the LMS shall set the error code to "0" No Error and returns "true". The LMS will assume the provided data is conformant to the ECMA Script standard for String encoding.
SetValue("ssp.0.appendData", "Hello World");
4.4 Bucket Manager Interface
SCOs are also able to make anonymous access to buckets they know the IDs of. This is done through the Bucket Manger Interface, described below.
4.4.1 ssp.bucket_state
This data model element is used by a SCO to request the current state of the specified bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The format of the required bucketID delimiter shall be:
- {bucketID=<GUID>} required. Identifies the target bucket. The format of the returned characterstring shall consist of the following delimiters:
- {totalSpace=<nonNegativeInteger>} required. Describes the total space available in the bucket.
- {used=<nonNegativeInteger>} required. Describes the amount of space currently used in the bucket.
- {type=<GUID>} optional. Describes the type of information stored in the bucket. LMSs shall only return a value for the type delimiter if a non-default bucketType is defined for the bucket.
Note: LMSs have no requirements to understand or enforce the value of the type delimiter. It is provided so that SCOs that 'know' about the type may optimize their behavior.
- This element is mandatory and shall be implemented by an LMS as read only.
- The LMS shall provide the current state of the SCO's specified bucket.
- This element is implemented by the LMS as read only. The SCO is only permitted to query (getValue()) this operation.
API Implementation Requirements:
- The LMS shall return the current state of the specified bucket and set the error code to "0" No Error. The format of the returned characterstring shall adhere to the Data Element Implementation Requirements described above.
- If the SCO invokes a GetValue() request to get the current state of the specified bucket and does not include a bucketID delimiter, then the LMS shall set the error code to "301" General Get Failure and returns "false". Refer to Section 3.1.2 Bucket Does Not Exist for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get the current state of the specified bucket and the bucket specified by the bucketID delimiter does not exist for the learner, then the LMS shall set the error code to "301" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Does Not Exist for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get the current state of the specified bucket and that bucket is one of the SCO's Managed Buckets with a Success Status of failure, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to Section 3.1.2 Bucket Improperly Declared for further recommendations on processing this request.
SetValue(): If the SCO invokes a SetValue() request to set the ssp.bucket_state, then the LMS shall set the error code to "404" Data Model Element Is Read Only and return "false".
GetValue("ssp.bucket_state.{bucketID=foobar}");
4.4.2 ssp.data.{bucketID=<GUID>}{offset=<nonNegativeInteger>}{size=<nonNegativeInteger>}
This data model element is used by a SCO to request some or all of the information currently stored in the specified bucket.
ssp.data.{bucketID=<GUID>}{offset=<nonNegativeInteger>}{size=<nonNegativeInteger>}
The following argument delimiters indicate where in the bucket data should be retrieved and how much data (relative to the starting octet) should be retrieved. The argument delimiters are both optional and shall immediately follow the final "." in the parameter of the GetValue() call.
- {bucketID=<GUID>} required. Identifies the target bucket.
- {offset=<nonNegativeInteger>} optional. Describes the starting offset (zero-based) to begin retrieving data from the bucket. If this delimiter is not provided, the offset is assumed to be zero (0).
Note: The value of the offset delimiter, if provided, must be an even number because information communicated across the Run-Time API is an ECMAScript characterstring and each character in the characterstring is represented as two bytes.
- {size=<nonNegativeInteger>} optional. Describes the amount of data (in octets) to be retrieved from the bucket.
Note: The value of the size delimiter, if provided, must be an even number because information communicated across the Run-Time API is an ECMAScript characterstring and each character in the characterstring is represented as two bytes.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The returned characterstring will consist of the requested number of octets (based on the specified offset and size delimiters) from the bucket.
- This element is mandatory and shall be implemented by an LMS as read only.
- If no size delimiter arguments are provided, the LMS shall provide all of the data contained in the specified bucket beginning at the specified offset.
- This element is implemented by the LMS as read only. The SCO is only permitted to query (GetValue()) this operation.
- The delimiters described above are argument delimiters which must be included in the GetValue() request.
API Implementation Requirements:
- The LMS shall return the number of requested octets (based on the specified offset and size delimiters) from the specified bucket and set the error code to "0" No Error. The encoding of the returned characterstring shall conform to the ECMA Script standard for String encoding.
- If the SCO invokes a GetValue() request to get data from the specified bucket and does not include a bucketID delimiter, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to Section 3.1.2 Bucket Does Not Exist for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get data from the specified bucket and the bucket specified by the bucketID delimiter does not exist for the learner, then the LMS shall set the error code to "301" General Set Failure and return an empty string (""). Refer to Section 3.1.2 Bucket Does Not Exist for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get data from the specified bucket and that bucket is one of the SCO's Managed Buckets with a Success Status of failure, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to Section 3.1.2 Bucket Improperly Declared for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get data from the specified bucket and the provided offset delimiter exceeds the total size of the specified bucket, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to Section 3.1.2 Offset Exceeds Bucket Size for further recommendations on processing this request.
- If the SCO invokes a GetValue() request to get data from the specified bucket and the combination of the provided offset delimiter and the provided size delimiter exceeds the specified bucket's available data, then the LMS shall set the error code to "301" General Get Failure and return an empty string (""). Refer to Section 3.1.2 Requested Data Exceeds Available Data for further recommendations on processing this request.
SetValue(): If the SCO invokes a SetValue() request to set the ssp.data, then the LMS shall enforce the behavior described in the next table entry.
Example: GetValue("ssp.data.{bucketID=foobar}");
GetValue("ssp.data.{bucketID=foobar}{offset=1024}{size=512}");
GetValue("ssp.data.{bucketID=foobar}{size=512}");
4.4.3 ssp.data
This data model element is used by a SCO to set some or all of the information currently stored in the specified bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The format of the required bucketID delimiter shall be:
The format of the characterstring may include the following delimiters:
- {offset=<nonNegativeInteger>} optional. Describes the starting offset (zero-based) to begin storing data into the bucket. If this delimiter is provided, the data will overwrite any existing data in the bucket starting at the provided offset. Data currently stored in the bucket that is either before or after the provided data will not be affected. If this delimiter is not provided, no offset is assumed; the data will overwrite all existing data in the bucket.
Note: The value of the offset delimiter, if provided, must be an even number because information communicated across the Run-Time API is an ECMAScript characterstring and each character in the characterstring is represented as two bytes.
- This element is mandatory and shall be implemented by an LMS as write only.
- If no offset delimiter is provided, the LMS replace (overwrite) all of the data contained in the specified bucket.
- This element is implemented by the LMS as write only. The SCO is only permitted to invoke (SetValue()) this operation.
API Implementation Requirements:
GetValue(): If the SCO invokes a GetValue() on ssp.data, then the LMS shall enforce the behavior described in the previous table entry.
- If the SCO invokes a SetValue() request to set data in the specified bucket and the combination of the provided offset delimiter and the provided data does not exceed the specified bucket's total size, then the LMS shall set the error code to "0" No Error and returns "true". The LMS will assume the provided data is conformant to the ECMA Script standard for String encoding.
- If the SCO invokes a SetValue() request to set data in the specified bucket and does not include a bucketID delimiter, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to 3.1.2 Bucket Does Not Exist for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the specified bucket and the bucket specified by the bucketID delimiter does not exist for the learner, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Does Not Exist for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the specified bucket and that bucket is one of the SCO's Managed Buckets with a Success Status of failure, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Improperly Declared for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the specified bucket and the provided offset delimiter exceeds the total size of the specified bucket, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Offset Exceeds Bucket Size for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the specified bucket and the provided offset delimiter exceeds the available size of the specified bucket, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Not Packed for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to set data in the specified bucket and the combination of the provided offset delimiter and the provided data exceeds the specified bucket's total size, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Size Exceeded for further recommendations on processing this request.
Example: SetValue("ssp.data", "{bucketID=foobar}Hello World");
SetValue("ssp.data", "{bucketID=foobar}{offset=16}Hello World");
4.4.4 ssp.appendData
This data model element is used by a SCO to append information to what is currently stored in the specified bucket.
Data Element Implementation Requirements:
Data Type: characterstring
Value Space: ISO-10646-1
Format: The format of the required bucketID delimiter shall be:
- This element is mandatory and shall be implemented by an LMS as write-only.
- The provided data will be appended to the bucket's existing data, provided the bucket's total space is not exceeded.
- This element is implemented by the LMS as write-only. The SCO is only permitted to invoke (SetValue()) this operation.
API Implementation Requirements:
GetValue(): If the SCO invokes a GetValue() on ssp.appendData, then the LMS shall set the error code to "405" Data Model Element Is Write Only and return an empty string ("").
- If the SCO invokes a SetValue() request to append data to the specified bucket and combination of existing and the provided data does not exceed the specified bucket's total size, then the LMS shall set the error code to "0" No Error and returns "true". The LMS will assume the provided data is conformant to the ECMA Script standard for String encoding.
- If the SCO invokes a SetValue() request to append data in the specified bucket and does not include a bucketID delimiter, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Does Not Exist for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to append data in the specified bucket and the bucket specified by the bucketID delimiter does not exist for the learner, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Does Not Exist for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to append data to the specified bucket and that bucket is one of the SCO's Managed Buckets with a Success Status of failure, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Improperly Declared for further recommendations on processing this request.
- If the SCO invokes a SetValue() request to append data to the specified bucket and the combination of the bucket's existing data and the provided data exceeds the specified bucket's total size, then the LMS shall set the error code to "351" General Set Failure and returns "false". Refer to Section 3.1.2 Bucket Size Exceeded for further recommendations on processing this request.
Example: SetValue("ssp.appendData", "{bucketID=foobar}Hello World");
About This Document
| Title | Shareable State Persistence SCORM® Application Profile |
| Editor | Angelo Panar (ADL), Alex Jackl (1EdTech), Brendon Towle (Thomson NETg) |
| Team Co-Lead | Robert Todd (DigitalThink) |
| Version | 1.0 |
| Version Date | 18 June 2004 |
| Status | Final Specification |
| Summary | This document describes the SCORM Application Profile for Shareable State Persistence |
| Revision Information | June 2004 |
| Purpose | This document has been approved by the 1EdTech Technical Board and is made available for adoption. |
| Document Location | http://www.imsglobal.org/ssp/sspv1p0/imsssp_prflv1p0.html |
| To register any comments or questions about this specification please visit: http://www.imsglobal.org/developers/ims/imsforum/categories.cfm?catid=21 |
List of Contributors
The following individuals contributed to the development of this document:
Revision History
Index
A
API Implementation 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
B
Binding 1
Bucket
element 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22
managed 1
D
Data bucket 1, 2, 3, 4, 5, 6, 7, 8, 9
Data Element Implementation 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
G
GUID 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
I
IEEE 1, 2
1EdTech Specifications
Content Packaging 1, 2
Learner Information Package 1
L
LMS 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22
LMS Behavior 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13
LOM 1
LTSC 1
R
Resource 1, 2, 3, 4
RFC 1, 2
S
SCO 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21
SCO Behavior 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
SCORM 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17
V
Vocabulary 1
W
W3C 1
1EdTech Consortium, Inc. ("1EdTech") is publishing the information contained in this 1EdTech Shareable State Persistence SCORM® Application Profile ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.
1EdTech makes no warranty or representation regarding the accuracy or completeness of the Specification.
This material is provided on an "As Is" and "As Available" basis.
The Specification is at all times subject to change and revision without notice.
It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.
1EdTech would appreciate receiving your comments and suggestions.
Please contact 1EdTech through our website at http://www.imsglobal.org
Please refer to Document Name: 1EdTech Shareable State Persistence SCORM® Application Profile Revision: 18 June 2004
