IMS Global Logo

IMS Global Learning Tools Interoperability™ Content-Item Message

Public Draft Version 1.0

Date Issued: 7 April 2014

Latest version: http://www.imsglobal.org/lti

IPR and Distribution Notices
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS’s procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/license.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

The IMS Logo and Learning Tools Interoperability (LTI) are trademarks of the IMS Global Learning Consortium, Inc. in the United States and/or other countries.
Documents Name: Learning Tools Interoperability Content-Item Message
v1.0 Public Draft – Revision: 7 April 2014

Table of Contents

2.1 Example Request.. 4

2.2 Example Response.. 5

3 Request to Tool Provider.. 7

3.1 Form Fields. 7

4 Response to Tool Consumer.. 9

4.1 Form Fields. 9

4.2 Content-Item Elements. 10

4.3 Example Responses. 11

4.3.1 LTI launch link. 11

4.3.2 Hyperlink with thumbnail 11

4.3.3 Embedded image. 12

4.3.4 Embedded HTML. 12

4.3.5 Hyperlink to local copy of a file. 12

About This Document.. 14

List of Contributors. 14

Revision History.. 15

1 Introduction

1.1 Scope

The content-item message is used to provide a mechanism for users to interact with a Tool Provider (TP) in the process of selecting one or more content items for insertion into the tool consumer. A typical use case would be to allow a user within a Tool Consumer (TC) to click a button on the toolbar of a text box editor, which opens a TP within an iframe (or pop-up window), use the interface provided to select one or more items, and have the selected item(s) returned to the TC and inserted into the text box. This may be an instructor adding content to a content page, or could be a student selecting an attachment to submit as part of an assignment.

Different types of content-item are supported for selection using this message:

· a customized launch of the TP;

· a static HTML hyperlink;

· an embedded image or other media type;

· embedded HTML;

· an iframe;

· a file (to be stored within the TC).

Since this message allows users to interact with the TP when creating LTI launch links, it can also be used to improve the workflow when adding an LTI link for TPs which require custom parameters to be included in the launch; these custom parameters can be specified when the link is created based on the content-item selected by the user.

1.2 References

[HTTP, 99] Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding et al. Retrieved 7 April 2014 from http://www.w3.org/Protocols/rfc2616/rfc2616.html

[LTI, 12] G.McFall, L.Neumann, S.Vickers, IMS Global Basic Learning Tools Interoperability v1.1.1, IMS Global Learning Consortium, September 2012. http://www.imsglobal.org/lti/.

[CIa, 14] S Vickers, Content-Item Message, IMS Global Learning Consortium, April 2014. http://www.imsglobal.org/lti/.

[CIb, 14] S Vickers, Content-Item Placements in the application/vnd.ims.lti.v1.contentitemplacement+json format, IMS Global Learning Consortium, April 2014. http://www.imsglobal.org/lti/.

[OAuth, 10] The OAuth 1.0 Protocol, E. Hammer-Lahav. Retrieved 7 April 2014 from http://tools.ietf.org/html/rfc5849

2 Implementation

The workflow around using the content-item message involves three steps:

The user’s browser is redirected to the TP.
The TP provides an interface which allows the user to discover and select an item to associate with a launch link in the TC.
The user’s browser is redirected back to the TC with details of the item(s) selected.

The initial redirection to the TP is achieved in the same manner as an LTI launch request: an HTML form is auto-submitted using JavaScript to the same endpoint in the TP using an HTTP POST. The same parameters are passed as for a launch request except that the lti_message_type has a value of ContentItemSelectionRequest; they are also signed with OAuth using the same consumer key and secret. [OAuth, 10] Given the different nature of this message type, the TP may be opened within an iframe or pop-up window so that the current page in the TC remains available when the user is returned from the TP; however, this is not a requirement and other workflows using this message type may re-use the same page as the TC.

