The Impression Talk subsystem includes new Impression content database tables and ImpressionConnect API methods for accessing and storing data into these tables. These tables are not used by the CCT; rather, they provide a way to store non-lesson data (or lesson-related data not supported by the CCT) and associate that data with the lessons and storyboards of a content database.

Although newer versions of the CCT will automatically define the Talk tables when creating a new database, older content databases will need to be upgraded to support Talk. This can be done using tools in the Impression Data Utilities package available from the Impression web site.

Talk Posts

The Post is the primary object for associating additional information with a piece of content.

A post can be a discrepancy report, a media request, or another item—the ImpressionConnect API methods for working with posts only enforce the relationship between a post and the courseware content; they do not mandate what additional data is included in the post. A post can be associated with a specific storyboard in a lesson, with a specific lesson, or with the content database as a whole.

Post data is stored and retrieved as a JSON string. The following properties, when stored in the root of a post object, are used by the API as described below.

`postid`	(identifier) The unique identifier of the post. Note that `postid` values are generated by the API.
`applicationid`	(identifier) The unique identifier of the application that created or is responsible for this post. May be empty.
`lessonid`	(identifier) The unique identifier of the lesson that the post applies to. If this value is empty, the post applies to the entire course.
`sbid`	(identifier) The unique identifier of the storyboard that the post applies to. If this value is not empty, the `lessonid` value must not be empty. If this value is empty, the `lessonid` property defines the scope of the post.
`status`	(integer) A numeric value indicating the disposition of the post. Future versions of the CCT will use this value when providing aggregate information for a lesson; positive values will indicate an “active” post, while 0 or negative values will indicate an “inactive” post.
`lastmodified`	(date/time) The date/time that the post was last written to the content database. This value is managed by the API.
`revision`	(identifier) A unique identifier managed by the API and used to ensure that content is not accidentally overwritten when concurrent users access the same post.

The properties listed above are stored in discrete fields in the content database. The ImpressionConnect API removes these properties from the JSON object before it is stored, and adds them back to the root of the post object before the object is returned to the caller.

getPosts method

Returns a JSON array containing the requested items, ordered by lastModified (descending/newest posts first).

Parameters

`applicationid`	(identifier, optional) Specifies the value of the `applicationid` property of the items. If this value is not specified, posts with any `applicationid` value will be returned. This value may be blank.
`lessonid`	(identifier, optional) Specifies the value of the `lessonid` property of the items. If this value is not specified, posts with any `lessonid` value will be returned. This value may be blank.
`sbid`	(identifier, optional) Specifies the value of the `sbid` property of the items. If this value is not specified, posts with any `sbid` value will be returned. This value may be blank.

If the sbid parameter is specified, the lessonid parameter must also be specified.

Returns

A JSON object with an array property named "posts", containing the requested TalkPost items.

Errors

400	`lessonid` parameter not specified when `sbid` parameter is specified.

Get an array of “global” posts (posts not associated with a specific lesson):

getPosts?lessonid=&sbid=


{
  "posts": [
    {
      "foo": "bar",
      "baz": "bat",
      "postid": "fe86d3d2-d2e9-493e-b796-3fe42173a3f1",
      "lessonid": "",
      "sbid": "",
      "status": 1,
      "lastModified": "2013-11-19T13:04:49.84",
      "revision": "4fe11e64-5342-4706-a50f-9a4487594354"
    },
    {
      "postid": "f07c0888-3403-4f01-a645-0c6da87edf3b",
      "lessonid": "",
      "sbid": "",
      "status": 1,
      "lastModified": "2013-11-19T13:04:12.483",
      "revision": "43ed1afb-1a3e-4fdd-bc8f-ede89869241b"
    }
  ]
}

Get all posts for the lesson with id “123”:

getPosts?lessonid=123

Get all posts for storyboard “123” in lesson “123”:

getPosts?lessonid=123&sbid=456

getPost method

Returns the specified TalkPost record.

Parameters

