Overview

The Impression Connect Application Programming Interface (API) is a system designed to allow custom applications to communicate with the Impression Content Creation Tool (CCT) and manipulate data stored in the active content database.

The API is HTTP-based; all API calls are made by calling a web server integrated into the of the CCT. Depending on the method invoked, the API calls will return JSON-formatted strings, XML strings, or plain text data. The CCT supports both HTML-based Connect applications opened in an external browser, and executable applications launched directly from the CCT.

In addtion to the CCT, Connect support requires installation of the Connect Server on each machine that will use Connect applications. The Connect Server setup program is included in this SDK.

Talk Data

Connect includes support for Impression Talk data, a set of tables stored in an Impression content database created to store data for production support and lifecycle applications. See the Talk page for more information.

Data types

The ImpressionConnect API uses the following data types:

identifier A string of up to 50 characters that uniquely identifies an object.  When generated by the API, identifiers are GUIDs created by calling System.Guid.NewGuid().
JSON string Data represented by a string of any size in JSON notation.
XML string Data represented by a string of any size in XML format. Some API methods require a specific XML schema; refer to the method documentation for details.
integer A 32-bit signed integer.
boolean A Boolean true/false.
datetime A date/time string.  Note that the format of the string is parsable by both Javascript and the Microsoft .Net Framework.

Errors and Error Codes

Since the ImpressionConnect API uses HTTP for communication, HTTP status codes are used to indicate success or failure of a call. The following table lists the HTTP status codes that can be returned by the API, along with the status code definition and some common cases that cause these values to be returned.

Code Description
200 (HTTP OK) Method invoked successfully.
400 (HTTP BAD REQUEST) Required method parameters are missing or incorrect.
404 (HTTP NOT FOUND) The data for a specific call is not found in the database. As an example, if the getPost method is called with a postid value that is not present in the database, HTTP 404 will be returned.
405 (HTTP METHOD NOT ALLOWED) A method that must be called with HTTP POST was invoked using HTTP GET.
409 (HTTP CONFLICT) A revision mismatch exists, and the overwrite parameter was not specified, or an attempt was made to update lesson content and there is no write lock on the lesson for the current session.
422 (HTTP UNPROCESSABLE ENTITY) Although well formed,the server was unable to process the request. This can occur if certain conditions are not met or have changed—for example, the database is no longer available or Talk features are not supported in the database.
500 (HTTP INTERNAL SERVER ERROR) An exception occurred during processing.
501 (HTTP NOT IMPLEMENTED) The method does not exist.

Calling the API

