Turnitin LTI: Full List of Custom Parameters

Turnitin LTI Custom Setup Guide

This documented provides examples of how to interact with Turnitin using the LTI custom parameters and extensions created to allow an LMS to specify the type of assignment they wish to create. This documents assumes the reader already knows how to launch LTI, if not see ‘LTI Guide’.

Explanation of terms used in the document

Context – A class or course. When a context is created it will belong to the Turnitin account.
Learner – A student
Resource – An assignment. The an assignment is created it belongs to the context specified during its creation.
Outcome – A submission by a student into the specified resource.
Tool consumer – The party that uses the LTI API. In this case the LMS acts as the tool consumer.
Tool provider – The party that supplies the LTI API. In this case Turnitin is the tool provider.

Turnitin Endpoints

https://sandbox.turnitin.com/api/lti/1p0/assignment - To create or launch an assignment.

https://sandbox.turnitin.com/api/lti/1p0/resource_link_tool/{turnitin_assignment_id} - To get the available URLs for a resource.

https://sandbox.turnitin.com/api/lti/1p0/outcome_tool_data/{turnitin_submission_id} - To get the details of a Turnitin submission.

https://sandbox.turnitin.com/api/lti/1p0/upload/submit/{turnitin_assignment_id} - To submit a submission to a specified resource.

https://sandbox.turnitin.com/api/lti/1p0/upload/resubmit/{turnitin_submission_id} - To resubmit a submission.

Turnitin Callbacks

The document will discuss usage of the extensions ext_resource_tool_placement_url, ext_outcomes_tool_placement_url and lis_outcome_services_url). These are URL’s passed to Turnitin on resource creation and outcome submission. The URL will be the LMS’s own site, Turnitin will make calls to these URL’s upon certain events. The purpose of each is explained below.

ext_resource_tool_placement_url

Upon assignment creation the below JSON object will be sent to the specified URL.

{
   resource_link_id: {LMS_assignment_id},
   assignmentid: {Turnitin_assignment_id},
   resource_tool_placement_url: "http://turnitin.com/api/lti/1p0/resource_tool_data/4321"
}

ext_outcomes_tool_placement_url

Upon submission the below JSON object is sent to the specified URL.

{
   lis_result_sourcedid: {LMS_paper_id},
   paperid: {Turnitin_paper_id},
   outcomes_tool_placement_url: "http://turnitin.com/api/lti/1p0/outcome_tool_data/4321"
}

lis_outcome_services_url

When an instructor changes the grade within the Turnitin document viewer, the new score is sent to the specified URL. This ensures consistency within the LMS.

<replaceResultRequest>
<resultRecord>
    <sourcedGUID>
      <sourcedId>{LMS_paper_id}</sourcedId>
    </sourcedGUID>
    <result>
      <resultScore>
        <language>en</language>
        <textString>{score}</textString>
      </resultScore>
    </result>
  </resultRecord>
</replaceResultRequest>

Resources

Retrieving the available URLs for the resource

Turnitin allows LMS’s to launch to specific pages within Turnitin. After launching to https://sandbox.turnitin.com/api/lti/1p0/resource_link_tool/{turnitin_assignment_id} a JSON object will be returned shown in the below table. Settings will only be returned for assignment types where the custom parameters can be used (i.e. a standard assignment, peermark settings are not returned).

{
  "resource_dashboard":{
     "roles":[
        "Learner"
     ],
     "launch_url":"https://turnitin.com/api/lti/1p0/ass...29125817?lang=",
     "text":null,
     "label":"Assignment Dashboard"
  },
  "resource_peermarksetup":{
     "roles":[
        "Instructor"
     ],
     "launch_url":"https://turnitin.com/api/lti/1p0/pee...29125817?lang=",
     "text":null,
     "label":"PeerMark Setup"
  },
  "resource_peermarkreviews":{
     "roles":[
        "Instructor",
        "Learner"
     ],
     "launch_url":"https://turnitin.com/api/lti/1p0/pee...29125817?lang=",
     "text":null,
     "label":"PeerMark Reviews"
  },
  "resource_edit":{
     "roles":[
        "Instructor",
        "Learner"
     ],
     "launch_url":"https://turnitin.com/api/lti/1p0/ass...29125817?lang=",
     "text":null,
     "label":"Turnitin Assignment"
  },
  "resource_inbox":{
     "roles":[
        "Instructor"
     ],
"launch_url":"https://turnitin.com/api/lti/1p0/ass...29125817?lang=",
     "text":null,
     "label":"Assignment Inbox"
  },
  "resource_submit":{
     "roles":[
        "Learner"
     ],
     "launch_url":"https://turnitin.com/api/lti/1p0/upl...29125817?lang=",
     "text":null,
     "label":"Submit File"
  }
"resource_settings": {
   "text": null,
"custom_resource_settings":{ "context_title": "Design of Personal Environments",
"custom_allow_non_or_submissions": 0,
"custom_duedate": "2015-03-04T19":03":27Z",
"custom_exclude_type": "percentage",
"custom_exclude_value": 33,
"custom_feedbackreleasedate": "2015-03-04T19":03":27Z",
"custom_institutioncheck": 0,
"custom_internetcheck": 0,
"custom_journalcheck": 0,
"custom_late_accept_flag": 0,
"custom_maxpoints": 33,
"custom_report_gen_speed": 0,
"custom_s_view_reports": 0,
"custom_startdate": "2015-02-24T19":03":27Z",
"custom_studentpapercheck": 0,
"custom_submit_papers_to": 0,
"custom_use_biblio_exclusion": 0,
"custom_use_quoted_exclusion": 0,
"resource_link_description": "hello",
"resource_link_title": "My Weekly Wiki", }
},
}