postid (identifier, required) Specifies the TalkPost to return.

Returns

A JSON object containing the TalkPost data.

Errors

400	`postid` parameter not specified.
404	TalkPost with `postid` not found in database.

getPost?postid=2fbd8230-a212-471b-9a5d-0a871de39f6f


{
  "foo": "bar",
  "baz": "bat",
  "postid": "fe86d3d2-d2e9-493e-b796-3fe42173a3f1",
  "lessonid": "",
  "sbid": "",
  "status": 1,
  "lastModified": "2013-11-19T13:04:49.84",
  "revision": "4fe11e64-5342-4706-a50f-9a4487594354"
}

addPost method (POST)

Creates a new TalkPost record.

Parameters

[postdata] (string, optional) A JSON string containing the initial TalkPost data.

The postid, lastmodified and revision properties of the JSON POST object are ignored. The return object will contain updated values for these properties.
If you omit the status property on the JSON object, the default value of 1 will be used.
Future versions of the CCT will use the status property of the JSON object to provide information about the number of active posts for a lesson. Property values >= 1 will be considered “active”, while values < 1 will be considered “inactive”.

Returns

A JSON object containing the TalkPost data.

Errors

400	`[postdata]` is not a valid JSON string (and is not empty).
405	Method was not invoked using HTTP POST.

Examples

Create a new, empty post:

addPost


{
  "postid": "2dd8ea17-8a33-452f-adbb-ac51c998dbbe",
  "lessonid": "",
  "sbid": "",
  "status": 1,
  "lastModified": "2013-11-19T14:34:55.4193913-05:00",
  "revision": "de87316b-d67c-44aa-a578-d36bfc634e51"
}

Create a new post for lesson “123”:


addPost
{
  "lessonid": "123",
  "status": 3,
}


{
  "postid": "e8b1736c-f259-4019-bc1b-6552a21fecd3",
  "lessonid": "123",
  "sbid": "",
  "status": 3,
  "lastModified": "2013-11-19T14:38:18.5133318-05:00",
  "revision": "99fdf73c-7022-4f53-b1e5-acb89e72f40c"
}

updatePost method (POST)

Updates a TalkPost record.

Parameters

`[postdata]`	(string, required) A JSON string containing the updated TalkPost data to store.
`overwrite`	(boolean, optional) If `true`, overwrite the existing data even if the `revision` property value in the database does not match the postdata's `revision` property value.

The lastmodified property value of the JSON POST object is ignored. The returned object will contain updated lastmodified and revision property values.
If you omit the status property on the JSON object, the value will not be changed. If the status property value is not castable to an integer, the default value of 1 will be used.

Returns

A JSON object containing the updated TalkPost data.

Errors

400	`[postdata]` is empty or is not a valid JSON string.
400	`[postdata]` does not contain a `postid` property value.
404	Post with the specified `postid` property value not found in the database.
405	Method was not invoked using HTTP POST.
409	The `[postdata]` object's `revision` property value does not match the `revision` property value stored in the database, and the `overwrite` parameter was not specified (or its value was not set to `true`). If this error occurs, the method will return the TalkPost object stored in the database.

Example


updatePost?overwrite=true
{
  "postid": "307247b9-501b-412e-9474-be9ff872006b",
  "lessonid": "123",
  "sbid": "",
  "lastModified": "2013-11-19T15:49:28.441",
  "revision": "588a85a2-4e6b-4345-869e-2f0bcb1716c0"
}


{
  "postid": "307247b9-501b-412e-9474-be9ff872006b",
  "lessonid": "123",
  "sbid": "",
  "status": 1,
  "lastModified": "2013-11-19T15:55:48.637",
  "revision": "c4fb02c7-5b05-46a8-bdff-0f82507a0d16"
}

deletePost method

Deletes a TalkPost record.

Parameters

postid (identifier, required) The TalkPost to delete.

Deleting a post will delete all comments associated with the post.

Returns

Nothing. The return code will be HTTP 200 (OK) if the method succeeds.