All Connect API calls are made using HTTP requests. While the sample applications included in the Connect SDK (and the C# managed wrapper) use an XMLHTTPRequest object, you are free to use any mechanism you like.

All calls are case-sensitive and are relative to the server root. For example, to retrieve the current date/time from the server, use this URL:

http://localhost:[port]/getDate

Although this particular call does not need any additional, some calls require additional parameters. Some parameters must be supplied as part of the querystring; for example, to get the lessoninfo object for lesson “123”, use this URL:

http://localhost:[port]/getLessonInfo?lessonid=123

Other calls may require HTTP POST data. Refer to the API documentation for more information.

The Developer API page included in the SDK allows you to interactively issue API calls and see their results. Use this page to gain a better understanding of the API calls, what they require, and what they return.

The instanceid parameter

Some methods (for example, the getCoreInfo method) require the instanceid parameter.  If this value is not passed to an API method as a querystring argument, the Connect server will attempt to determine the instance from the referring URL.  If you use XMLHTTPRequest objects, the referring URL will be the page that issues the request.  Initial access to the instanceid parameter is noted in the sections on application startup, below.

Connect applications

Defining applications for use in the CCT

Information about the Connect applications available for use is stored in the configuration data (Project Properties) of the content database—specifically, on the Connect tab of the Project Properties dialog. The CCT can launch any number of Connect applications, and multiple Connect applications can be active at the same time.

The Connect tab of the Project Properties dialog allows the user to add, edit, arrange, and delete references to connect applications. Connect applications are available from the Tools menu of both the Groups window and the Lesson Editor, and are displayed in the same top-down order shown in the Project Properties dialog. Each application listed contains the following information:

Caption The caption of the application. The caption is used as the menu item text for the application.
Type

The type of application, either a browser-based application, or an executable application.

If the application is a browser-based application, the CCT will launch the application by crafting an appropriate URL and invoking the ShellExecute function to open the URL with the user’s default web browser.

If the application is an executable, the CCT will launch the application directly, passing appropriate information to the executable via command-line arguments.

Keep application open...

Executable applications only.  If this value is checked, the Connect server will not close the application when a shutdown notification is sent.  If unchecked (default), the application will be closed when the notification is sent.  More information on shutdown and other notifications is available in the subscriptions section of the API: Content page.

Show In

Specifies when the application should be available. Options include:

  • Groups Window (all items). The application will be available from the Tools menu of the Groups window, regardless of the selected item in the Groups treeview.
  • Groups Window (lessons only). The application will be available from the Tools menu of the Groups window, but enabled only when a lesson is selected in the Groups treeview.
  • Lesson Editor. The application will be available from the Tools menu of the Lesson Editor. Note that the lesson may or may not be open for writing.
Application Filename The HTML file or executable filename to launch. This is a tokenized string value; many of the supported tokens (including %PROJECT_ROOT% and %MDB_PATH%) can be used here.
Application ID A unique identifier for the application. By default, the CCT will create a new GUID for this value, but you may change it to any value. The Application ID is used to help filter Talk Post records (see the section on Talk Posts for more information).
In addtion to the Application ID, the Connect server will create an instanceid value that uniquely identifies a specific instance of a Connect application.

Defining local applications

In addition to the Connect applications defined in a content database, you can define applications for global use. These applications will be available for all instances of the CCT in addition to those defined in the database.

The configuration data is stored in a file named impressionconnect.localapps.xml stored in the user's documents directory. The SDK includes an application (ImpressionConnectLSE.EXE) that can be used to edit the list of local applications.

HTML application startup

When an HTML-based application is launched, the URL is of the form:

http://localhost:[port]/[instanceid]/[htmlfilename]

Where

  • [port] is the random port assigned to the instance of the CCT used to launch the application.
  • [instanceid] is a unique identifier for this instance of the application.
  • [htmlfilename] is the filename portion of the detokenized string stored in the “Application Filename” field of the configuration data for the application.

Executable application startup

When an executable application is launched, three parameters are passed to the application as command-line arguments. These are, in order:

  1. [port] The random port assigned to the instance of the CCT used to launch the application.
  2. [instanceid] The unique identifier for this instance of the application.
  3. [hwndparent] The 32-bit handle of the active CCT window at the time the application was launched.

Accessing files via URL

A Connect application may require access to additional files from a number of sources, including:

  • Application supporting files
  • Lesson media files
  • Lesson XML files
  • Shell/RTE files

These files are likely to be located in different, unrelated sections of a user’s filesystem. The Connect server makes these files available via URL through the use of identifiers. Specifically:

  • Application supporting files are accessed relative to the application’s applicationid.That is, if an application with an application id value of “123” needs to load the file “foo.js”, located in the same folder as the application file (as defined in Project Properties), the URL to use would be:
    http://localhost:[port]/123/foo.js
    Alternatively, you can use the instanceid value. This value is also used to construct the initial URL, so from the initial page of an application, you can load foo.js with the URL
    ./foo.js
  • Lesson media files are accessed relative to a lessons’ mediaid value. That is, to load the file “foo.jpg” from a lesson with a media id value of “media-456”, the URL to use would be:
    http://localhost:[port]/media-456/foo.jpg
    You can also use the form shellid/mediaid. Assuming a shell id value of “789” and a media id value of “media-456”, the following URL will also work:.
    http://localhost:[port]/789/media-456/foo.jpg
  • Shell/RTE supporting files are accessed relative to the application’s shellid. That is, if an application with an shell id value of “789” needs to load the file “index.html”, located in the shell folder, the URL to use would be:
    http://localhost:[port]/789/index.html
    The actual filesystem location of the shell/RTE files path is defined in the “other files source” field of the Package section of the database’s Project Properties.
  • Lesson XML data is accessed using the lessonid property.  Assuming a lesson id value of “012”, the URL to use would be:
    http://localhost:[port]/012
    You can also use the form shellid/lessonid. Assuming a shell id value of “789” and a lesson id value of “012”, the following URL will also work:.
    http://localhost:[port]/789/012

Accessing files via the filesystem

Connect executable applications may prefer to access files using the filesystem directly. Each of the ID properties listed above have a path variation that specifies the filesystem location of the files.  The ID properties are:

  • instancepath
  • applicationpath
  • shellpath
  • mediapath

Note that lesson XML data must be loaded from the connect server, as it is not written to the filesystem (so no lessonpath property).

Connect objects

Most of the Connect API methods deal with retrieving (and storing) collections of data. Some of these collections can be converted to objects that include properties and methods, while some convert to objects that are simply aggregated data. The following sections summarize the objects accessible through Connect.

Persistence objects

Most Persistence objects use XML as a data transfer format. Many of these objects will be familiar to Impression Runtime Engine authors, and methods available for these objects are identical to the methods available through the RTE DevKit’s Base Class Framework.

The Connect SDK includes both source and compiled versions of Impression.Persistence.Dll, a managed library authored in C# containing all of the persistence objects exposed through the Connect API. The SDK also includes both uncompressed and minified versions of the Impression Persistence library for Javascript.

The following table lists the Persistence objects:

Object Description
PersistedPropertiesCollection An unordered collection of name/value pairs. Methods for retrieving data allow the caller to specify a default value if no data exists for the specified property name.
ChildElement An extension of the PersistedPropertiesCollection that can be added to a ChildElementCollection.
ChildElementCollection An ordered list of ChildElement objects.
Storyboard The basic unit of data for an individual screen. A Storyboard object contains a PersistedPropertiesCollection object (“Properties”) as well as a ChildElementCollection (“Children”).
StoryboardCollection An unordered collection of Storyboard objects.
LessonMap Defines a hierarchical ordering of storyboards.
LessonMapCollection A list of LessonMap objects, accessible by either name or position.
Lesson An individual unit of courseware; defining both content and structure.
LessonDescription A subset of a lesson, the LessonDescription includes all information relating to a lesson other than the actual content (storyboards and maps).
LessonDescriptionCollection An unordered collection of LessonDescription objects.
CourseMap Defines a hierarchical ordering of lessons.
CourseDescription Defines the content and structure for a content database. Note that a CourseDescription object does not include actual lesson content; rather, LessonDescription objects are available.

Informational objects

Informational objects provide contextual information about the environment hosting the content. The data is provided as JSON objects; no methods are provided for these items. The following table lists the informational objects:

Object Description
LessonInfo Contextual information about a lesson, including the location of media files for the lesson, access rights and token values.
ApplicationInfo Information about the calling application, including the instanceid, location of files, and a LessonInformation object containing information about the lesson that was selected at the time the application was launched.
CoreInfo Information about the system, including environment and database information, application information, and lesson information for the active lesson.
UserInformation Username and rights for the content database.

Talk objects

Talk objects encapsulate data from one of the Talk tables. These tables have been added to Impression content databases to allow storage of data relevant to, but not directly part of, developed content. The Talk application included with newer versions of the CCT (and available in regular and minified source versions in this SDK) uses the Talk tables to store media requests and discrepancy reports.

Talk data is provided as JSON objects; no methods are provided for these items. The following table lists the Talk objects:

Object Description
TalkPost The primary object for associating additional information with a piece of content.
TalkComment An additional unit of information, comments belong to posts.
TalkConfiguration An object intended to be used to store settings/preferences for applications using the Talk subsystem.

Active lesson vs. selected lesson

Connect notes two distinct lessons, the active lesson and the selected lesson.

The active lesson is the lesson that is currently open in the CCT's lesson editor.  If the lesson editor is not currently open, there is no active lesson; /getCoreInfo will not include an activelesson object, and calls to /getActiveLessonInfo will return an empty object.  You can use the /subscribe call to receive notifications when the active lesson changes (for example, when the user closes the lesson editor and returns to the Groups window).

The selected lesson is the lesson that was selected in the CCT when the application was launched.  This may be the active lesson (if the application was launched when the lesson editor is open), or it may be the lesson selected in the Groups treeview when the application was launched.  Information about the selected lesson is available from the ApplicationInfo object returned from a call to /getApplicationInfo, or in the application object returned from a /getCoreInfo call.  Unlike the active lesson, the selected lesson never changes.

C# Wrapper

A managed code interface for executable applications.

The Connect SDK includes a managed wrapper, written in C#, to ease development of Connect executable applications. The wrapper is provided in both source code and compiled versions. The C# wrapper requires the Impression.Persistence library as well as JSON.Net (also included in the SDK). Although the compiled versions of the wrapper and the supporting libraries were built against the .Net Framework 4 Client Profile, they can be compiled against 3.5 and higher of the .Net Framework. The included JSON.Net archive includes source and compiled versions, and is designed to run in multiple environments, including the .Net framework version 2 and higher, Silverlight, and Mono.

API Calls

Unlike the HTTP interface which returns strings that must be deserialized into an appropriate object, the C# wrapper returns native objects where possible. Methods that return persistence data (e.g. getLesson) return the appropriate persistence object, while informational object methods (e.g. getCoreInfo)return strongly typed objects defined in the wrapper. Talk objects are also returned as strongly typed objects; but since Talk objects can contain any type of data, they also expose a JSON.Net JObject for application developers to use to store additional data.

Exceptions

The HTTP API interface uses the statuscode and statusdescription properties of an HTTP request to indicate success or failure and to provide additional information in the event of a failed call. The C# wrapper catches failure codes and throws a ConnectorException. The exception has a Code property that contains the original HTTP status code, while the Message property contains the description of the error. Some errors return JSON data as part of the failed response; this data is converted to the appropriate object and stored in the ResultObject property.

Note that a ConnectorException is generated whenever a WebException is thrown.