The interface for discovering and selecting content items is entirely a matter for the TP. The request received from the TC should be verified in the same way as a launch request (for example, check the timestamp and nonce values and validate the signature). The parameters passed should provide sufficient data to allow the TP to identify the context from which the user is being passed, who the user is, and their role. Where appropriate this data can be used to provide an appropriate selection of items from which the user can select, or allow the user to create a new item. In the latter case, a TP should be aware that there is no guarantee that a link to the item selected will actually be created in the TC when the user is returned; this is entirely under the control of the TC interface which may allow a cancel option, for example.

One of the parameters provided when a user is redirected to the TP will be a URL for returning them to the TC (see the content_item_return_url parameter). A TP should always ensure that the user is returned to the TC, even if they do not select any items. This will allow the TC to close any iframes or windows opened during the initial redirect and return the user to the original page from which they started the process. Details of any selected items are passed back to the TC in a JSON array; this array may be empty if no item was selected. A user should always be redirected back to the TC using an auto-submitted form as an HTTP POST request; this return message may, or may not, be signed (see below).

2.1 Example Request

The following HTML form is an example of a redirect for a user to a TP to initiate a content-item selection process (some parameter values have been replaced with “...” for simplicity).

This form would be included in a page returned to the user’s browser and auto-submitted using JavaScript so that a POST request with the specified parameters is sent to the LTI endpoint for the TP (in the same way that a normal LTI launch request is handled).

2.2 Example Response

A user is returned by a TP to the TC in a similar manner to the request (see above). A form would be included in a page returned to the user’s browser and auto-submitted using JavaScript to the URL provided in the content_item_return_url parameter from the TC.

For example, assume the JSON representation of the selected content-item is as follows:

{
"@context" : "http://purl.imsglobal.org/ctx/lti/v1/ContentItemPlacement",
"@graph" : [
    {
      "@type" : "ContentItemPlacement",
      "placementOf" : {
        "@type" : "FileItem",
        "@id" : "http://developers.imsglobal.org/images/imscertifiedsm.png",
        "mediaType" : "image/png",
        "text" : "IMS logo for certified products",
        "title" : "The logo used to identify IMS certified products"
      },
      "displayWidth" : 147,
      "displayHeight" : 184,
      "presentation_document_target" : "embed",
      "windowTarget" : "_blank"
    }
]
}

The TP can then use a form like the following to return this item to be embedded in the TC (some parameter values have been replaced with “...” for simplicity).

Note that the JSON value of the content_items parameter should be encoded to ensure that the HTML of the page is valid. At a minimum any instances of the quotation character used to delimit the attribute value need to be encoded. A double quote may be encoded as " (or ") and a single quote may be encoded as '. For further information refer to the specification for the version of HTML being used by the page in which the form is being embedded.

3 Request to Tool Provider

3.1 Form Fields

A TC redirects the user to the TP using an HTTP POST request from an auto-submitted form. The form may include the following fields:

lti_message_type=ContentItemSelectionRequest (Required)
This indicates that this request represents a content-item selection message.

lti_version=LTI-1p0 (Required)
This indicates which version of the specification is being used for this particular message; for example, LTI-1p0 or LTI-2p0.