Errors

400	`postid` is not specified

Example

deletePost?postid=307247b9-501b-412e-9474-be9ff872006b


{
  "deleted": true
}

Talk Comments

A Talk Comment is an additional unit of information associated with a post. As with posts, comments are stored as JSON strings and can contain any information.

Comments must be associated with a post; if a post is deleted, all comments associated with the post are deleted as well. The following properties, when stored in the root of a Comment object, are used by the API as described below.

`commentid`	(identifier) The unique identifier of the comment. Note that `commentid` values are generated by the API.
`postid`	(identifier) The unique identifier of the post that the comment applies to.
`lastmodified`	(date/time) The date/time that the comment was last written to the content database. This value is managed by the API.
`revision`	(identifier) A unique identifier managed by the API and used to ensure that content is not accidentally overwritten when concurrent users access the same comment.

The properties listed above are stored in discrete fields in the content database. The ImpressionConnect API removes these properties from the JSON object before it is stored, and adds them back to the root of the post object before the object is returned to the caller.

getComments method

Returns a JSON array containing all comments for the specified post, ordered by lastModified (ascending/oldest posts first).

Parameters

postid (identifier, required) Specifies the post to retrieve the comments of.

Returns

A JSON object with an array property named "comments", containing the comments for the post.

Errors

400	`postid` parameter not specified.
404	Post with `postid` not found in the database.

Example

Get the comments for the post with postid “123” posts:

getComments?postid=123


{
  "comments": [
    {
      "commenttext": "baz bat",
      "commentid": "a7b63a76-9e7c-4678-b306-9ed0a324fac7",
      "postid": "123",
      "lastModified": "2013-11-20T08:11:56.582",
      "revision": "08b5a964-cf5e-4e37-86db-51718453224c"
    },
    {
      "foo": "bar",
      "commentid": "00309e0b-e677-49bb-a30b-d0a8800138ac",
      "postid": "123",
      "lastModified": "2013-11-20T09:14:23.643",
      "revision": "bf98e29e-d5b3-4837-93f1-1a477ed96f25"
    }
  ]
}

getComment method

Returns the specified comment.

Parameters

commentid (identifier, required) Specifies the comment to return.

Returns

A JSON object containing the comment data.

Errors

400	`commentid` parameter not specified.
404	Comment with `commentid` not found in the database.

Example

getComment?commentid=00309e0b-e677-49bb-a30b-d0a8800138ac


{
  "foo": "bar",
  "commentid": "00309e0b-e677-49bb-a30b-d0a8800138ac",
  "postid": "123",
  "lastModified": "2013-11-20T08:11:20.003",
  "revision": "81f13a81-751c-4d62-9638-a71c3c81b043"
}

addComment method (POST)

Creates a new Talk comment.

Parameters

[postdata] (string, required) A JSON string containing the initial comment data.

The lastmodified and revision properties of the JSON POST object are ignored. The return object will contain updated values for these properties.

Returns

A JSON object containing the TalkPost data.

Errors

400	`[postdata]` is not a valid JSON string.
400	`[postdata]` does not contain a `postid` property.
404	Post with `postid` not found in the database.
405	Method was not invoked using HTTP POST.

Example


addComment

{
  "postid": "e6596cd9-a6f9-4ca9-a409-bfe98922de6a",
  "commenttext": "foo bar"
}


{
  "commenttext": "foo bar",
  "commentid": "00309e0b-e677-49bb-a30b-d0a8800138ac",
  "postid": "e6596cd9-a6f9-4ca9-a409-bfe98922de6a",
  "lastModified": "2013-11-20T08:11:20.0031343-05:00",
  "revision": "81f13a81-751c-4d62-9638-a71c3c81b043"
}

updateComment method (POST)

Updates a Talk comment.

Parameters

`[postdata]`	(string, required) A JSON string containing the updated comment object to store.
`overwrite`	(boolean, optional) If `true`, overwrite the existing data even if the `revision` property value in the database does not match the postdata object's `revision` property value.

