API: Talk
Production support.
Production support.
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.
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. |
Returns a JSON array containing the requested items, ordered by lastModified (descending/newest posts first).
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. |
sbid
parameter is specified, the lessonid
parameter
must also be specified.A JSON object with an array property named "posts", containing the requested TalkPost items.
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
Returns the specified TalkPost record.
postid |
(identifier, required) Specifies the TalkPost to return. |
A JSON object containing the TalkPost data.
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"
}
Creates a new TalkPost record.
[postdata] |
(string, optional) A JSON string containing the initial TalkPost data. |
postid
, lastmodified
and revision
properties of the JSON POST object are ignored.
The return object will contain updated values for these
properties.status
property on the JSON object, the default value of
1
will be used.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”.A JSON object containing the TalkPost data.
400 | [postdata] is not a valid
JSON string (and is not empty). |
405 | Method was not invoked using HTTP 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"
}
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"
}
Updates a TalkPost record.
[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. |
lastmodified
property value of the JSON POST object is ignored. The
returned object will contain updated lastmodified
and revision
property values.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.A JSON object containing the updated TalkPost data.
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. |
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"
}
Deletes a TalkPost record.
postid |
(identifier, required) The TalkPost to delete. |
Nothing. The return code will be HTTP 200 (OK) if the method succeeds.
400 | postid is not specified |
deletePost?postid=307247b9-501b-412e-9474-be9ff872006b
{
"deleted": true
}
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. |
Returns a JSON array containing all comments for the specified post, ordered by lastModified (ascending/oldest posts first).
postid |
(identifier, required) Specifies the post to retrieve the comments of. |
A JSON object with an array property named "comments", containing the comments for the post.
400 | postid parameter not specified. |
404 | Post with postid not found in the database. |
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"
}
]
}
Returns the specified comment.
commentid |
(identifier, required) Specifies the comment to return. |
A JSON object containing the comment data.
400 | commentid parameter not specified. |
404 | Comment with commentid not found in the
database. |
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"
}
Creates a new Talk comment.
[postdata] |
(string, required) A JSON string containing the initial comment data. |
lastmodified
and revision
properties of
the JSON POST object are ignored. The return object will contain
updated values for these properties.A JSON object containing the TalkPost data.
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. |
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"
}
Updates a Talk comment.
[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. |
lastmodified
property value of the JSON POST
object is ignored. The returned object will contain updated
lastmodified
and revision
property
values.
A JSON object containing the updated comment data.
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. |
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"
}
Deletes a comment.
commentid |
(identifier, required) The comment to delete. |
Nothing. The return code will be HTTP 200 (OK) if the method succeeds.
400 | commentid is not specified |
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. |
Returns a JSON array containing the configurationid
values of all configuration objects.
None.
A JSON object with an array property named "configurationIdList", containing the
configurationid
values of all Talk configuration
records stored in the database.
None.
getTalkConfigurationList
{
"configurationIdList": [
"123",
"456"
]
}
Returns the specified configuration object.
configurationid |
(identifier, required) Specifies the id of the configuration object to return. |
A JSON object containing the comment data.
400 | configurationid parameter not specified. |
configurationid
parameter cannot be found, an empty
object with default values will be returned.
getTalkConfiguration?configurationid=123
{
"configurationid": "123",
"configurationtext": "foo bar baz bat",
"lastModified": "2013-08-21T09:49:13.183",
"revision": "c8994e05-062a-443f-94c6-9f0077fc7099"
}
getTalkConfiguration?configurationid=789
{
"configurationid": "789",
"lastModified": "1899-12-30T00:00:00",
"revision": ""
}
Updates a Talk configuration object.
[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:
lastmodified
property value of the JSON POST object is ignored. The
returned object will contain updated lastmodified
and revision
property values.revision
property value is
ignored, and a new configuration record is added to the
database.A JSON object containing the updated comment data.
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. |
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.