1EdTech Learning Tools Interoperability^® Content-Item Message

Version 1.0 Final

Date Issued: 24 May 2016

Latest version: http://www.imsglobal.org/specs/lticiv1p0

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.

1EdTech 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 1EdTech’s procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: https://www.imsglobal.org/sites/default/files/imsipr_policyFinal.pdf.

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: https://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 1EdTech 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.

Trademark information: https://www.imsglobal.org/copyright.html
Document Name: 1EdTech Learning Tools Interoperability Content-Item Message v1.0
Revision: 24 May 2016

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, 14] Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, R. Fielding et al. Retrieved 24 May 2016 from [http://tools.ietf.org/html/rfc7231].

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

[LTI, 14 OM] S.Vickers, Outcomes Management v2.0, 1EdTech Consortium, December 2014. [http://www.imsglobal.org/lti/].

[CIa, 15] S Vickers, Content-Item Message, 1EdTech Consortium, May 2016. [http://www.imsglobal.org/lti/].

[CIb, 15] S Vickers, Content Items in the application/vnd.ims.lti.v1.contentitems+json format, 1EdTech Consortium, May 2016. [http://www.imsglobal.org/lti/].

[OAuth, 10] The OAuth 1.0 Protocol, E. Hammer-Lahav. Retrieved 24 May 2016 from [http://tools.ietf.org/html/rfc5849].

2 Behavioral Model

The Content-Item message provides a method for transferring content between systems. A content item can be anything which is accessed via a URL, or can be static content captured completely within the media type. In addition to the generic class, two specific types of content item are defined, one representing a file and one an LTI launch link. In each case, a content item may include advice on how it is best presented to users for display. This element would be omitted when the content is merely being passed for consumption by the recipient system and not to insert into a content page; for example, a homework file.

Figure 2.1 Content-Item model

Content-Item model diagram

3 Information Model

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).

3.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).

<form action="http://www.tp.com/lti" method="post" encType="application/x-www-form-urlencoded">
  <input type="hidden" name="lti_message_type" value="ContentItemSelectionRequest" />
  <input type="hidden" name="lti_version" value="LTI-1p0" />
  <input type="hidden" name="user_id" value="29123" />
  <input type="hidden" name="roles" value="Instructor" />
  <input type="hidden" name="lis_person_name_full" value="John Logie Baird" />
  <input type="hidden" name="lis_person_name_family" value="Baird" />
  <input type="hidden" name="lis_person_name_given" value="John" />
  <input type="hidden" name="lis_person_contact_email_primary" value="jbaird@uni.edu" />
  <input type="hidden" name="context_id" value="S3294476" />
  <input type="hidden" name="context_type" value="CourseSection" />
  <input type="hidden" name="context_title" value="Telecommunications 101" />
  <input type="hidden" name="context_label" value="ST101" />
  <input type="hidden" name="lis_course_section_sourcedid" value="DD-ST101:C1" />
  <input type="hidden" name="tool_consumer_info_product_family_code" value="ims" />
  <input type="hidden" name="tool_consumer_info_version" value="1.2" />
  <input type="hidden" name="tool_consumer_instance_guid" value="imsglobal.org" />
  <input type="hidden" name="tool_consumer_instance_name" value="Learning Impact Leadership Institute" />
  <input type="hidden" name="launch_presentation_document_target" value="frame" />
  <input type="hidden" name="accept_media_types" value="*/*" />
  <input type="hidden" name="accept_presentation_document_targets" value="none,embed,frame,iframe,window,popup,overlay" />
  <input type="hidden" name="content_item_return_url" value="http://www.tc.com/item-return" />
  <input type="hidden" name="accept_unsigned" value="false" />
  <input type="hidden" name="accept_multiple" value="true" />
  <input type="hidden" name="auto_create" value="false" />
  <input type="hidden" name="data" value="Some opaque TC data" />
  <input type="hidden" name="oauth_version" value="1.0" />
  <input type="hidden" name="oauth_nonce" value="..." />
  <input type="hidden" name="oauth_timestamp" value="..." />
  <input type="hidden" name="oauth_consumer_key" value="..." />
  <input type="hidden" name="oauth_callback" value="about:blank" />
  <input type="hidden" name="oauth_signature_method" value="HMAC-SHA1" />
  <input type="hidden" name="oauth_signature" value="..." />
</form>

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).

3.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/ContentItem",
  "@graph" : [
    { "@type" : "FileItem",
      "url" : "https://www.imsglobal.org/sites/default/files/IMSconformancelogosm.png",
      "mediaType" : "image/png",
      "text" : "1EdTech logo for certified products",
      "title" : "The logo used to identify 1EdTech certified products",
      "placementAdvice" : {
        "displayWidth" : 147,
        "displayHeight" : 184,
        "presentationDocumentTarget" : "embed"
      }
    }
  ]
}

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).

