Content methods

You can use the persistence objects to transform XML objects into courseware data objects.  Persistence objects are provided for both Javascript (impression.persistence.js) and C# (Impression.Persistence.Dll)  Refer to the documentation for these two files for more information.

getCourseDescription method

Returns an XML object containing information about the structure of the items in the entire content database.

Parameters

None.

Returns

An <courseDescription>-format XML object containing content database information.

Errors

None.

Example
getCourseDescription

<courseDescription title="Connect Sample">
  <ppc name="properties" />
  <courseMap name="Connect Sample">
    <item lessonid="F86024CB-226C-42EA-BFEA-675514D185E8">
      <item lessonid="F61B870D-429B-425F-B004-7084AB502198" />
      <item lessonid="80A2F5A0-4955-47CC-97C3-A9B3BB4AD92D" />
    </item>
    <item lessonid="A0995CD5-BE51-4986-B58F-A85695CDAADF" />
  </courseMap>
  <lessonDescriptions>
    <lessonDescription
      lessonid="A0995CD5-BE51-4986-B58F-A85695CDAADF"
      title="Scratch Lesson"
      identifier="SCRATCH"
      lessonType="Lesson">
    </lessonDescription>
    <lessonDescription
      lessonid="F86024CB-226C-42EA-BFEA-675514D185E8"
      title="Samples"
      identifier="SAMPLES"
      lessonType="Group">
    </lessonDescription>
...
  </lessonDescriptions>
</courseDescription>

getProjectProperties method

Returns an XML object containing configuration information for the content database.

Parameters

None.

Returns

An <ppc>-format XML object containing configuration information.

The format of the project properties object is not strictly defined—future versions of the Content Creation Tool may move, rename, or remove specific items.  Care should be taken when working with project properties.
Errors

None.

Example
getProjectProperties

<ppc name="ProjectProperties">
  <ppcProp name="export">
    <ppc name="export">
      <stringProp name="DataPath"></stringProp>
      <stringProp name="LessonFilename">lesson.xml</stringProp>
      <intProp name="LessonOptimizeFlags" value="23" />
      <intProp name="LessonXMLOutputFlags" value="704" />
...
  <ppcProp name="media">
    <ppc name="media">
      <stringProp name="AssetImportRights">users</stringProp>
      <colorProp name="AssetPickerBackgroundColor" value="#C0C0C0" />
      <stringProp name="MediaPath">%PROJECT_ROOT%\media</stringProp>
      <stringProp name="ProjectReportPath">%PROJECT_ROOT%\reports</stringProp>
...
    </ppc>
  </ppcProp>
...
</ppc>

getLessonDescription method

Returns an XML object containing information (but not data) for a lesson.

Parameters
lessonid (identifier, required) The lesson to retrieve information for.
Returns

An <lessonDescription>-format XML object containing configuration information.

Errors
400 lessonid parameter is not specified.
404 lessonid not found in the database.
Example
getLessonDescription?lessonid=F61B870D-429B-425F-B004-7084AB502198

<lessonDescription
  lessonid="F61B870D-429B-425F-B004-7084AB502198"
  title="Content and Structure"
  identifier="CONTENT_AND_STRUCTURE"
  lessonType="Lesson">
  <ppc name="properties">
    <stringProp name="LessonModifiedBy">f.bar</stringProp>
    <stringProp name="LessonModifiedDate">3/12/2014 2:51:48 PM</stringProp>
    <intProp name="StoryboardCount" value="137" />
  </ppc>
</lessonDescription>

getLessonInfo method

Returns a JSON object containing non-content information about a lesson.

Parameters
lessonid (identifier, required) The lesson to retrieve information for.
Returns

A JSON object containing lesson information.

Errors
400 lessonid parameter is not specified.
404 lessonid not found in the database.
Example
getLessonInfo?lessonid=F61B870D-429B-425F-B004-7084AB502198

{
  "lessonid": "F61B870D-429B-425F-B004-7084AB502198",
  "exists": true,
  "mediaid": "media-F61B870D-429B-425F-B004-7084AB502198",
  "mediapath": "C:\\Users\\foo\\Desktop\\sample\\media",
  "sbid": "",
  "tokens": {
    "%ADDITIONAL_SOURCE_PATH%": "",
...
  },
  "haswritelock": true,
  "hasreadlock": false,
  "sessionlocks": "EditLesson"
}

