Originality Reports API
LTI API for OriginalityReports (Must use JWT access tokens with this API).
Originality reports may be used by external tools providing plagiarism detection services to give an originality score to an assignment submission's file. An originality report has an associated file ID (the file submitted by the student) and an originality score between 0 and 100.
Note that when creating or updating an originality report a
tool_setting[resource_type_code]
may be specified as part of the originality report.
This parameter should be used if the tool provider wishes to display
originality reports as LTI launches.
The value of tool_setting[resource_type_code]
should be a
resource_handler's "resource_type" code. Canvas will lookup the resource
handler specified and do a launch to the message with the type
"basic-lti-launch-request" using its "path". If the optional
tool_setting[resource_url]
parameter is provided, Canvas
will use this URL instead of the message's path
but will
still send all the parameters specified by the message. When using the
tool_setting[resource_url]
the tool_setting[resource_type_code]
must also be
specified.
A ToolSetting object looks like:
{
// the resource type code of the resource handler to use to display originality
// reports
"resource_type_code": "originality_reports",
// a URL that may be used to override the launch URL inferred by the specified
// resource_type_code. If used a 'resource_type_code' must also be specified.
"resource_url": "http://www.test.com/originality_report"
}
An OriginalityReport object looks like:
{
// The id of the OriginalityReport
"id": 4,
// The id of the file receiving the originality score
"file_id": 8,
// A number between 0 and 100 representing the originality score
"originality_score": 0.16,
// The ID of the file within Canvas containing the originality report document
// (if provided)
"originality_report_file_id": 23,
// A non-LTI launch URL where the originality score of the file may be found.
"originality_report_url": "http://www.example.com/report",
// A ToolSetting object containing optional 'resource_type_code' and
// 'resource_url'
"tool_setting": null,
// A message describing the error. If set, the workflow_state will become
// 'error.'
"error_report": null,
// The submitted_at date time of the submission.
"submission_time": null,
// The id of the root Account associated with the OriginalityReport
"root_account_id": 1
}
Create an Originality Report Lti::OriginalityReportsApiController#create
POST /api/lti/assignments/:assignment_id/submissions/:submission_id/originality_report
url:POST|/api/lti/assignments/:assignment_id/submissions/:submission_id/originality_report
Create a new OriginalityReport for the specified file
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
originality_report[file_id] | integer |
The id of the file being given an originality score. Required if creating a report associated with a file. |
|
originality_report[originality_score] | Required | number |
A number between 0 and 100 representing the measure of the specified file’s originality. |
originality_report[originality_report_url] | string |
The URL where the originality report for the specified file may be found. |
|
originality_report[originality_report_file_id] | integer |
The ID of the file within Canvas that contains the originality report for the submitted file provided in the request URL. |
|
originality_report[tool_setting][resource_type_code] | string |
The resource type code of the resource handler Canvas should use for the LTI launch for viewing originality reports. If set Canvas will launch to the message with type ‘basic-lti-launch-request’ in the specified resource handler rather than using the originality_report_url. |
|
originality_report[tool_setting][resource_url] | string |
The URL Canvas should launch to when showing an LTI originality report. Note that this value is inferred from the specified resource handler’s message “path” value (See ‘resource_type_code`) unless it is specified. If this parameter is used a `resource_type_code` must also be specified. |
|
originality_report[workflow_state] | string |
May be set to “pending”, “error”, or “scored”. If an originality score is provided a workflow state of “scored” will be inferred. |
|
originality_report[error_message] | string |
A message describing the error. If set, the “workflow_state” will be set to “error.” |
|
originality_report[attempt] | integer |
If no ‘file_id` is given, and no file is required for the assignment (that is, the assignment allows an online text entry), this parameter may be given to clarify which attempt number the report is for (in the case of resubmissions). If this field is omitted and no `file_id` is given, the report will be created (or updated, if it exists) for the first submission attempt with no associated file. |
Edit an Originality Report Lti::OriginalityReportsApiController#update
PUT /api/lti/assignments/:assignment_id/submissions/:submission_id/originality_report/:id
url:PUT|/api/lti/assignments/:assignment_id/submissions/:submission_id/originality_report/:id
PUT /api/lti/assignments/:assignment_id/files/:file_id/originality_report
url:PUT|/api/lti/assignments/:assignment_id/files/:file_id/originality_report
Modify an existing originality report. An alternative to this endpoint is to POST the same parameters listed below to the CREATE endpoint.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
originality_report[originality_score] | number |
A number between 0 and 100 representing the measure of the specified file’s originality. |
|
originality_report[originality_report_url] | string |
The URL where the originality report for the specified file may be found. |
|
originality_report[originality_report_file_id] | integer |
The ID of the file within Canvas that contains the originality report for the submitted file provided in the request URL. |
|
originality_report[tool_setting][resource_type_code] | string |
The resource type code of the resource handler Canvas should use for the LTI launch for viewing originality reports. If set Canvas will launch to the message with type ‘basic-lti-launch-request’ in the specified resource handler rather than using the originality_report_url. |
|
originality_report[tool_setting][resource_url] | string |
The URL Canvas should launch to when showing an LTI originality report. Note that this value is inferred from the specified resource handler’s message “path” value (See ‘resource_type_code`) unless it is specified. If this parameter is used a `resource_type_code` must also be specified. |
|
originality_report[workflow_state] | string |
May be set to “pending”, “error”, or “scored”. If an originality score is provided a workflow state of “scored” will be inferred. |
|
originality_report[error_message] | string |
A message describing the error. If set, the “workflow_state” will be set to “error.” |
Show an Originality Report Lti::OriginalityReportsApiController#show
GET /api/lti/assignments/:assignment_id/submissions/:submission_id/originality_report/:id
url:GET|/api/lti/assignments/:assignment_id/submissions/:submission_id/originality_report/:id
GET /api/lti/assignments/:assignment_id/files/:file_id/originality_report
url:GET|/api/lti/assignments/:assignment_id/files/:file_id/originality_report
Get a single originality report
Returns an OriginalityReport object