IMS Logo

IMS Shareable State Persistence SCORM® Application Profile

Version 1.0 Final Specification

Copyright © 2004 IMS Global Learning Consortium, Inc. All Rights Reserved.
The IMS Logo is a trademark of IMS Global Learning Consortium, Inc.
Document Name: IMS 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.

IMS 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 IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2004 IMS Global Learning Consortium. All Rights Reserved.

If you wish to copy or distribute this document, you must complete a valid Registered User license registration with IMS and receive an email from IMS granting the license to distribute the specification. To register, follow the instructions on the IMS website: http://www.imsglobal.org/specificationdownload.cfm.

This document may be copied and furnished to others by Registered Users who have registered on the IMS 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 IMS, except as needed for the purpose of developing IMS specifications, under the auspices of a chartered IMS project group.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/license.html.

The limited permissions granted above are perpetual and will not be revoked by IMS 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 IMS 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 IMS Shareable State Persistence (SSP) Specification. Readers of this document should be familiar with the IMS 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 View of the SSP Conceptual Model

Figure 1.1 SCORM View of the SSP Conceptual Model.
  1. 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.
  2. 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.
  3. 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

ADL
Advanced Distributed Learning
API
Application Program Interface
IEEE
Institute of Electrical and Electronics Engineers
IETF
Internet Engineering Task Force
ISO
International Organization for Standardization
LOM
Learning Object Metadata (usually used in "IEEE LOM")
LTSC
Learning Technology Standards Committee
RFC
Request for Comment (usually used in "IETF RFC xxxx")
SCO
Shareable Content Object
SCORM
Sharable Content Object Reference Model
SSP
IMS Shareable State Persistence Specification
VDEX
IMS Vocabulary Definition Exchange Specification
W3C
World Wide Web Consortium
XML
Extensible Mark-up Language

1.2 References

[SSP, 04a]
IMS Shareable State Persistence Information Model v1.0, A.Jackl, A.Panar, B.Towle, IMS Global Learning Consortium, Inc., June 2004.
[SSP, 04b]
IMS Shareable State Persistence XML Binding v1.0, A.Jackl, B.Towle, IMS Global Learning Consortium, Inc., June 2004.
[SSP, 04c]
IMS Shareable State Persistence Best Practice and Implementation Guide v1.0, A.Jackl, IMS Global Learning 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 IMS Content Packaging to Package Instances of LIP and Other IMS Specifications v1.0, B.Olivier, M.McKell, IMS Global Learning Consortium, Inc., August 2001.
[IMSPLID]
IMS Persistent, Location-Independent, Resource Identifier Implementation Handbook v1.0, M.McKell, IMS Global Learning 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 IMS 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:

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.

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).

Elements:

Multiplicity: Occurs 0 or more times for each <resource> within an IMS content package, when that <resource> also has the ADL content package extension attribute "adlcp:scormType" equal to "sco".

Example:

<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:

Attributes:

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.

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.

Elements:

None

Multiplicity: Occurs exactly 1 time for each <bucket> element within an IMS content package.

Example:

<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 IMS 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:

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.

Table 4.1 Shareable State Persistence Abstract API mapped to SCORM Run-Time API dot-notation.

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
Within SCORM, contextual access to bucket IDs is done in two steps. First, a SCO requests the number of Managed Buckets using ssp._count. Second, a SCO must iterate over the number of Managed Buckets requesting each bucket's ID using ssp.n.bucket_id.

Bucket Manager (anonymous access)
SSP Operation SCORM API Operation Dot-Notation Binding
getData(bucketID)
GetValue()
ssp.data.{bucketID=<GUID>}
getDataOffset(bucketID, offset, size)
GetValue()
ssp.data.{bucketID=<GUID>}{offset=<offset>}{size=<size>}
setData(bucketID, data)
SetValue()
ssp.data
(with {bucketID=<GUID>} delimiter)
setDataOffset(bucketID, data, offset)
SetValue()
ssp.data
(with {offset=<offset>} (with {bucketID=<GUID>} delimiters)
appendData(bucketID, data)
SetValue()
ssp.data
(with {bucketID=<GUID>} delimiter)
getState(bucketID)
GetValue()
ssp.bucket_state.{bucketID=<GUID>}

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:

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:

The following delimiters define a Bucket Allocation:

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

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:

Example:

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

API Implementation Requirements:

GetValue():

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".

Example:

GetValue("ssp._count")

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:

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.

LMS Behavior Requirements:

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:

SCO Behavior Requirements:

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():

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

API Implementation Requirements:

GetValue():

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".

Example:

GetValue("ssp.0.id");

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:

LMS Behavior Requirements:

SCO Behavior Requirements:

API Implementation Requirements:

GetValue():

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".

Example:

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:

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

API Implementation Requirements:

GetValue():

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".

Example:

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.

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.

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

API Implementation Requirements:

GetValue():

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:

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

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.

SetValue():

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

LMS Behavior Requirements:

SCO Behavior Requirements:

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 ("").

SetValue():

Example:

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:

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

API Implementation Requirements:

GetValue():

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".

Example:

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.

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.

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

API Implementation Requirements:

GetValue():

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:

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.

LMS Behavior Requirements:

SCO Behavior Requirements:

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.

SetValue():

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:

LMS Behavior Requirements:

SCO Behavior Requirements:

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 ("").

SetValue():

Example: SetValue("ssp.appendData", "{bucketID=foobar}Hello World");

About This Document

Title
Shareable State Persistence SCORM® Application Profile
Editor
Angelo Panar (ADL), Alex Jackl (IMS), 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 IMS 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:

Name Organization Name Organization
Brandt Dargue
Boeing
Angelo Panar
ADL
Jeff Falls
ADL
Jonathan Poltrack
ADL
Fabrizio Giorgini
GIUNTI
James Simon
Sun Microsystem
Alex Jackl
IMS
Martin Spence
Act E-Learning
Steve Jeyes
CETIS
Robert Todd
DigitalThink
Owen McGrath
UC Berkeley
Brendon Towle
Thomson NETg
Claude Ostyn
Click2learn, Inc.
Edith Wells
Boeing

Revision History

Version No. Release Date Comments
Public Draft 1.0
25 March 2004
First version of the profile document.
a) Made minor editorial changes and corrections.
b) Removed reference to elements <contentScope> and <learnerScope>.
Final Specification 1.0
18 June 2004
Formal Final Release of the specification.

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
IMS 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

P
Profile 1, 2, 3, 4, 5, 6, 7

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

U
URI 1
URN 1

V
Vocabulary 1

W
W3C 1

X
XML 1, 2, 3, 4, 5, 6

 

 

 

IMS Global Learning Consortium, Inc. ("IMS") is publishing the information contained in this IMS Shareable State Persistence SCORM® Application Profile ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

IMS 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.

IMS would appreciate receiving your comments and suggestions.

Please contact IMS through our website at http://www.imsglobal.org

Please refer to Document Name:
IMS Shareable State Persistence SCORM® Application Profile Revision: 18 June 2004