Custom resource settings that can be defined

To define certain settings when creating an assignment it is simply a case of adding the custom parameters as extra body parameters. For example to set the maximum number of points to an assignment as 100 add ‘custom_max_points:100’.

When parameters are not supplied the default values will be used, which are listed below.
If after an assignment is created different custom parameters are sent on another launch then they will overwrite the previous settings, there is no way to lock assignment settings.
If an assignment is created with a custom parameter but a future request does not contain the parameter, then the original setting would be kept. However we would recommend explicitly posting the parameter with each request to aide any debugging.

List of custom parameters

custom_allow_non_or_submissions
custom_ anonymous_marking_enabled
custom_duedate
custom_exclude_type
custom_exclude_value
custom_feedbackreleasedate
custom_institutioncheck
custom_internetcheck
custom_journalcheck
custom_late_accept_flag
custom_maxpoints
custom_report_gen_speed
custom_s_view_reports
custom_startdate
custom_studentpapercheck
custom_submit_papers_to
custom_use_biblio_exclusion
custom_use_quoted_exclusion

Usage of custom parameters

custom_allow_non_or_submissions
Description - Determines whether to allow submissions that cannot have an originality report generated (i.e. a drawing or a photocopy).
Allowed values (Boolean)
[1, 0]. 1 allows non originality report submissions.
Default behaviour
0 - Cannot submit non originality report capable files

custom_anonymous_marking_enabled
Description - Determines if an assignment should have anonymous marking. This is currently enabled only on the Turnitin UK environment, and accounts have to have anonymous marking enabled. This cannot be changed once a student has submitted a paper to preserve anonyminity.
Allowed values (Boolean)
[1, 0]. 1 enables anonymous marking
Default behaviour
0 - Anonymous marking disabled

custom_duedate
Description - Determines when the end date of the assignment
Allowed values (date string)
A UTC date in ISO8601 format. Example - 2014-12-10T07:43:43Z
Default behaviour
Set to 7 days in the future

custom_exclude_type
Description - Determines at what level Turnitin ignores plagarism matches. It can be set as the number of words or the percentage match. The value is defined in custom_exclude_value. If used must be used with custom_exclude_value.
As an example, to set an assignment to ignore matches under 5 words, use the paramaters - custom_exclude_type='words', custom_exclude_value=5.
Allowed values (String)
'words', 'percentage', 'none'
Default behaviour
'none' - Nothing set

custom_exclude_value

Description - Determines the word level or percentage that Turnitin ignores plagarism matches. If used must be used with custom_exclude_type.
Allowed values (Positive Integer)
0-100 - If 'percentage' is used in custom_exclude_type
> 0 - If 'words' is used in custom_exclude_type
Default behaviour
0 - Nothing set

custom_feedbackreleasedate
Description - Determines when the feedback (grades, quickmarks) are released to the student
Allowed values (date string)

A UTC date in ISO8601 format. Example - 2014-12-10T07:43:43Z
Default behaviour
Set to 7 days in the future

custom_internetcheck
Description - Determines whether the paper is checked against internet matches
Allowed values (Integer)
[0, 1]. Setting 1 means the paper will be checked.
Default behaviour
Set to individual preference stored within Turnitin

custom_institutioncheck
Description - Determines whether the paper is checked against internet matches
Allowed values (Integer)
[0, 1]. Setting 1 means the paper will be checked.
Default behaviour
Set to individual preference stored within Turnitin