getActiveLessonInfo method

Returns a JSON object containing non-content information about the active lesson.

Parameters

None.

Returns

A JSON object containing information about the active lesson.

The active lesson is the lesson that is open in the CCT's lesson editor.  If there is no lesson open in the editor, this method returns an empty object.
Errors

None.

getLesson method

Returns an XML object containing the data for a lesson.

Parameters
lessonid (identifier, required) The lesson to retrieve information for.
optimize (boolean, optional. default true) Specifies whether or not to optimize the returned lesson XML.
format (boolean, optional. default true) Specifies whether or not to format the returned lesson XML.
If either the optimize or the format flags are set to true, the optimizing and formatting options specified in the Export section of the database's project properties are used to modify the lesson before returning it.
Returns

A <lesson>-format XML object containing the lesson data.

If the requested lesson is the active lesson, the lesson data will come from the data currently being edited in the CCT.  If the requested lesson is not the active lesson, the lesson data is pulled from the database.
Errors
400 lessonid parameter is not specified.
404 lessonid not found in the database.
Example
getLesson?lessonid=F61B870D-429B-425F-B004-7084AB502198

<lesson
  lessonid="F61B870D-429B-425F-B004-7084AB502198"
  title="Content and Structure"
  identifier="CONTENT_AND_STRUCTURE"
  documentid="3802b2c3-3290-437a-b728-cc11db97e494">
  <ppc name="properties">
    <stringProp name="ExportedBy">user</stringProp>
    <stringProp name="ExportedDate">3/11/2014 11:47:15 AM</stringProp>
    <intProp name="StoryboardCount" value="137" />
...
  </ppc>
  <maps default="primary">
    <map name="primary">
      <item sbid="e98e9403-ef9e-4aa0-8118-33dc7373a4ee" />
      <item sbid="8BE114F1-1019-4A42-B588-01CF0FB4FF14" />
      <item sbid="82442A77-D6C9-47D8-8449-DDAEA85225D6">
        <item sbid="D6A46981-7F3C-4D3A-B132-279ACBCAFBB9" />
        <item sbid="995D1C27-8BA3-4B1F-9BB3-36B43D7F03DC" />
...
      </item>
    </map>
  </maps>
  <storyboards>
    <storyboard sbid="8BE114F1-1019-4A42-B588-01CF0FB4FF14" 
    title="Multiple-Choice Text Sample Storyboard" 
    identifier="CONTENT_AND_STRUCTURE:01351" 
    type="multiple-choice text" 
    shortid="136">
      <ppc name="properties">
        <stringProp name="BackButtonEnabled">always;</stringProp>
        <stringProp name="CompleteWhen">answerCorrect;</stringProp>
        <stringProp name="NextButtonEnabled">whenComplete;</stringProp>
        <stringProp name="Question">What is the first metasyntactic variable?</stringProp>
        <encProp>PHN0cmluZ1Byb3AgbmFtZT0iQW5zd2VyIj5mb288L3N0cmluZ1Byb3A+</encProp>
        <encProp>PHN0cmluZ1Byb3AgbmFtZT0iRGlzdHJhY3RvcjEiPmJhcjwvc3RyaW5nUHJvcD4=</encProp>
        <encProp>PHN0cmluZ1Byb3AgbmFtZT0iRGlzdHJhY3RvcjIiPmJhejwvc3RyaW5nUHJvcD4=</encProp>
        <encProp>PHN0cmluZ1Byb3AgbmFtZT0iRGlzdHJhY3RvcjMiPmJhdDwvc3RyaW5nUHJvcD4=</encProp>
      </ppc>
    </storyboard>
...
  </storyboards>
</lesson>

getStoryboard method

Returns an XML object containing the data for a storyboard.

Parameters
lessonid (identifier, required) The unique identifier of the lesson containing the storyboard.
sbid (identifier, required) The unique identifier of the storyboard to retrieve the data of.
Returns

A <storyboard>-format XML object containing the storyboard data.

Only storyboards from the active lesson can be retrieved.  If the requested lesson is not the active lesson, or the storyboard is not found in the active lesson, no data will be returned, and a result code of 200 (no error) will be returned.
Errors
400 lessonid parameter is not specified.
404 lessonid not found in the database.
Example
getStoryboard?lessonid=123&sbid=456

