Introduction

External tools can be associated with Canvas assignments so that students are able to experience an integrated offering of the tool. Tools can also leverage LTI services to return submissions and/or scores back to the Canvas gradebook.

The specifics for how grading is achieved depend on the LTI version being used:

Tools become associated with Canvas assignments either through the UI during assignment creation, or by the tool using the Line Items Service to create assignments.

If configured in via the Canvas UI, Course Designers (Admins/Instructors) will see a submission type called "External Tool" during assignment creation where they can select a tool configuration to use for the assignment. The assignment_selection placement is often used in conjunction with the deep linking specification to allow an Instructor or Course Designer to launch out to the tool and select a specific resource to be associated to the assignment. When students view the assignment, instead of seeing a standard Canvas assignment they'll see the tool loaded in an iframe on the page.

LTI Advantage: Assignment and Grading Services

LTI 1.3 tools can be configured to have access to the Assignment and Grading Services (AGS). Assignment and Grading Services are a powerful way for tools to interact with the LMS gradebook to save time for instructors and students.

Some examples of use cases that are uniquely solvable using AGS that were not resolvable by the LTI 1.1 Outcomes Service include:

In addition to permitting these use cases, many more use cases are described in the IMS LTI Advantage Implementation Guide.

Configuring

To configure an LTI 1.3 tool that has access to AGS, an LTI Developer Key must be created with the desired scopes enabled. This can either be done via the "Manual" method, or by providing raw JSON or a secure URL that hosts JSON. A full list and description of available scopes is described in the AGS documentation.

For example, the following JSON would create an LTI 1.3 tool that has access to read and write scores, check for existing scores, and manage line items (ex. assignments) that are associated with the tool:

{  
   "title":"Cool AGS Tool ",
   "scopes":[
      "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
      "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
      "https://purl.imsglobal.org/spec/lti-ags/scope/score"
      ],
   "extensions":[  
      {  
         "domain":"agsexample.com",
         "tool_id":"ags-tool-123",
         "platform":"canvas.instructure.com",
         "settings":{  
            "text":"Cool AGS Text",
            "icon_url":"https://some.icon.url",
            "placements":[                 
               {  
                  "text":"Embed Tool Content as a Canvas Assignment",
                  "enabled":true,
                  "icon_url":"https://some.icon.url",
                  "placement":"assignment_selection",
                  "message_type":"LtiDeepLinkingRequest",
                  "target_link_uri":"https://your.target_link_uri/deeplinkexample"
               }
            ]
         }
      }
   ],
   "public_jwk":{  
      "kty":"RSA",
      "alg":"RS256",
      "e":"AQAB",
      "kid":"8f796169-0ac4-48a3-a202-fa4f3d814fcd",
      "n":"nZD7QWmIwj-3N_RZ1qJjX6CdibU87y2l02yMay4KunambalP9g0fU9yZLwLX9WYJINcXZDUf6QeZ-SSbblET-h8Q4OvfSQ7iuu0WqcvBGy8M0qoZ7I-NiChw8dyybMJHgpiP_AyxpCQnp3bQ6829kb3fopbb4cAkOilwVRBYPhRLboXma0cwcllJHPLvMp1oGa7Ad8osmmJhXhM9qdFFASg_OCQdPnYVzp8gOFeOGwlXfSFEgt5vgeU25E-ycUOREcnP7BnMUk7wpwYqlE537LWGOV5z_1Dqcqc9LmN-z4HmNV7b23QZW4_mzKIOY4IqjmnUGgLU9ycFj5YGDCts7Q",
      "use":"sig"
   },
   "description":"1.3 Test Tool",
   "target_link_uri":"https://your.target_link_uri",
   "oidc_initiation_url":"https://your.oidc_initiation_url"
}

NOTE: Using AGS does not require configuration of any specific placements, so the placement(s) here could be any placement(s).

Available Services

Canvas supports the following AGS services:

Accessing AGS

Before a tool can run AGS requests, it must be available in the course that it wishes to interact with, and also complete the OAuth2 Client Credentials grant to obtain an access token. This covered in depth in the IMS LTI Security Framework, SEC 4.

Extensions

Canvas has extended several AGS endpoints to support deeper grading integrations. Here, we will focus on these extensions and describe how tools can be configured to leverage AGS in Canvas.

Line Item Extension: Creating deep linked assignments

The Line Item service has been extended to allow an external tool to not only create gradebook columns (i.e. assignments) in Canvas, but also connect the column/assignment to a specific LTI resource on the external tool. This means that when the student accesses the assignment from Canvas, they are able to see the external tool content directly in the page, complete their assessment on the tool side, and have grades returned without the instructor having to manually create assignments in Canvas.

This also allows tools to introduce new workflows, such as allowing instructors to launch from a Course Navigation Placement, select multiple resources, and import them into their course.

Score Extension: Creating submission data

The Score service has been extended to allow an external tool to submission data back to the Canvas Gradebook. This data is then exposed in the Submission Details and Speedgrader Views so that both students and teachers can see what was submitted to the external tool without leaving Canvas. Support for basic urls, text, and LTI links are supported.

LTI 1.1 Grade Passback Tools