custom_jourrnalcheck
Description - Determines whether the paper is checked against journal matches
Allowed values (Integer)
[0, 1]. Setting 1 means the paper will be checked.
Default behaviour
Set to individual preference stored within Turnitin

custom_late_accept_flag
Description - Determines if a paper can be submitted after the due date
Allowed values (Boolean)
0, 1. Setting 1 allows late submissions.
Default behaviour
0 - false

custom_maxpoints
Description - Determines the maximum number of points available to the student. 100 is the maximum points in an LTI assignment
Allowed values (Integer)
A full integer
Default behaviour
Set to 100

custom_report_gen_speed
Description - Determines when an originality report is generated. This also controls the resubmission settings for the assignment.
Allowed values (0, 1, 2)
0 - First submission is final and originality report generated immediately. No resubmissions are allowed.
1 - Originality report generated immediately, the student can make resubmissions and get new originality reports.
2 - Originality report is only generated on the due date, but the student can make resubmissions to the assignment before the due date.
Default behaviour
0 - First submission is final and originality report generated immediately. No resubmissions are allowed.

custom_s_view_reports
Description - Whether the students are allowed to view the originality reports
Allowed values (Boolean)
[0, 1] - Setting 1 means the student can view the originality report
Default behaviour
0 - Cannot view reports

custom_startdate
Description - Determines when the assignment starts
Allowed values (date string)
A UTC date in ISO8601 format. Example - 2014-12-10T07:43:43Z
Default behaviour
Set to the current time

custom_studentpapercheck
Description - Determines whether the paper is checked against student paper matches
Allowed values (Integer)
[0, 1]. Setting 1 means the paper will be checked.
Default behaviour
Set to individual preference stored within Turnitin

custom_submit_papers_to
Description - Determines which repository the student is going to submit their paper to.
A new account will only have two options, submitting to no repository or the standard repository. An account can also setup it's own institutional repository by contacting Turnitin.
Allowed values (Integer)
0 - Do not store in a repository
1 - Store in the standard repository
2 - Store in an institutional repository
Default behaviour
1 - Store in the standard repository

custom_use_biblio_exclusion
Description - Determines whether the bibliography is excluded from the originality score
Allowed values (Boolean)
[0, 1]. 1 means the bibliography is excluded.
Default behaviour
0 - Bibliography material is not excluded

custom_use_quoted_exclusion
Description - Determines whether quoted material is excluded from the originality score
Allowed values (Boolean)
[0, 1]. 1 means the quoted material is excluded.
Default behaviour
0 - Quoted material is not excluded

Outcomes

Retrieving the available URLs and submission details for an outcome

Launch to https://sandbox.turnitin.com/api/lti/1p0/outcome_tool_data/{turnitin_submission_id} and a JSON object will be returned, shown in the below table.

{
"outcome_pdffile":{
"roles":[
"Learner",
"Instructor"
],
"launch_url":"https://turnitin.com/api/lti/1p0/dow...72874634?lang=",
"text":null,
"label":"Download File in PDF Format"
},
"outcome_originalfile":{
"roles":[
"Learner",
"Instructor"
],
"launch_url":"https://turnitin.com/api/lti/1p0/dow...72874634?lang=",
"text":null,
"label":"Download File in Original Format"
},
"outcome_resubmit":{
"roles":[
"Learner"
],
"launch_url":"https://turnitin.com/api/lti/1p0/upl...72874634?lang=",
"text":null,
"label":"Resubmit File"
},
"outcome_originalityreport":{
"roles":[
"Instructor"
],
"breakdown":{
"submitted_works_score":100,
"publications_score":0,
"internet_score":0
},
"launch_url":"https://turnitin.com/api/lti/1p0/dv/...72874634?lang=",
"text":"100%",
"numeric":{
"max":100,
"score":100
},
"label":"Open Originality Report"
},
"outcome_grademark":{
"roles":[
"Instructor"
],
"launch_url":"https://turnitin.com/api/lti/1p0/dv/...72874634?lang=",
"text":"--",
"numeric":{
"max":100,
"score":null
},
"label":"Open GradeMark"
}
}

It is expected that this will only be used when a student goes into the assignment in the LMS to view their paper, and only whilst the LMS is still waiting for the originality score from Turnitin. To keep the Turnitin grade consistent on the LMS the lis_outcome_services_url must be used.

Back to Support Center

Thank you! Your feedback will help us to improve this guide.

Was this page helpful?

We're sorry to hear that

If you have the time, we'd love to know how we could improve it.

Need to contact a human?

Get in touch