<form action="http://www.tc.com/item-return" method="post"
 encType="application/x-www-form-urlencoded">
  <input type="hidden" name="lti_message_type" value="ContentItemSelection" />
  <input type="hidden" name="lti_version" value="LTI-1p0" />
  <input type="hidden" name="content_items" value="{ &quot;@context&quot;: &quot;http://purl.imsglobal.org/ctx/lti/v1/ContentItem&quot;, &quot;@graph&quot;: [ { &quot;@type&quot;: &quot;FileItem&quot;, &quot;url&quot;: &quot;https://www.imsglobal.org/sites/default/files/IMSconformancelogosm.png&quot;, &quot;mediaType&quot;: &quot;image/png&quot;, &quot;text&quot;: &quot;1EdTech logo for certified products&quot;, &quot;title&quot;: &quot;The logo used to identify 1EdTech certified products&quot;, &quot;placementAdvice&quot;: { &quot;displayWidth&quot;: 147, &quot;displayHeight&quot;: 184, &quot;presentationDocumentTarget&quot;: &quot;embed&quot; } } ] }" />
  <input type="hidden" name="data" value="Some opaque TC data" />
  <input type="hidden" name="oauth_version" value="1.0" />
  <input type="hidden" name="oauth_nonce" value="..." />
  <input type="hidden" name="oauth_timestamp" value="..." />
  <input type="hidden" name="oauth_consumer_key" value="..." />
  <input type="hidden" name="oauth_callback" value="about:blank" />
  <input type="hidden" name="oauth_signature_method" value="HMAC-SHA1" />
  <input type="hidden" name="oauth_signature" value="..." />
</form>

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.3 Request to Tool Provider

3.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.ltilink,application/vnd.ims.lti.v1.ltiassignment,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.ltilink is used to represent an LTI launch request to a TP. For an LTI link which represents an assignment (an activity which involves a submission by learners) a MIME type of application/vnd.ims.lti.v1.ltiassignment should be used. This parameter should use the same format as the Accept header in HTTP requests [HTTP, 14]. 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. To accept any media type except an LTI link, a header of "application/vnd.ims.lti.v1.ltilink; q=0, */*" could be used.

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 presentationDocumentTarget element for a returned content item). 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).
none – the item is not intended for display but for storing or processing (for example, an assignment submission may just be stored without a link to it being added to the course).

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.

auto_create=false | true (Optional)

This indicates whether any content items returned by the TP would be automatically persisted without any option for the user to cancel the operation. This parameter is optional; when omitted a value of false should be assumed (i.e. items returned may not be persisted at the TC end).

title=... (Optional)

Default text to be used as the title or alt text for the content item returned by the TP. This value should normally be short in length, for example, suitable for use as a heading.

text=... (Optional)

Default text to be used as the visible text for the content item returned by the TP. If no text is returned by the TP, the TC may use the value of the title parameter instead (if any). This value may be a long description of the content item.

data=... (Optional)

An opaque value which should be returned by the TP in its response.

Additional Fields

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.

3.4 Response to Tool Consumer

3.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=ContentItemSelection (Required)

This indicates that this is a message containing an array of content items.

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. The accompanying HTML documentation defines the application/vnd.ims.lti.v1.contentitems+json media type used by this parameter. For example, the content_items parameter may have a value of:

{
  "@context" : "http://purl.imsglobal.org/ctx/lti/v1/ContentItem",
  "@graph" : [
    { "@type" : "ContentItem",
      "@id" : ":item1",
      "url" : "http://www.imsglobal.org",
      "title" : "The 1EdTech website",
      "mediaType" : "text/html"
    },
    { "@type" : "LtiLinkItem",
      "@id" : ":item2",
      "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
      },
      "title" : "Open sIMSon application",
      "text" : "The &lt;em&gt;sIMSon&lt;/em&gt; application provides a collaborative space for developing semantic modelling skills.",
      "mediaType" : "application/vnd.ims.lti.v1.ltilink",
      "custom" : {
        "level" : "novice",
        "mode" : "interactive"
      },
      "placementAdvice" : {
        "presentationDocumentTarget" : "window",
        "windowTarget" : "anLTIApp"
      }
    },
    { "@type" : "FileItem",
      "@id" : ":item3",
      "url" : "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",
      "copyAdvice" : false,
      "placementAdvice" : {
        "displayWidth" : 800,
        "presentationDocumentTarget" : "iframe",
        "displayHeight" : 600
      }
    }
  ]
}

The structure of each element in the array could be different for each type of content item (see below) but should appear in the order in which they are to be processed by the TC. If no content items were selected, then the parameter may have a value of:

{
  "@context" : "http://purl.imsglobal.org/ctx/lti/v1/ContentItem",
  "@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¹ 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]).

3.4.2 Content-Item Elements

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

@id (Optional)

A unique identifier to use for the item. The value of this element may be changed in different messages even if the entry refers to the same actual item or resource. The content item is merely the metadata for an item and not the item itself.

mediaType (Required)

This element describes the type of content item. It should have a value of the MIME type for the content item.

url (Optional)

A fully qualified URL to use for the item. When not specified for a content item of type application/vnd.ims.lti.v1.ltilink 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.ltilink.

presentationDocumentTarget (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.

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 presentationDocumentTarget element (see above) which is used to determine how the content item is opened. This parameter is most useful when a presentationDocumentTarget of window is specified.

title (Optional)

The text to use as the title or heading for the content item. ²

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. When not provided, a TC may use the value of the title 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.

hideOnCreate=false | true (Optional)

An element with a boolean value for which true would indicate to the Tool Consumer that the item should be set as not being visible to learners when it is created. The default value for this element is false and it is only advisory for Tool Consumers.

available (Optional)

An element which can include a startDatetime and/or an endDatetime element which define when the item should become accessible to learners and when it should not be, respectively. A TC may choose to make an item not accessible by hiding it, or by disabling the link, or some other method which prevents the link from being opened by a learner. Both elements should have values which are combined date and time in the format of ISO 8601; i.e. YYYY-MM-DDThh:mm:ssTZD. The time is denoted in Coordinated Universal Time (UTC) with TZD denoting the time zone offset in hours and minutes with respect to UTC.

noUpdate=false | true (Optional)

This parameter indicates whether the content-item can be updated using a ContentItemUpdateRequest message. When true the TC may make an update option available for the item but this must not generate a ContentItemUpdateRequest message to the TP, even if the message type is supported and available for the tool. If the value is false, and support is provided by the TP for the ContentItemUpdateRequest message, the TC should provide an update option for the link which generates a ContentItemUpdateRequest message to the TP. If the TP has not offered support for the ContentItemUpdateRequest message the TC should offer its only internal update facility for the link. The default value for this parameter is false. This parameter only applies to content items of type application/vnd.ims.lti.v1.ltilink or application/vnd.ims.lti.v1.ltiassignment.

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.ltilink or application/vnd.ims.lti.v1.ltiassignment. A custom parameter specified here must be treated in the same way as if the custom parameter had been manually associated with the resource link within the Tool Consumer by a user (such as an instructor). Thus, if a custom parameter is specified with the same name as one which has already been manually defined for the resource link, the latter should be overwritten.

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

3.4.3 LTI Assignment Content-Item Elements

An LTI assignment is an LTI link which connects to an activity which can be assigned to users to complete. It would normally be expected to have a line-item associated with it so that the outcome of the user can be returned. LTI assignment content items are identified by a media type of application/vnd.ims.lti.v1.ltiassignment and may also include the following element:

submission (Optional)

An element which can include a startDatetime and/or an endDatetime element which define when the assignment may first be submitted by learners and when it ceases to be submittable, respectively. These values may be different from the availability dates but are expected to fall inside the available dates if both are specified. Both elements should have values which are combined date and time in the format of ISO 8601; i.e. YYYY-MM-DDThh:mm:ssTZD. The time is denoted in Coordinated Universal Time (UTC) with TZD denoting the time zone offset in hours and minutes with respect to UTC. It is the responsibility of the TP to enforce the submission dates, which could be overridden for individual users.

3.4.4 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).

LTI Launch Link

The following example should add an image and the text "Week 1 reading" 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" : "LtiLinkItem",
  "mediaType" : "application/vnd.ims.lti.v1.ltilink",
  "icon" : {
    "@id" : "https://www.server.com/path/animage.png",
    "width" : 50,
    "height" : 50
  },
  "title" : "Week 1 reading",
  "text" : "Read this section prior to your tutorial.",
  "available" : {
    "startDatetime" : "2016-10-31T19:20:30Z",
    "endDatetime" : "2016-12-01T00:00:00Z"
  },
  "custom" : {
    "chapter" : "12",
    "section" : "3"
  }
}