The lastmodified property value of the JSON POST object is ignored. The returned object will contain updated lastmodified and revision property values.

Returns

A JSON object containing the updated comment data.

Errors

400	`[postdata]` is empty or is not a valid JSON string.
400	`[postdata]` does not contain a `commentid` property value.
400	`[postdata]` does not contain a `postid` property value.
404	Comment with the specified `commentid` property value not found in the database.
404	Post with the specified `postid` property value not found in the database.
405	Method was not invoked using HTTP POST.
409	The `[postdata]` object's `revision` property value does not match the `revision` property value stored in the database, and the `overwrite` parameter was not specified (or its value was not set to `true`). If this error occurs, the method will return the Talk comment object stored in the database.

Example


updateComment
{
  "foo": "bar",
  "commentid": "00309e0b-e677-49bb-a30b-d0a8800138ac",
  "postid": "e6596cd9-a6f9-4ca9-a409-bfe98922de6a",
  "lastModified": "2013-11-20T09:14:23.643",
  "revision": "bf98e29e-d5b3-4837-93f1-1a477ed96f25"
}


{
  "foo": "bar",
  "commentid": "00309e0b-e677-49bb-a30b-d0a8800138ac",
  "postid": "e6596cd9-a6f9-4ca9-a409-bfe98922de6a",
  "lastModified": "2013-11-20T09:38:19.411",
  "revision": "c0708275-a84e-43d1-82c6-fe891a46e579"
}

deleteComment method

Deletes a comment.

Parameters

commentid (identifier, required) The comment to delete.

Returns

Nothing. The return code will be HTTP 200 (OK) if the method succeeds.

Errors

400	`commentid` is not specified

Example

deleteComment?commentid=00309e0b-e677-49bb-a30b-d0a8800138ac


{
  "deleted": true
}

Talk supports configuration objects; these typically contain data for the application.

For example, the basic Talk application included with Impression uses a configuration object to store support priority values. The following properties, when stored in the root of a configuration object, are used by the API as described below.

`configurationid`	(identifier) The unique identifier of the configuration object.
`lastmodified`	(date/time) The date/time that the configuration was last written to the content database. This value is managed by the API.
`revision`	(identifier) A unique identifier managed by the API and used to ensure that content is not accidentally overwritten when concurrent users access the same configuration object.

Unlike posts and comments, the unique identifier for a configuration object must be generated by the application. This is typically done by hard-coding a configuration ID (usually a GUID) into the application itself.

getTalkConfigurationList method

Returns a JSON array containing the configurationid values of all configuration objects.

Parameters

None.

Returns

A JSON object with an array property named "configurationIdList", containing the configurationid values of all Talk configuration records stored in the database.

Errors

None.

Example

getTalkConfigurationList


{
  "configurationIdList": [
    "123",
    "456"
  ]
}

getTalkConfiguration method

Returns the specified configuration object.

Parameters

configurationid (identifier, required) Specifies the id of the configuration object to return.

Returns

A JSON object containing the comment data.

Errors

400	`configurationid` parameter not specified.

Unlike posts and comments, if the configuration object specified by the configurationid parameter cannot be found, an empty object with default values will be returned.

Examples

Retrieve the configuration object with configuration id “123”:

getTalkConfiguration?configurationid=123


{
  "configurationid": "123",
  "configurationtext": "foo bar baz bat",
  "lastModified": "2013-08-21T09:49:13.183",
  "revision": "c8994e05-062a-443f-94c6-9f0077fc7099"
}

Retrieve the configuration object with configuration id “789”, which does exist in the database:

getTalkConfiguration?configurationid=789


{
  "configurationid": "789",
  "lastModified": "1899-12-30T00:00:00",
  "revision": ""
}

updateTalkConfiguration method (POST)

Updates a Talk configuration object.

Parameters

`[postdata]`	(string, required) A JSON string containing the updated configuration object to store.
`overwrite`	(boolean, optional) If `true`, overwrite the existing data even if the `revision` property value in the database does not match the postdata object's `revision` property value.