<storyboard
  sbid="456"
  title="Overview"
  identifier="CONTENT_AND_STRUCTURE:00559"
  type="placeholder"
  shortid="12">
  <ppc name="properties">
    <stringProp name="BackButtonEnabled">always;</stringProp>
    <stringProp name="CompleteWhen">always;</stringProp>
    <stringProp name="NextButtonEnabled">whenComplete;</stringProp>
    <stringProp name="PlaceholderType">Topic/Subtopic</stringProp>
  </ppc>
</storyboard>

newSBIdentifier method

Returns a string containing a new storyboard identifier.

Parameters
lessonid (identifier, required) The unique identifier of the lesson to base the result on.
sbid (identifier, optional) The unique identifier of the storyboard to base the result on.
Returns

A string containing the new identifier.

This function returns a new value for a storyboard's identifier property.  The identifier is a human-readable code designed to assist in identifying specific storyboards during the production process.  The value returned is based on the identifier template specified in the project properties, and can use information from the lesson and/or the sbid.

The identifier is not the sbid, and is not guaranteed to be unique.  To generate a new sbid, use the newGuid method or another mechanism for generating unique identifiers.

Errors
400 lessonid parameter is not specified.
404 lessonid not found in the database.
Example
newSBIdentifier?lessonid=F61B870D-429B-425F-B004-7084AB502198

"CONTENT_AND_STRUCTURE:01360"

updateLesson method

Replaces the data for the lesson currently being edited in the CCT with the data passed to the method.

Parameters
[postdata] (string, required) A <lesson>-format XML string containing the lesson data.
Before updating the database, this function will remove the tokens persisted properties collection from the lesson's properties collection.  Do not stick any data you wish to preserve in the tokens ppc.
Returns

Nothing.

Errors
400 [postdata] is empty or is not a<lesson>-format XML string.
400 The lessonid value of the [postdata] string is not the unique identifier of the active lesson.
404 The lessonid value of the [postdata] string was not found in the database.
409 The active lesson is not open with write privileges.
Example
updateLesson
<lesson
  lessonid="123"
  title="Sample Lesson"
  identifier="LESSON_123"
...
</lesson>		

""

updateStoryboard method

Replaces the data for one of the storyboards of the lesson currently being edited in the CCT with the data passed to the method.

Parameters
[postdata] (string, required) A <storyboard>-format XML string containing the storyboard data.
lessonid (identifier, required) The unique identifier of the lesson containing the storyboard.
Returns

Nothing.

Errors
400 [postdata] is empty or is not a<storyboard>-format XML string.
400 The lessonid parameter is not the unique identifier of the active lesson.
404 The lessonid parameter value was not found in the database.
409 The active lesson is not open with write privileges.
Example
updateStoryboard?lessonid=123
<storyboard
  sbid="456"
  title="Overview"
  identifier="LESSON_123:00559"
  type="placeholder"
...
</storyboard>		

""

selectSBID method

Instructs the CCT to select a specific storyboard within the active lesson.

Parameters
sbid (identifier, required) The unique identifier of the storyboard to select.
If there is no storyboard in the active lesson with sbid, the CCT will select the map root node of the first map in the lesson.
Returns

Nothing.

Errors
400 The sbid parameter was not specified.
Example
selectSBID?sbid=456

""

Subscriptions

Receive CCT change notifications.

The Connect API includes a mechanism to allow Connect applications to receive notifications when the user performs certain actions within the CCT. This allows application developers to react appropriately when the underlying environment changes.

To receive notifications, Connect applications will issue a subscribe call to the server. When a notifiable action occurs, the call will return and provide specific information about the action.

In general, providing asynchronous notifications to a web client is commonly known as HTTP PUSH, and can be supported in several ways. Connect uses the “long poll” approach for push notifications. With the long poll approach, the HTTP server receives the request from a client, but does not return any response until appropriate. Using the long poll approach means that subscribers must issue the server request asynchronously (or issue the request on a non-UI thread) to avoid locking up the application until the response is received.

The C# managed wrapper uses the HttpWebRequest object’s BeginGetResponse() method to asynchronously handle subscriber notifications. The subscriber.html sample illustrates how to handle notifications in an HTML/Javascript environment.