It should only be visible to learners after the specified start date and until the specified end date.

Hyperlink with Thumbnail

The following example should add an image and the text "1EdTech 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" : "ContentItem",
  "url" : "http://imscatalog.org/",
  "mediaType" : "text/html",
  "thumbnail" : {
    "@id" : "http://developers.imsglobal.org/images/imscertifiedsm.png",
    "width" : 147,
    "height" : 184
  },
  "title" : "1EdTech catalog of certified products",
  "hideOnCreate" : true,
  "available" : {
    "startDatetime" : "2016-10-31T19:20:30Z",
    "endDatetime" : "2017-10-31T19:20:30Z"
  }
  "placementAdvice" : {
    "presentationDocumentTarget" : "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 1EdTech catalog of certified products in a new window">
  <img src="http://developers.imsglobal.org/images/imscertifiedsm.png"
   alt="1EdTech catalog of certified products"
   width="147" height="184" />&nbsp;1EdTech catalog of certified products
</a>

It should initially be hidden from access by learners even if the start date/time has passed and, once made available, it should only remain so until the specified end date/time.

Embedded Image

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

{
  "@type" : "ContentItem",
  "url" : "http://developers.imsglobal.org/images/imscertifiedsm.png",
  "mediaType" : "image/png",
  "title" : "1EdTech logo for certified products",
  "placementAdvice" : {
    "displayWidth" : 147,
    "displayHeight" : 184,
    "presentationDocumentTarget" : "embed",
    "windowTarget" : "_blank"
  }
}

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

  <img src="http://developers.imsglobal.org/images/imscertifiedsm.png"
   alt="1EdTech logo for certified products"
   width="147" height="184" />

Embedded HTML

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

{
  "@type" : "ContentItem",
  "mediaType" : "text/html",
  "text" : "<p>1EdTech has a <a href=\" http://imscatalog.org/\">catalog of certified products</a> available on their website</p>",
  "placementAdvice" : {
    "presentationDocumentTarget" : "embed"
  }
}

Hyperlink to Local Copy of a File

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

{
  "@type" : "FileItem",
  "url" : "http://www.imsglobal.org/xsd/qti/qtiv2p1/imsqti_v2p1.xsd",
  "copyAdvice" : "true",
  "expiresAt" : "2014-03-05T00:00:00Z",
  "mediaType" : "application/xml",
  "title" : "QTI v2.1 Specification Information Model",
  "placementAdvice" : {
    "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>

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/ContentItem",
    {
      "educationalUse" : "http://schema.org/educationalUse"
    }
  ],
  "@graph" : [
    { "@type" : "LtiLinkItem",
      "text" : "The &lt;em&gt;sIMSon&lt;/em&gt; application provides a collaborative space for developing semantic modelling skills.",
      "mediaType" : "application/vnd.ims.lti.v1.ltilink",
      "title" : "Open sIMSon application",
      "placementAdvice" : {
        "windowTarget" : "anLTIApp",
        "educationalUse" : "group work"
      }
    }
  ]
}

LTI Launch Link with Outcomes Support

It is possible to return an LTI launch link with a request to have it be associated with a line item in the gradebook by including a description of the line item within the LtiLinkItem element. It uses the same technique as the previous example to re-use the LineItem type from the Outcomes Management specification [LTI, 14 OM]. When persisting this content item, the tool consumer should also create a column in the gradebook to achieve the same end result as when an LTI 1 tool which supports the Outcomes service is manually added.

{
  "@context" : [
    "http://purl.imsglobal.org/ctx/lti/v1/ContentItem",
    {
      "lineItem" : "http://purl.imsglobal.org/ctx/lis/v2/LineItem",
      "res" : "http://purl.imsglobal.org/ctx/lis/v2p1/Result#"
    }
  ],
  "@graph" : [
    { "@type" : "LtiLinkItem",
      "mediaType" : "application/vnd.ims.lti.v1.ltilink",
      "title" : "Chapter 12 quiz",
      "lineItem" : {
        "@type" : "LineItem",
        "label" : "Chapter 12 quiz",
        "reportingMethod" : "res:totalScore",
        "assignedActivity" : {
          "@id" : "http://toolprovider.example.com/assessment/66400",
          "activity_id" : "a-9334df-33"
        },
        "scoreConstraints" : {
          "@type" : "NumericLimits",
          "normalMaximum" : 100,
          "extraCreditMaximum" : 10,
          "totalMaximum" : 110
        }
      }
    }
  ]
}

LTI Assignment

The following example should create a hyperlink with the text "LTI assignment" at the current insertion point in the TC. The hyperlink should cause an LTI launch to the tool provider which includes the id custom parameter:

{
  "@type" : "LtiLinkItem",
  "mediaType" : "application/vnd.ims.lti.v1.ltiassignment",
  "title" : "LTI assignment",
  "available" : {
    "startDatetime" : "2016-10-31T19:20:30Z"
  },
  "submission" : {
    "startDatetime" : "2016-11-07T00:00:00Z",
    "endDatetime" : "2016-12-01T00:00:00Z"
  },
  "custom" : {
    "id" : "33490efkno4509jkl"
  }
}

It should only be visible to learners after the specified start date and shown as only being available for a submission between the specified dates.

3.5 Content-Item Capabilities

A TC can declare its support for the Content-Item message and its related parameters by including their capability names in the capability_offered section of its profile. The mapping between a message parameter and a capability name is given in the following table.

Table 3.1 - Content-Item capability name mapping

Parameter Name	Capability Name
lti_message_type	ContentItemSelectionRequest
accept_media_types	ContentItem.acceptTypes
accept_presentation_document_targets	ContentItem.acceptTargets
content_item_return_url	ContentItem.returnUrl
accept_unsigned	ContentItem.acceptUnsigned
accept_multiple	ContentItem.acceptMultiple
auto_create	ContentItem.autocreate
data	ContentItem.data

In addition the elements which can be defined for an LTI link are also available to be passed in messages by the custom parameter substitution variables given in the following table.

Table 3.2 - Content-Item element substitution variables

Element Name	Custom Parameter Substitution Variable Name
available.startDateTime	ResourceLink.available.startDateTime
available.endDateTime	ResourceLink.available.endDateTime
submission.startDateTime	ResourceLink.submission.startDateTime
submission.endDateTime	ResourceLink.submission.endDateTime

No variable is defined for the following elements:

copyAdvice
expiresAt
hideOnCreate
icon
mediaType
placementAdvice (for the actual placement use the Message.documentTarget, Message.height and Message.width variables)
text (use the ResourceLink.description variable)
thumbnail (this may be embedded in the ResourceLink.description value)
title (use the ResourceLink.title variable)
url

3.6 Updating LTI Links

A message type of ContentItemUpdateRequest is provided to allow TCs to connect to a TP when the details of an LTI link require updating. Typically this link would have been created using the ContentItemSelectionRequest message, but this need not be the case; the only requirement is that the TP supports the ContentItemUpdateRequest message type. Note that this message type can only be used for updating LTI links (including LTI assignments) and not any other types of content item which may have been created via a ContentItemSelectionRequest message (such as static HTML). In addition, the ContentItemUpdateRequest message is sent to the TP which would be launched by the link; this may be different from the TP that created the content item.

3.6.1 Form Fields

A ContentItemUpdateRequest message is very similar to the ContentItemSelectionRequest message. The 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=ContentItemUpdateRequest (Required)

This indicates that this request represents a content-item update 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.ltilink (Required)

This parameter should have a value of application/vnd.ims.lti.v1.ltilink or application/vnd.ims.lti.v1.ltiassignment to represent an LTI link to the TP.

accept_presentation_document_targets=embed,frame,iframe,window,popup,overlay (Required)

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).
none – the item is not intended for display but for storing or processing (for example, an assignment submission may just be stored without a link to it being added to the course).

