Impression Connect Content API Reference

Content methods

Use BCF 1.5.2 in JavaScript extensions or Impression.Persistence.dll in C# extensions to transform the XML returned by this API into Impression courseware objects. Both are included in the Connect SDK.

getCourseDescriptionmethod #

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>

getProjectPropertiesmethod #

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 Impression Scribe 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>

getLessonDescriptionmethod #

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>

getLessonInfomethod #

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

getActiveLessonInfomethod #

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 Scribe's lesson editor. If there is no lesson open in the editor, this method returns an empty object.

Errors

None.

getLessonmethod #

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

getStoryboardmethod #

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>

getCanvasImagemethod #

Renders a Storyboard canvas and returns the filesystem path of the generated image.

Parameters

`lessonid`	(identifier, required) The lesson containing the Storyboard.
`sbid`	(identifier, required) The Storyboard whose canvas should be rendered.
`scale`	(integer, optional; default 1) A positive rendering scale. The C# wrapper defaults this value to 2.

Returns

The path of the generated image as plain text. An empty string is returned when the host cannot render the requested canvas.

Errors

400	`lessonid` or `sbid` is not specified.
404	`lessonid` is not found in the project.

Example

getCanvasImage?lessonid=123&sbid=456&scale=2

C:\Users\user\AppData\Local\Temp\Impression\canvas-456.png

newSBIdentifiermethod #

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"

updateLessonmethod #

Replaces the data for the lesson currently being edited in Scribe 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>

""

updateStoryboardmethod #

Replaces the data for one of the storyboards of the lesson currently being edited in Scribe 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>

""

selectSBIDmethod #

Instructs Scribe 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, Scribe 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 Scribe change notifications.

The Connect API includes a mechanism to allow Connect applications to receive notifications when the user performs certain actions within Scribe. 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.

Returns a value when certain actions are performed within Scribe.

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:

Calling the subscribe request as a child of the instance root.
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:

shutdownmessage #

Returned when Scribe closes the current database.

Format

String.

Example

"shutdown"

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

When Scribe 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 changedmessage #

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 Scribe. If the lesson editor is closed, the value of the lessonid element will be the empty string ("").

When a lesson is opened, Scribe 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 changedmessage #

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 Scribe. If a storyboard is not selected, the value of the sbid element will be the empty string ("").

lesson updatedmessage #

Returned when a change is made in Scribe 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 updatedmessage #

Returned when a change is made in Scribe 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 Scribe, 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 Scribe 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 Scribe. 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.

property focus changedmessage #

Returned when the author selects or leaves an editable property in Scribe. Contextual extensions can use this notification to identify the content the author is working on.

Format

JSON string.

Example

{
  "type": "propertyfocuschanged",
  "lessonid": "F61B870D-429B-425F-B004-7084AB502198",
  "sbid": "4CDA10BB-5EDA-489E-9121-7D5AB560C6BA",
  "focus": {
    "hasFocus": true,
    "propertyName": "Question",
    "scope": "storyboard",
    "contentType": "text",
    "childElementId": "",
    "childElementName": "",
    "ppcName": "properties",
    "ppcType": "",
    "ppc": { }
  }
}

When focus is cleared, hasFocus is false and the remaining focus fields are empty. The optional ppc member contains the selected persistence-property container when it is available.

Content API

Content methods

getCourseDescriptionmethod #

Parameters

Returns

Errors

Example

getProjectPropertiesmethod #

Parameters

Returns

Errors

Example

getLessonDescriptionmethod #

Parameters

Returns

Errors

Example

getLessonInfomethod #

Parameters

Returns

Errors

Example

getActiveLessonInfomethod #

Parameters

Returns

Errors

getLessonmethod #

Parameters

Returns

Errors

Example

getStoryboardmethod #

Parameters

Returns

Errors

Example

getCanvasImagemethod #

Parameters

Returns

Errors

Example

newSBIdentifiermethod #

Parameters

Returns

Errors

Example

updateLessonmethod #

Parameters

Returns

Errors

Example

updateStoryboardmethod #

Parameters

Returns

Errors

Example

selectSBIDmethod #

Parameters

Returns

Errors

Example

Subscriptions

subscribemethod #

Parameters

Returns

Errors

Examples

shutdownmessage #

Format

Example

active lesson changedmessage #

Format

Example

active storyboard changedmessage #

Format

Example

lesson updatedmessage #

Format

Example

storyboard updatedmessage #