Notes:

The lastmodified property value of the JSON POST object is ignored. The returned object will contain updated lastmodified and revision property values.
If the configuration record is not found in the database, the revision property value is ignored, and a new configuration record is added to the database.

Returns

A JSON object containing the updated comment data.

Errors

400	`[postdata]` is empty or is not a valid JSON string.
400	`[postdata]` does not contain a `configurationid` property value.
405	Method was not invoked using HTTP POST.
409	The `[postdata]` object's `revision` property value does not match the `revision` property value stored in the database, and the `overwrite` parameter was not specified (or its value was not set to `true`). If this error occurs, the method will return the Talk comment object stored in the database.

Example


updateTalkConfiguration
{
  "configurationtext": "fred barney wilma betty",
  "configurationid": "123",
  "lastModified": "2013-11-27T10:33:45.587",
  "revision": "746b1f81-f6e0-4f94-9e96-c4fe175ef66e"
}


{
  "configurationtext": "fred barney wilma betty",
  "configurationid": "123",
  "lastModified": "2013-11-27T10:34:28.048",
  "revision": "6cfb5a1b-106d-428a-8fad-ea803a907844"
}

Handling concurrent access.

In the Impression Content Creation Tool, editing conflicts are prevented by the use of locks. When a user chooses to edit a lesson, the CCT adds a write lock to the database before allowing the user to edit, and releases the lock when the user exits the lesson editor. Checks are performed before issuing the lock to ensure that no other user has a write lock on the lesson, and the lock is checked before any saves are made to the database. Additional code and tools are built into the CCT to handle the cases where the write lock is not properly released, or has been improperly removed from the content database. Since only one content creator is typically working on a lesson at any time during the production process, this limitation does not impose an undue burden.

The use cases for Talk-type applications are not a good fit for the locking mechanism used by the CCT for lesson content; multiple users reviewing Impression content and creating or updating information about a given lesson is an expected case. Further, typical Talk applications do not switch into an “edit mode” in all cases (unlike the CCT). Because of this, Talk posts, comments, and configuration data objects all use a revision field to assist the application developer supporting concurrent user editing of Talk data.

Each revision field contains a GUID, generated by the ImpressionConnect API, which is automatically updated by ImpressionConnect each time a Talk object is written to the database. The revision value passed in the JSON object from the application to the API is compared to the revision value stored in the database. If the value does not match, the write operation is cancelled and the stored data (including the revision value) is returned to the caller. The application can then handle the conflict in any fashion by, including displaying a simple notification to the user, offering a merge dialog to allow the user to select what data, or some other approach.

If the value does match, the write operation is performed, and the updated object with the new revision value is returned. This allows an application to ensure that a write operation will not replace content added since the last time the object was retrieved from the content database.

If the application determines that the updated data stored should be modified, the application can either update the object with the newest revision value provided by the API before re-attempting the call, or by setting the overwrite parameter to true.

As noted above, calls that write Talk objects to the database return the changed revision property. Talk application developers should update their objects with the new revision.

API: Talk

Overview

Talk Posts

getPosts method

Parameters

Returns

Errors

getPost method

Parameters

Returns

Errors

addPost method (POST)

Parameters

Returns

Errors

Examples

updatePost method (POST)

Parameters

Returns

Errors

Example

deletePost method

Parameters

Returns

Errors

Example

Talk Comments

getComments method

Parameters

Returns

Errors

Example

getComment method

Parameters

Returns

Errors

Example

addComment method (POST)

Parameters

Returns

Errors

Example

updateComment method (POST)

Parameters

Returns

Errors

Example

deleteComment method

Parameters

Returns

Errors

Example

Talk Configuration

getTalkConfigurationList method

Parameters

Returns

Errors

Example

getTalkConfiguration method

Parameters

Returns

Errors

Examples

updateTalkConfiguration method (POST)

Parameters

Returns

Errors

Example

Revisions