Since the item will already exist for this message to be sent, this parameter should normally just be set to the value used when the item was created. However, if a TC wishes to allow this setting to be changed, it may include the other alternatives available for the TP to select from.

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)

accept_multiple=false (Optional)

This message type can only update one item at a time so this parameter should always have a value of false or be omitted as this is the default value.

accept_copy_advice=false | true (Optional)

This parameter should have a value of false or be omitted.

auto_create=true (Optional)

title=... (Optional)

Default text to be used as the title or alt text for the content item returned by the TP. This value should normally be short in length, for example, suitable for use as a heading.

text=... (Optional)

data=... (Optional)

An opaque value which should be returned by the TP in its response.

Additional Fields

The TC should also pass the other parameters about the tool consumer, the user, the context, the resource link and the user's roles which would be included in a launch request message (see [LTI, 11, Basic Launch Data]). Note that, unlike the ContentItemSelectionRequest message, this could include the following parameters as the link already exists:

resource_link_id
resource_link_title
resource_link_description

However, the following parameters should not be passed:

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.

Sending the Message

The ContentItemUpdateRequest message is sent in the same way as a ContentItemSelectionRequest message (see above). It must always be signed.

Handling by the Tool Provider

On receipt of a ContentItemUpdateRequest message, the TP should use the content item to update its own record of the item and then provide an interface to allow the user to edit the item including any elements which are specific to the TP. This is likely to be similar to the original form provided when the item was created. It is expected that the TP will be able to identify the item being updated from either a custom parameter inserted by the TP when it was created or from the resource link ID. Once the user has completed updating the item, a copy should be persisted by the TP and the user redirected back to the TC using the ContentItemSelection message in the same way as the conclusion of a ContentItemSelectionRequest workflow. If no changes were made, the item should be returned to the TC unchanged. The following elements should not be included in the content item:

copyAdvice
expiresAt

as they are not relevant to an LTI link.

About this Document

Summary

Title: 1EdTech LTI Content-Item Message

Editor: Stephen Vickers (1EdTech)

Version: 1.0

Version Date: 24 May 2016

Status: Final

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

Document Location: http://www.imsglobal.org/specs/lticiv1p0

List of Contributors

The following individuals contributed to the development of this document:

Name	Organization
Viktor Haag	D2L
Brad Humphrey	Instructure
Greg McFall	Pearson
Nathan Mills	Instructure
Bracken Mosbacker	Instructure
Claude Vervoort	Cengage
Stephen Vickers	1EdTech
Brian Whitmer	Instructure

Revision History

Version No.	Release Date	Comments
Public Draft 1.0	3 February 2015
Candidate Final Draft 1.0	2 May 2016
	4 May 2016	Removed option to confirm persistence, left for a future release
Final v1.0	24 May 2016

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

1EdTech 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.

1EdTech would appreciate receiving your comments and suggestions.

Please contact 1EdTech through our website at https/www.imsglobal.org.

Please refer to Document Name: 1EdTech Learning Tools Interoperability Content-Item Message v1.0

Date: 24 May 2016

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. ↩︎
This value may be HTML or plain text; in the latter case the TC should wrap the value within a pair of appropriate tags before rendering it, for example, <p> or <div> tags. It should also apply its standard santizing code to the value to make safe any content which may cause a security threat. ↩︎ ↩︎

Learning Tools Interoperability Deep Linking

1EdTech Learning Tools Interoperability® Content-Item Message

Version 1.0 Final

IPR and Distribution Notices

1 Introduction

1.1 Scope

1.2 References

2 Behavioral Model

Figure 2.1 Content-Item model

3 Information Model

3.1 Example Request

3.2 Example Response

3.3 Request to Tool Provider

3.3.1 Form Fields

Additional Fields

3.4 Response to Tool Consumer

3.4.1 Form Fields

3.4.2 Content-Item Elements

3.4.3 LTI Assignment Content-Item Elements

3.4.4 Example Responses

LTI Launch Link

Hyperlink with Thumbnail

Embedded Image

Embedded HTML

Hyperlink to Local Copy of a File

Example including Elements from Other Contexts (e.g. Metadata)

LTI Launch Link with Outcomes Support

LTI Assignment

3.5 Content-Item Capabilities

Table 3.1 - Content-Item capability name mapping

Table 3.2 - Content-Item element substitution variables

3.6 Updating LTI Links

3.6.1 Form Fields

Additional Fields

Sending the Message

Handling by the Tool Provider

About this Document

Summary

List of Contributors

Revision History

1EdTech Learning Tools Interoperability^® Content-Item Message