subscribe method

Returns a value when certain actions are performed within the CCT.

Parameters
[unique identifier] (identifier, required) A unique identifier for the subscribe request.
Returns

Either a string or a JSON object containing information about the action.

Errors
400 subscribe request is insufficiently unique.

IMPORTANT:

The ‘long poll’ approach used by the Connect server requires that each simultaneous subscribe method request have a unique identifier.  If a  subscribe request is issued by a client without a unique idenfier, the request will not be processed by the server until the previous request's TCP sock times out; this occurs approximately 20 seconds after the request has been received.

The subscribe method supports unique identifiers in one of two ways:

  1. Calling the subscribe request as a child of the instance root.
  2. Passing unique querystring data along with the request.
Examples
Subscribe using the instance root (assumes that the call is made from a page accessed from the instance root): 
./subscribe
Subscribe using the instance id: 
/subscribe?instanceid=123
Subscribe using some unique data: 
/subscribe?uniquevalue=[unique value]

The subscribe call can return one of the following values:

shutdown message

Returned when the CCT closes the current database.

Format

String.

Example
"shutdown"

The shutdown message is sent whenever the current database is closed in the CCT.  This can occur:

  • When the CCT application closes.
  • When the user selects a different database.
  • After the user has changed project properties.
  • After the user has made changes using the Lesson/Group editor.
It is strongly recommended that you process shutdown messages.  Even if the shutdown message is generated as part of an action that reloads the current database, the connect server will reset itself.  As a result, all instance information for running applications will be lost.

active lesson changed message

Returned when the active lesson is changed.

Format

JSON string.

Example
{
  "type": "activelessonchanged",
  "lessonid": "F61B870D-429B-425F-B004-7084AB502198"
  "sbid": "4CDA10BB-5EDA-489E-9121-7D5AB560C6BA"
  "mediaid": "media-F61B870D-429B-425F-B004-7084AB502198"
}

The active lesson is the lesson currently open in the lesson editor of the CCT.  If the lesson editor is closed, the value of the lessonid element will be the empty string ("").

When a lesson is opened, the CCT attempts to select the last storyboard edited.  If a storyboard was selected, the value of the sbid element will contain its value.  If the lesson editor is closed, or no storyboard is selected, the value of the sbid element will be the empty string ("").

 Note that the active lesson may be opened with either read-write or read-only permissions.  Use the lesson information object to determine the access rights.

active storyboard changed message

Returned when the active storyboard is changed.

Format

JSON string.

Example
{
  "type": "activestoryboardchanged",
  "sbid": "4CDA10BB-5EDA-489E-9121-7D5AB560C6BA"
}
The active storyboard is the storyboard currently selected in the lesson editor of the CCT.  If a storyboard is not selected, the value of the sbid element will be the empty string ("").

lesson updated message

Returned when a change is made in the CCT to the active lesson that affects the entire lesson.

Format

JSON string.

Example
{
  "type": "lessonupdated",
  "lessonid": "F61B870D-429B-425F-B004-7084AB502198"
}

Not all changes made to a lesson affect the entire lesson.  Most changes made by a user affect only the active storyboard.  Some changes that affect the entire lesson include:

  • Adding a new storyboard.  In this case, the lesson's storyboard collection and (one of) the lesson map(s) are changed.
  • Moving one or more storyboards.  In this case, the lesson's map (or maps) are changed.
  • Importing lesson data.

storyboard updated message

Returned when a change is made in the CCT to the active lesson that affects only the active storyboard.

Format

JSON string.

Example
{
  "type": "storyboardupdated",
  "sbid": "4CDA10BB-5EDA-489E-9121-7D5AB560C6BA"
}
When a user enters text data into a storyboard field in the CCT, each individual keystroke counts as a change, and will cause this notification to occur.  If you plan on updating your client application’s data as changes occur, you may wish to use a timer or other mechanism to coalesce these notifications and only retrieve updates when the changes have “settled down.”
Starting with CCT builds > 3.11.1145, the storyboard updated and lesson updated notifications occur when a Connect application issues an update to the content as well as when the content is manipulated directy by the user in the CCT.  Avoid triggering updates from your Connect application when loading data as the result of an update notification—your program may end up in an infinite loop otherwise.