Exposing TCA Settings - Best Practice

Exposing TCA Settings and Functionality

Settings exposed to end users will depend on your integration use case.  If you are an institution building an integration into your 'home grown' application then the decisions are yours.  If you are a software vendor building an integration that will be used by multiple mutual customers then the following is expected, (as a minimum) for the majority of use cases.

Administrator Configuration Page

Provide a configuration page allowing an administrator, (at the mutual customer) to enter their Turnitin URL and API key and 'test' the credentials.

Test Connection

‘Test Connection’ should call the ‘Get Features Enabled’ request to validate the users entry. 'Save Changes' will implement the actual save, (along with handling webhook registration and some other logic). 

Save Changes

• Call the ‘Get Features Enabled’ request and store the ‘tenant.require_eula’ value. If true, EULA needs to be displayed to submitters and users viewing reports, (guide on the Turnitin EULA requirements is here).  You should also store the true|false value for each of the 'exclude_*' options in the 'view_settings' attribute for use in TCA, (discussed further down this guide).
• Call the 'List Webhooks' request.  For a new setup, no webhooks will be registered and you should register the required webhooks using the 'Create Webhook' request.  If correct webhooks are already registered for your integration then no action needs to be taken.
• Store the 'Indexing' option and 'Visibility' options for use in TCA as detailed below.

Indexing Options

3 options that control the value of the ‘add_to_index’ attribute in the ‘Generate Report’ request. 

• ‘Index all submissions’ sets the value to true.
• ‘Don’t index any submissions’ sets the value to false. The 2 '... Visibility' options should be disabled for selection as they are only applicable for indexed submissions.
• ‘Allow choice’ defers the value of the attribute to a deeper part of your software that allows end users to choose, (eg, 'Assignment' creation within a Learning Management System).

Institution Source Text Visibility and Institution Match Detail Visibility

If a match to an indexed document in the same account occurs, the report viewer 'can' show the metadata provided in the 'Create Submission' request for the matching document.  Displaying this metadata depends on the integration use case and the persona/role of the user viewing the report.  

The 'Create Viewer Launch URL' request has a 'viewer_default_permission_set' attribute, (mandatory) and a predefined set  of 'Roles with Permissions', (akin to the users persona or role) for that attribute that should be used for each request.  More often than not, one of the predefined 'role permissions' is suitable but scenarios can occur where the predefined permissions need to be overridden.  Overrides are performed using the 'viewer_permissions' attribute, (optional) where each individual permission can be set.  

• 'Institution Source Text Visibility' maps to 'viewer_permissions.may_view_submission_full_source' and 'may_view_document_details_panel'
  

• 'Institution Match Detail Visibility' maps to ''viewer_permissions.may_view_match_submission_info'

The functionality of these 2 permissions has the ability to release 'Personal Identifiable Information', (PII) so control of the functionality is passed to the administrator at the Institution.  Consider the following 'Learning Management System', (LMS) use case, (there are several other use cases).

Turnitin account was purchased at the 'District/Municipality' level so multiple schools submit to the same Turnitin account.  Without exposing these attributes, (to override the 'INSTRUCTOR' permissions set) teachers, (INSTRUCTOR's) at one school could see PII from a student in another school if a match to a document submitted by the other school occurred.  The administrator would set the 2 visibility options false to prevent this from happening.  Special consideration needs to be given to the LMS use case if the LMS supports 'anonymous marking'.  For an anonymous marking workflow, viewer launches using the 'INSTRUCTOR' permissions set should always set these 3 attributes to false, (regardless of administrator settings) to ensure PII cannot be released in the report viewer.  Please note, the 'LEARNER' permissions set should never send 'viewer_permissions' as students, (LEARNERs) should never have access to PII or text from the matching document. It is only pertinent to instructors for instances of collusion.   

User Configuration Page

TCA attributes, (and functionality) that 'could' be exposed deeper in your software for users to choose will likely depend on your use case.  Some settings could even be pushed to the 'Administrator Configuration Page' and thus apply to all submissions/users?

Again, the Learning Management System, (LMS) use case will be used to provide context to the attributes and functionality that can/should be exposed from within the LMS.

Allow Students to view Reports 

This option does not map to any API attributes. It would control the visibility of a button for students to launch the report viewer for their submissions.  For all use cases, (not just the LMS use case) the underlying application controls who has access to similarity reports. 

Index Submissions

This would only be visible if the 'Allow Choice' option was selected by the administrator in the 'Indexing Options' exposed in the 'Administrator Configuration Page'. 

Exclude Bibliography and Exclude Quotes

These map to attributes in the 'Generate Report' request.  Specifically:

• 'Exclude Bibliography' maps to 'view_settings.exclude_bibliography'
• 'Exclude Quotes' maps to 'view_settings.exclude_quotes'

TCA supports several products and the exclusion options available vary for each product. All products allow the exclusion of bibliography and quotes and will be familiar to end users of the 'LMS' use case.  To 'know' which attributes to expose, use the stored values from the 'Get Features Enabled' request triggered by the 'Save' action in the 'Administrator Configuration Page'. 

Suggested Text for 'Help' Icons

Administrator Configuration Page

• Turnitin URL: Your institution’s unique Turnitin URL. Takes the format of https://[YourInstitution].turnitin.com. For example. https://universityofturnitin.turnitin.com 
• Turnitin API Key: The unique API key generated when configuring the integration in Turnitin, (guide to creating the API key is here).
• Indexing Options: Choose if uploaded files will be available to be matched against in future Similarity Reports. 
• Institution Source Text Visibility: Instructors of matching sources within the same institution can view the full text of the original submission. 
• Institution Match Detail Visibility: Instructors of matching sources within the same institution can view basic details about the original submission and the person who submitted the file. This includes class details, their name, and submission dates. 

Please note that the text for, 'Institution Source Text Visibility' and 'Institution Match Detail Visibility' references 'Instructors' for the 'LMS' use case only. 

User Configuration Page

• Exclude Bibliography: The bibliography will automatically be detected by our machine learning algorithms and not included in the Similarity Report. 
• Exclude Quotes: Turnitin identifies any quoted text in the uploaded file and won’t include it in the Similarity Report. 
• Index Submissions: Upload files can be matched against in future Similarity Reports.

For other options, please refer to the descriptions for each attribute in the 'view_settings' of the 'Generate Report' request.