Overview
Last updated
Was this helpful?
Last updated
Was this helpful?
The plagiarism detection platform provides a standard way for LTI2 tool providers (TPs) to seamlessly integrate plagiarism detection tools with Canvas. Part of this platform is the introduction of Originality Reports which can be created, edited, and retrieved by TPs. TPs are also given a means of subscribing to webhooks to notify them of changes to assignments and submissions.
This document provides details to guide TPs toward leveraging the plagiarism detection platform. The document is divided into three sections that cover the plagiarism detection platform:
TPs leveraging the new plagiarism detection platform must go through the standard LTI2 registration flow, with some additional steps along the way. Canvas will automatically create a subscription on behalf of the tool for a submissions webhook, allowing the TP to be notified when a submission has been made. (See .)
Once registered, tools will be provided with an LTI tool placement in the Canvas assignment create/edit UI to launch a configuration page.
The webhook sent to the TP contains the data needed for the tool to retrieve the submission from Canvas. The TP can then process the submission, determine its "originality score", and create an Originality Report. This data is then sent back to Canvas and associated with the submission via the Canvas Originality Report API.
Descriptions of optional features tool providers may use.
For additional help please see the following reference tools:
Canvas’ plagiarism platform requires the TP to support LTI2 and obtain a Canvas developer key. During the standard LTI2 registration flow, the TP should take the following steps:
Include a JWT access token in the Authorization header of the request to get the Tool Consumer Profile (see section 1.1).
Add the Canvas.placements.similarityDetection capability to the Tool Profile’s Resource Handler enabled capabilities (See section 1.2).
Add the vnd.Canvas.OriginalityReport service to the Tool Proxy’s Security Contract (see section 1.3).
Add the Security.splitSecret capability to the Tool Proxy’s enabled capabilities (see section 1.4).
Include a JWT access token in the Authorization header of the Tool Proxy create POST request (see section 1.5).
Canvas will include a restricted set of services/capabilities in the TCP if the request to retrieve the TCP contains a JWT access token in the Authorization header.
Canvas requires that the TP use the following restricted capabilities/services:
vnd.Canvas.OriginalityReport service
vnd.Canvas.submission service
Canvas.placements.similarityDetection capability
Tool Providers who wish to use the plagiarism detection platform must add the similarity detection placement capability to the Tool Profile’s Resource Handler:
This placement is listed in the TCP request as described in section 1.1:
Note that the Canvas.placements.similarityDetection capability should be enabled in both the resource handler and in the enabled_capability array at the root of the tool proxy.
The following example security contract shows the services required to use the plagiarism platform:
For each tool service object, the service field must match the @id of the service given in the TCP (see section 1.1) and the value of action must be a subset of the actions provided in the TCP (see section 1.1).
The Security.splitSecret capability must be used by the TP when using the similarity detection platform in Canvas. Specify this capability in the Tool Proxy:
The following excerpt regarding the split secret capability is from the LTI 2.1 Implementation Guide (in draft) and may change in the future:
The shared secret is used to digitally sign launch requests in accordance with the OAuth [sic]. If the Tool Consumer offers a capability of
Security.splitSecretand this is enabled in the Tool Proxy, then the security contract should include an element namedtp_half_shared_secretwith a value of 128 hexadecimal characters (all in lowercase). This represents the second half of the string to use as the shared secret; the first half will be generated by the Tool Consumer and passed to the Tool Provider in its acceptance response (see section 10.1) as a parameter namedtc_half_shared_secret(along with the Tool Proxy GUID value); this should also be a 128 string of lowercase hexadecimal characters. Each 128-character hexadecimal string should be generated from 64 bytes of random data. If the split secret capability was not offered or enabled, then the security contract should include the full shared secret in an element namedshared_secret. The Tool Proxy should never contain both thetp_half_shared_secretandshared_secretelements; just one or the other.
Once a Tool Proxy is created Canvas will automatically create a subscription to notify the tool when submissions are created by students(see section 2.2).
Tools configured as described in section 1 of this document will be launchable from the assignment create/edit page in Canvas (see section 2.1).
Tools configured as described in section 1 of this document will be made available to assignments using “File Upload” or "Text Entry" submission types. Other submission types are not supported at this time. Once “File Upload” or "Text Entry" submission type is selected, a “Plagiarism Review” dropdown box becomes available so that the user can associate the assignment to the plagiarism tool. Note that the plagiarism platform feature flag must be enabled in Canvas.
Selecting a tool in the "Plagiarism Review" selector initiates a standard LTI launch to the launch URL provided in the resource handler during the registration phase (see 1.2). This launch is intended to allow configuration of the plagiarism review tool during the assignment creation process.
In addition to standard LTI parameters and variables requested by the TP for this launch, Canvas will send a parameter named ext_lti_assignment_id. This behavior will soon be deprecated. Instead please add the com.instructure.Assignment.lti.id capability to the same message that uses the Canvas.placements.similarityDetection capability. This parameter's value uniquely identifies the assignment and may be used by the TP to show the correct configuration options.
Webhooks from canvas are your way to know that a change has taken place (e.g. new or updated submission, change to assignment, etc).
Webhooks are available via HTTPS to an endpoint you own and specify, or via an AWS SQS queue that you provision, own, and specify. We recommend SQS for the most robust integration, but do support HTTPS for lower volume applications.
Webhooks that are sent but receive an unsuccessful response will be retried five times, waiting thirty seconds between attempts.
If you choose to use SQS transport, contact us for simple steps on how to grant Canvas write permissions to your queue or queues.
We do not duplicate or batch messages before transmission. Avoid creating multiple identical subscriptions. Webhooks always identify the ID of the subscription that caused them to be sent, allowing you to identify problematic or high volume subscriptions.
We cannot guarantee the transmission order of webhooks. If order is important to your application, you must check the “event_time” attribute in the “metadata” hash to determine the sequence that events occurred in Canvas.
While we strive to maintain very low latency, this is not guaranteed at all times, and applications should support delays of several minutes.
Additional JSON keys may be added in the future. Consumers should be permissive in what they accept in this regard.
Once a Tool Proxy is created that enables a plagiarism detection tool, a webhook subscription is automatically created and configured as specified by the SubmissionEvent service in the Tool Profile’s service_offered section. Below is an example of how to configure this service in the Tool Profile:
This automatic subscription will cause a webhook to be sent to the endpoint specified by the SubmissionEvent whenever a submission is created or updated or when a user clicks the “resubmit to plagiarism detection service” button in the Canvas UI.
HTTPS Webhooks will be transmitted over HTTPS via a POST request with a content type of application/json to the endpoint you specify in your subscriptions.
SQS Webhooks will contain the same JSON body as the body of the SQS Message.
After processing the submission, an Originality Report may be created for the submission.
The following are optional features the tool provider may wish to implement.
The plagiarism platform automatically handles most of the work required for course copy to work with TPs. When a Course that contains assignments associated with a plagiarism detection TP is copied in Canvas the following occurs:
The copies of assignments in the new course are automatically associated with the correct tool.
Tool Settings associated with the course are copied to the new course (See Using the LTI Tool Settings Service below).
These two actions will only occur if the same TP has been installed in the context the course is being copied to.
TPs often have a configuration that is set on a per-assignment basis via their UI by the instructor creating the assignment and stored by the TP. There are two ways of handling these TP configurations during a course copy: using reasonable defaults or using the LTI Tool Settings Service.
Option 1: Using Defaults
When receiving a submission_created webhook for an assignment that has never had an associated LTI launch, TP configuration items have not been set by the instructor. In these cases, TPs should use good defaults for any custom configuration they typically offer to instructors when configuring assignments. TPs may even wish to provide a resource handler that uses the Canvas.placements.accountNavigation placement in order to provide Canvas administrators the ability to set account-level default configurations.
Option 2: Using the LTI Tool Settings Service
The LTI Tool Settings service may be used as a key/value store associated with a particular LTI launch. This means that a TP may store their custom per-assignment configuration in a Tool Setting associated with the Canvas assignment. When a course is copied all Tool Settings will be copied to the new course and be associated with the proper assignments in the new context. The following describes how to create a Tool Setting associated with an assignment and leverage it for course copy:
Use LtiLink.custom.url variable expansion
Store assignment-level custom configuration in Tool Settings
When receiving a submission_created webhook for an unknown assignment, use the LTI assignment API to fetch assignment data
When receiving a submission_created webhook for an unknown assignment, use the lti_assignment_id and the Tool Setting Service to retrieve TP assignment-level configuration
1. Using LtiLink.custom.url
The LtiLink.custom.url variable expansion should be used in the same message handler that handles Canvas.placements.similarityDetection launches:
Canvas will then create a Tool Setting for the TP associated with the assignment when the Canvas.placements.similarityDetection launch occurs for the first time. This Tool Setting can be used to store TP specific assignment-level configuration that will be copied to the new context during a course copy.
2. Store assignment-level custom configuration in Tool Settings
Example Request:
When using the update endpoint the request body should contain JSON defining the key/value pairs the TP wishes Canvas to store in the Tool Setting. Canvas will replace the contents of the Tool Setting with whatever keys/values are sent in the request:
This endpoint is defined in the tool consumer profile.
3. use the LTI assignment API to fetch assignment data
4. use the lti_assignment_id and the Tool Setting Service to retrieve TP assignment-level configuration
If the TP has been leveraging Tool Settings in Canvas to store TP specific assignment-level configurations, those Tool Settings will be copied to the new assignment as well. To access the Tool Setting note the lti_assignment_id in the submission_created webhook. The Tool Setting that should be requested will have a resource_link_id that matches this value:
Example Request:
Response:
When a student submits to a group assignment, Canvas will send a submission_created webhook for each student in that group. The tool provider need only respond to one of these webhooks per group.
Canvas will copy any originality reports created for a group submission to every other student in the same group. Canvas will also propagate edits to any originality reports for a group submission to every other student in the same group.
The submission_created and subission_updated webhooks each contain a group_id that identifies what group a submission belongs to. Tool providers may use this value to make sure they only create one originality report per group.
Description
This feature provides a mechanism for a tool provider to specify a link to a EULA or terms of service they wish to show to students submitting homework.
This feature also guarantees that the user has agreed to the EULA/terms of service before they submit homework. The timestamp of when the user agreed is also provided to the tool provider during the normal submission/attachment retrieval flow.
Implementation
To implement this feature a tool provider must add the vnd.Canvas.Eula service to the service_offered array of their tool proxy:
As shown in the example above the value of endpoint should be a fully qualified URL pointing to the tool provider’s terms of service or EULA. The value of the @id must end in #vnd.Canvas.Eula. The action array must contain GET.
Once the tool is registered in Canvas and associated with an assignment, students will be presented with a link to the tool’s EULA that they must agree to before Canvas will allow a homework submission:
When the tool provider retrieves the assignment details from Canvas the body of the response payload will contain a property named eula_agreement_timestamp which contains the timestamp indicating when the user clicked the checkbox:
Requesting a TCP is the second step of registering an LTI2 Tool (See )
To retrieve a TCP with these restricted services/capabilities first retrieve a JWT access token as described in section 1.0. These tokens are associated with a single developer key which, in turn, are associated with a single custom TCP. Include this token in the authorization header of the request to retrieve the TCP:
The next-to-last step in the standard LTI2 registration flow is creating a Tool Proxy in the Tool Consumer (see ).
To register a Tool Proxy that uses restricted capabilities/services (like the originality report service) from a custom TCP the Tool Proxy creation POST request should include a JWT access token in the Authorization header. For information on retrieving a JWT access token for this purpose see section 1.0. This may be the same token used to retrieve the tool consumer profile.
Standard LTI2 registration requires requests to be signed with a temporary reg_key and reg_password (see ). When using a JWT access token in the authorization header this is not necessary (see section 1.0).
For additional field definitions and example JSON payloads, refer to the documentation for the assignment_updated, submission_created, and submission_updated event types in Canvas Data Services, specifically under and Event Format.
Once the TP has been notified of a new submission (see section 2.2), it may access the submission through the for processing. The payload from this request will contain URLs for retrieving the submission’s attachment.
For more details on creating originality reports see the .
Using the Originality Report and Submissions APIs requires a JWT access token be sent in the authorization header. For more information on using JWT tokens in Canvas see .
Once the course copy has occurred TPs should be aware that they will begin receiving submission_created webhooks for assignments for which they have never had an LTI launch occur. This is because it is unlikely that an instructor will edit each assignment in the new course, which is what would allow the Canvas.placements.similarityDetection placement LTI launch to occur. To access information about assignments that a TP has never received an LTI launch for use the .
When a submission_created webhook is received for an assignment the TP has not seen before, it means that the submission is for an assignment that was copied from an assignment the TP was configured on within another course. The TP should still process the submission. To fetch assignment information for a submission that has not been seen before, use the
This documentation is generated directly from the Canvas LMS source code, available .