accept_media_types=application/vnd.ims.lti.v1.launch+json,image/*,text/html (Required)
A comma-separated list of MIME types which can be accepted on the return URL. A MIME type of application/vnd.ims.lti.v1.launch+json is used to represent an LTI launch request to a TP. This parameter should use the same format as the Accept header in HTTP requests [HTTP, 99]. For example, a value of “image/*; q=0.5, image/png” indicates that a PNG image is preferred, but any type of image will be accepted if one is not available.

accept_presentation_document_targets=embed,frame,iframe,window,popup,overlay (Required)
A comma-separated list of ways in which the selected content item(s) can be requested to be opened (via the presentation_document_target response parameter). The possible values for this parameter are:

· embed – insert the item at the current insertion point (for example, using an img tag or an object tag);

· frame – open the item in the same frame as the link;

· iframe – open the item within an iframe within the same page/frame as the link;

· window – open the item in a new window (or tab);

· popup – open the item in a popup window (using the dimensions provided, if any);

· overlay – open the item over the top of the page where the link exists (for example, using a lightbox).

content_item_return_url=http://lmsng.school.edu/portal/123/page/988/item/261 (Required)
Fully qualified URL where the TP redirects the user back to the TC interface. This URL can be used once the TP is finished or if the TP cannot start or has some technical difficulty.

accept_unsigned=false | true (Optional)
This indicates whether the TC is willing to accept an unsigned return message, or not. A signed message should always be required when the content item is being created automatically in the Tool Consumer without further interaction from the user. This parameter is optional; when omitted a value of false should be assumed (i.e. the return message should be signed).

accept_multiple=false | true (Optional)
This indicates whether the user should be permitted to select more than one item. This parameter is optional; when omitted a value of false should be assumed (i.e. only a single item may be returned).

accept_copy_advice=false | true (Optional)
This indicates whether the TC is able and willing to make a local copy of a content item. The return message may include a expiresAt parameter to indicate that the URL provided will expire and so a copy of the content item should be stored locally before the expiry time passes. Use a value of false (the default) to indicate that the TC has no capacity for storing local copies of content items.

text=... (Optional)
Default text to be used as the visible text or titles for the content-item returned by the TP.

title=... (Optional)
Default text to be used as the title or alt text for the content-item returned by the TP. If no title is returned by the TP, the TC may use the text parameter (if any) instead.

data=... (Optional)
An opaque value which should be returned by the TP in its response.

The TC should also pass the other parameters about the tool consumer, the user, the context and the user’s roles as would be included in a launch request (see [LTI, 11, Basic Launch Data]). The following parameters should not be passed:

· resource_link_id

· resource_link_title

· resource_link_description

· launch_presentation_return_url

· lis_result_sourcedid

If any custom parameters have been specified for launches to the TP, they should also be included for this message type. All relevant custom substitution parameter variables should also be supported; those relating to resource links or results would not be relevant, for example, since this message occurs before a resource link is created, if one is created at all.

4 Response to Tool Consumer

4.1 Form Fields

A TP should return the user to the TC as an HTTP POST request using an auto-submitted form. It may include the following fields:

lti_message_type=ContentItemSelectionResponse (Required)
This indicates that this is a response to a content-item selection request message.

lti_version=LTI-1p0 (Required)
This indicates which version of the specification is being used for this particular message. It should use the same value as received in the request from the Tool Consumer.

content_items=... (Optional)
The value of this parameter should be a JSON array containing details of each of the items selected (see examples below). If no items have been selected this parameter may contain an empty array or be omitted.

For example, the content_items parameter may have a value of:

{
"@context" : "http://purl.imsglobal.org/ctx/lti/v1/ContentItemPlacement",
"@graph" : [
    { "@type" : "ContentItemPlacement",
      "presentation_document_target" : "window",
      "placementOf" : {
        "@type" : "LtiLink",
        "icon" : {
          "@id" : "http://tool.provider.com/icons/small.png",
          "width" : 50,
          "height" : 50
        },
        "thumbnail" : {
          "@id" : "http://tool.provider.com/images/thumb.jpg",
          "width" : 100,
          "height" : 150
        },
        "text" : "The <em>sIMSon</em> application provides a collaborative space for developing semantic modelling skills.",
        "mediaType" : "application/vnd.ims.lti.v1.launch+json",
        "title" : "Open sIMSon application",
        "custom" : {
          "level" : "novice",
          "mode" : "interactive"
        }
      },
      "windowTarget" : "anLTIApp"
    },
    { "@type" : "ContentItemPlacement",
      "copyAdvice" : false,
      "displayWidth" : 800,
      "presentation_document_target" : "iframe",
      "displayHeight" : 600,
      "placementOf" : {
       "@type" : "FileItem",
        "@id" : "http://tool.provider2.com/animation/sample.swf",
        "icon" : {
          "@id" : "http://tool.provider2.com/icon/sample.png",
          "width" : 45,
          "height" : 45
        },
        "text" : "Watch this animation.",
        "mediaType" : "application/x-shockwave-flash"
      }
    }
]
}

The structure of each element in the array could be different for each type of content item (see below). If no content items were selected, then the parameter may have a value of:

{
"@context" : "http://purl.imsglobal.org/ctx/lti/v1/ContentItemPlacement",
"@graph" : [
]
}

or be omitted from the return parameters altogether.

data=... (Optional)
If a data parameter is passed with the original content-item message received, then its value must be returned in this parameter. The value is opaque to the TP and should be returned unchanged. If no parameter was included in the original request, then this parameter should be omitted.

lti_msg=... (Optional)
If the TP is returning normally, and wants a message displayed to the user it can include it as a plain text[1] value in this parameter.

lti_log=... (Optional)
This parameter allows the TP to give the TC a plain text message to log when it returns normally.

lti_errormsg=... (Optional)
In the case of an error, the TP may use this parameter to provide some detail in plain text as to the nature of the error for displaying to the user. The TC should ensure that this message is displayed; if the TP has already provided an indication of the error to the user, then there would be no need to also use this parameter.

lti_errorlog=... (Optional)
This parameter may contain a plain text error message to be logged by the TC.

The response message must be signed unless the initial request included an accept_unsigned parameter with a value of true. Otherwise the TP may choose whether to sign the response message, or not. Messages are signed using OAuth ([OAuth, 10]) in the same way as LTI launch request messages ([LTI, 12]).

4.2 Content-Item Elements

The permitted elements to describe the placement of a selected content-item are as follows:

mediaType (Required)
This element describes the type of content-item. It should have a value of the MIME type for the content item.

@id (Required/Optional)
A fully qualified URL to use for the item being placed. This parameter is optional for content-items of type application/vnd.ims.lti.v1.launch+json but is required for all other types. When not specified for a content-item of type application/vnd.ims.lti.v1.launch+json the default launch URL used for the same TP should be assumed.

copyAdvice=false | true (Optional)
This parameter is an indicator to the TC as to whether it should take a copy of the content-item and use its local copy for users to access. If true then the TP may also indicate a time period within which the copy must be taken using the expiresAt parameter. The default value is false.

expiresAt (Optional)
The presence of this parameter indicates that the content URL is only available for a limited time and so a copy of its contents should be stored locally if access is required for a longer period. The parameter value should be a date/time in ISO 8601 format (e.g. 2014-03-05T12:34:56Z). This parameter is not applicable to content-items of type application/vnd.ims.lti.v1.launch+json.

presentation_document_target (Optional)
This parameter is used to determine where the content-item being added should be opened. It should be one of the values included in the accept_presentation_document_targets request parameter (see above); if the parameter was not included in the request then this parameter should be omitted from the response. When omitted, the TC should use a plain anchor tag; the target parameter (see below) may be used to set where the content-item is opened.

windowTarget (Optional)
The windowTarget parameter to be used for any hyperlink used to open the content-item may be specified using this parameter. Note that this parameter is distinct from the presentation_document_target parameter (see above) which is used to determine how the content-item is opened. This parameter is most useful when a presentation_document_target of window is specified.

text (Optional)
The text to display to represent the content-item. A TP should use any text provided by the TC in the request as the initial default, but this may be altered as part of the selection process.

title (Optional)
The text to use as the title attribute for the content-item. When not provided, a TC may use the value of the text parameter instead.

icon (Optional)
An object containing an @id element providing a fully qualified URL for an icon image to be placed with the content item. A width and/or height element may also be provided. When specified the width and height values should be a positive integer representing the number of pixels. An icon size of 50x50 is recommended. A tool consumer may not support the display of icons; but where it does, it may choose to use a local copy of the icon rather than linking to the URL provided (which would also allow it to resize the image to suits its needs).

thumbnail (Optional)
An object containing an @id element providing a fully qualified URL for a thumbnail image to be made a hyperlink. This allows the hyperlink to be opened within the TC from text or an image, or from both. A width and/or height element may also be included. When specified the width and height values should be a positive integer representing the number of pixels.

displayWidth (Optional)
A valid value for the width attribute of the HTML element which will be created by the TC to refer to the content-item. This may also be used for sizing a popup window when this document target is requested. Typically this is a positive integer value representing the number of pixels.

displayHeight (Optional)
A valid value for the height attribute of the HTML element which will be created by the TC to refer to the content-item. This may also be used for sizing a popup window when this document target is requested. Typically this is a positive integer value representing the number of pixels.

custom (Optional)
A set of custom parameters to be included in the LTI launch request (as name and value pairs) from the link being created. This parameter only applies to content-items of type application/vnd.ims.lti.v1.launch+json.

For further details see [CIa, 14] and [CIb, 14].

4.3 Example Responses

Some examples of different content-item types follow. Whilst there is a certain level of trust which can be assumed when a response is signed, it is always recommended that any parameter value which is being added to a content page in the TC is checked for any potentially harmful content (such as JavaScript).

4.3.1 LTI launch link

The following example should add an image and the text “LTI launch” at the current insertion point in the TC, with both being set as a hyperlink to generate a launch request to the TP with two custom parameters being passed:

{
"@type" : "ContentItemPlacement",
"placementOf" : {
    "@type" : "LtiLink",
    "mediaType" : "application/vnd.ims.lti.v1.launch+json",
    "icon" : {
      "@id" : "https://www.server.com/path/animage.png",
      "width" : 50,
      "height" : 50
    },
    "text" : "LTI launch",
    "title" : "special content"
}
}

4.3.2 Hyperlink with thumbnail

The following example should add an image and the text “IMS catalog of certified products” at the current insertion point in the TC, with both being set as a hyperlink to open the URL provided in a new window:

{
    "@type" : "ContentItemPlacement",
"placementOf" : {
    "@type" : "FileItem",
    "@id" : "http://imscatalog.org/",
    "mediaType" : "text/html",
    "thumbnail" : {
      "@id" : "http://developers.imsglobal.org/images/imscertifiedsm.png",
      "width" : 147,
      "height" : 184
    },
    "text" : "IMS catalog of certified products",
    "title" : "Open the IMS catalog of certified products in a new window"
}
"presentation_document_target" : "window",
"windowTarget" : "_blank"
}

The TC would insert HTML like the following on receipt of the above content-item; the precise layout and format is not prescribed here but should display the image and the text and make both hyperlinked to the URL provided:

<a href=" http://imscatalog.org/" target="_blank"
title="Open the IMS catalog of certified products in a new window">
<img src="http://developers.imsglobal.org/images/imscertifiedsm.png"
   alt="IMS catalog of certified products"
   title="Open the IMS catalog of certified products in a new window"
   width="147" height="184" /> IMS catalog of certified products
</a>

4.3.3 Embedded image

The following example should insert an image in the TC at the current insertion point:

{
"@type" : "ContentItemPlacement",
"placementOf" : {
    "@type" : "FileItem",
    "@id" : "http://developers.imsglobal.org/images/imscertifiedsm.png",
    "mediaType" : "image/png",
    "text" : "IMS logo for certified products",
    "title" : "The logo used to identify IMS certified products"
},
"displayWidth" : 147,
"displayHeight" : 184,
"presentation_document_target" : "embed",
"windowTarget" : "_blank"
}

The HTML used to display the image would be as follows:

4.3.4 Embedded HTML

The following example shows how an HTML fragment may be inserted into the TC at the current insertion point:

{
"@type" : "ContentItemPlacement",
"placementOf" : {
    "@type" : "FileItem",
    "@id" : "http://developers.imsglobal.org/images/imscertifiedsm.png",
    "mediaType" : "text/html",
    "text" : "<p>IMS has a <a href=\" http://imscatalog.org/\">catalog of certified products</a> available on their website</p>",
    "title" : "The logo used to identify IMS certified products"
},
"presentation_document_target" : "embed",
}

4.3.5 Hyperlink to local copy of a file

The following example should insert a link to a local copy of a PDF file in the TC:

{
"@type" : "ContentItemPlacement",
"placementOf" : {
    "@type" : "FileItem",
    "@id" : "http://www.imsglobal.org/xsd/qti/qtiv2p1/imsqti_v2p1.xsd",
    "copyAdvice" : "true",
    "expiresAt" : "2014-03-05T00:00:00Z",
    "mediaType" : "application/xml",
    "text" : "QTI v2.1 Specification Information Model"
},
"windowTarget" : "_blank"
}

The copyAdvice element indicates that the TC should make a local copy of this item. The expiresAt element indicates that the content URL is only available for a limited period and so the copy should be taken before this time. It is expected that normally a copy will be taken when the link is created. A link to the local copy of the file would be inserted in the TC:

<a href="http://www.tc.com/local/file.xml" target="_blank"> QTI v2.1 Specification Information Model</a>

4.3.6 Example including elements from other contexts (e.g. metadata)

Additional elements can be included in the JSON response by referencing the context(s) from which they are drawn. The following example includes an element from LRMI.

{
"@context" : [
    http://purl.imsglobal.org/ctx/lti/v1/ContentItemPlacement,
    {
      "educationalUse" : "http://schema.org/educationalUse"
    }
],
"@graph" : [
    { "@type" : "ContentItemPlacement",
      "presentation_document_target" : "window",
      "placementOf" : {
        "@type" : "LtiLink",
        "text" : "The <em>sIMSon</em> application provides a collaborative space for developing semantic modelling skills.",
        "mediaType" : "application/vnd.ims.lti.v1.launch+json",
        "title" : "Open sIMSon application"
      },
      "windowTarget" : "anLTIApp",
      "educationalUse" : "group work"
    }
]
}

About This Document

Title: IMS Global LTI Content-Item Message

Editor: Stephen Vickers (IMS Global)

Version: 1.0

Version Date: 7 April 2014

Status: Public Draft

Purpose: This document is made available for comment by the public community at large.

Document Location: http://www.imsglobal.org/lti

List of Contributors

The following individuals contributed to the development of this document:

Viktor Haag Desire2Learn

Bracken Mosbacker Instructure

Brad Humphrey Instructure

Greg McFall Pearson

Claude Vervoort Cengage Learning

Stephen Vickers IMS Global

Revision History

Version No.	Release Date	Comments
Public Draft v1.0	7 April 2014

IMS Global Learning Consortium, Inc. (“IMS Global”) is publishing the information contained in this document (“Specification”) for purposes of scientific, experimental, and scholarly collaboration only.

IMS Global makes no warranty or representation regarding the accuracy or completeness of the Specification.

This material is provided on an “As Is” and “As Available” basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

IMS Global would appreciate receiving your comments and suggestions.

Please contact IMS Global through our website at http://www.imsglobal.org.

Please refer to Document Name: IMS Global Learning Tools Interoperability Content-Item Message

Date: 7 April 2014

[1] Plain text means that the TC will treat the parameter value as text/plain and not text/html. If the TP includes characters such as less-than or greater-than in plain text fields, those characters are to be escaped and displayed. In particular, the TP should not embed HTML tags in plain text fields with the expectation that the HTML will be handed directly to the browser. For example, if a plain text field contains the string "Mode: <strong> security", the TC should escape the data so the user sees the less-than, greater-than, and text between them literally rather than switching the word "security" to be in bold font.