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.

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:

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.

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

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.

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:

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:

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:

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.