Tools can know that they have been launched in a graded context because additional parameters are sent across when a student accesses the external tool assignment. Specifically, the lis_outcome_service_url and lis_result_sourced_id are sent as specified in the LTI 1.1 specification. Grades are passed back to Canvas from the tool's servers using the outcomes component of LTI 1.1. Notably, one of the major limitations of the LTI 1.1 Outcomes Service is the inability of tools to return grades before a student accesses the assignment from Canvas. If this functionality is desirable,

you should upgrade to LTI Advantage's Assignment and Grading Services.

Data Return Extension

Canvas sends an extension parameter for assignment launches that allows the tool provider to pass back values as submission text in canvas. The key is ext_outcome_data_values_accepted and the value is a comma separated list of types of data accepted. The currently available data types are url and text. The added launch parameter will look like this:

ext_outcome_data_values_accepted=url,text

Returning Data Values from Tool Provider

If the external tool wants to supply these values, it can augment the POX sent with the grading value. LTI replaceResult POX

Only one type of resultData should be sent, if multiple types are sent the tool consumer behavior is undefined and is implementation-specific. Canvas will take the text value and ignore the url value if both are sent.

Text

Add a resultData node with a text node of plain text in the same encoding as the rest of the document within it like this:

<?xml version = "1.0" encoding = "UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>3124567</sourcedId>
        </sourcedGUID>
        <result>
          <resultScore>
            <language>en</language>
            <textString>0.92</textString>
          </resultScore>
          <!-- Added element -->
          <resultData>
            <text>text data for canvas submission</text>
          </resultData>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
</imsx_POXEnvelopeRequest>

URL

Add a resultData node with a url node within it like this:

<?xml version = "1.0" encoding = "UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>3124567</sourcedId>
        </sourcedGUID>
        <result>
          <resultScore>
            <language>en</language>
            <textString>0.92</textString>
          </resultScore>
          <!-- Added element -->
          <resultData>
            <url>https://www.example.com/cool_lti_link_submission</url>
          </resultData>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
</imsx_POXEnvelopeRequest>

LTI Launch URL

Add a resultData node with a ltiLaunchUrl node like this:

<?xml version = "1.0" encoding = "UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>3124567</sourcedId>
        </sourcedGUID>
        <result>
          <resultScore>
            <language>en</language>
            <textString>0.92</textString>
          </resultScore>
          <!-- Added element -->
          <resultData>
            <ltiLaunchUrl>https://some.launch.url/launch?lti_submission_id=42</ltiLaunchUrl>
          </resultData>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
</imsx_POXEnvelopeRequest>

Total Score Return Extension

Canvas sends an extension parameter for assignment launches that allows the tool provider to pass back a raw score value instead of a percentage. The key is ext_outcome_result_total_score_accepted and the value is true. The added launch parameter will look like this:

ext_outcome_result_total_score_accepted=true

Returning Total Score from Tool Provider

If the external tool wants to supply this value, it can augment the POX sent with the grading value. LTI replaceResult POX

Simply add a node called resultTotalScore instead of resultScore. If both are sent, then resultScore will be ignored. The textString value should be an Integer or Float value.

<?xml version = "1.0" encoding = "UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>3124567</sourcedId>
        </sourcedGUID>
        <result>
          <!-- Added element -->
          <resultTotalScore>
            <language>en</language>
            <textString>50</textString>
          </resultTotalScore>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
</imsx_POXEnvelopeRequest>

Submission Details Return Extension

Canvas sends an extension parameter for assignment launches that allows the tool provider to pass back submission metadata not directly related to the result.

Details about the submission the external tool wants to supply should augment the POX sent with the grading value. LTI replaceResult POX Simply add a node called submissionDetails to the replaceResultRequest node. Any data regarding the submission that is not related directly to the result will be included in this node.

<?xml version = "1.0" encoding = "UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <!-- Added element -->
      <submissionDetails>
        ...
      </submissionDetails>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>3124567</sourcedId>
        </sourcedGUID>
        <result>
          <resultScore>
            <language>en</language>
            <textString>0.92</textString>
          </resultScore>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
</imsx_POXEnvelopeRequest>

Submission Submitted At Timestamp Extension

Canvas sends an extension parameter for assignment launches that allows the tool provider to pass back the submission submitted at timestamp. The key is ext_outcome_submission_submitted_at_accepted and the value is true. The added launch parameter will look like this:

ext_outcome_submission_submitted_at_accepted=true

Submission Submitted At Timestamp from Tool Provider

If the external tool wants to supply this value, it can augment the POX sent with the submission submitted at value. LTI replaceResult POX

Simply add a node called submittedAt to the submissionDetails node. The text string must be an iso8601 formatted timestamp. If included, then it will override any existing submitted_at value on the submission even when result score or result total score are not present.

<?xml version = "1.0" encoding = "UTF-8"?>
<imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <submissionDetails>
        <!-- Added element -->
        <submittedAt>
          2017-04-16T18:54:36.736+00:00
        </submittedAt>
      </submissionDetails>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>3124567</sourcedId>
        </sourcedGUID>
        <result>
          <resultScore>
            <language>en</language>
            <textString>0.92</textString>
          </resultScore>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
</imsx_POXEnvelopeRequest>