API Manual

TurnitinUK API Manual: 1

TurnitinUK API Manual

Copyright © 1998 – 2009 iParadigms, LLC. All rights reserved.

Updated February 24, 2010

Version 2.1.1

TurnitinUK API Manual: 2Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved.

Contents

Introduction 4Getting Started 5

Configuring the API From Your Admin Account 5

Calling the API 7

Overview of Function Variables 7Functions Specific Variables 9

API Functions 11Create user and login (fid=1) 11

Create class and assign the user as the instructor of the class (fid=2) 13

Join Class (fid=3) 17

Create Assignment (fid=4) 19

Submit Paper Function (fid=5) 24

Return Report Function (fid=6) 27

View/Download Submission (fid=7) 29

Delete Submission (fid=8) 31

Change Password (fid=9) 33

List Submissions (fid=10) 35

Check for Submission (fid=11) 38

Administrator Statistics (fid=12) 40

Return GradeMark Function (fid=13) 41

Report Turn Around Time (fid=14) 43

Submission Score (fid=15) 45

Anonymous Marking (fid=16) 46

Login Session (fid=17) 48

End a Session (fid=18) 49

Error Checking 50Logging 51

Return Codes 51

Success States 51

Error States 52


TablesFID/FCMD Error Code Table 59

FID/Data Elements Table 65

FID/MD5 Table 66

FID/Encrypt Data Table 67

GET/POST Requirements for Functions 68

Functions which Create User Profiles 70

Glossary 71


TurnitinUK API Manual Section: Introduction

Introduction

The TurnitinUK API allows you to access a variety of TurnitinUK actions in your own native applications or scripts. It is a REST based API, therefore it can be implemented in any language that allows for making https requests.

API Request Overview

All API calls are made through one URL, https://submit.ac.uk/api.asp. The different functionalities of the API are addressed by the function identification variable (fid). Each function carries out a specific set of actions at TurnitinUK. All the different functions have a core data requirement with each function potentially having additional data requirements. Each API function typically has two or more types of return methods that are controlled using the fcmd variable. One method which is intended for student/instructor URL access, for example a school portal integration, will log the user in after the successful execution of the API function. In the event of an error the API will redirect the user to your callback error URL. The second method is intended for back-end administrative programs, e.g. a batch auto-registration program. This method can also be used for performing actions without being brought to the TurnitinUK website. In this case, the API will return a status code to your program in XML indicating whether the requested action was successful or resulted in an error. If an error occurs, you can use the status code to determine the cause of the action’s failure.

Security Measures

The API also has a number of security features built into it for the purposes of authentication, encryption, and to prevent request tampering and misuse. We authenticate all API requests by comparing information in the URL to information stored in our authentication table. For further control, API requests can be locked down to a specific IP address or a range of IP addresses. To ensure that all requests are encrypted in transit, all API requests are required to be passed over an SSL connection. To further enhance the level of encryption we also offer the option of accepting encrypted data. To prevent URL misuse, we require that all API requests be time stamped; all expired requests are rejected. Requests expire after 59 minutes. To prevent URL tampering, we use a shared secret key between your institution and TurnitinUK.


TurnitinUK API Manual Section: Getting Started

Getting Started

Before you can begin using the TurnitinUK API, you must configure your account in TurnitinUK with a 8-digit alphanumeric shared key. This key will be used in calculating an MD5 signature for all your API requests and to encrypt your data, if you choose to, using Blowfish encryption. You can access this API administration page at TurnitinUK by clicking the integrations icon next to your primary account. An error callback URL and an IP address or range if you choose to use this security option must be provided.

Configuring the API From Your Admin Account

Your TurnitinUK account administrator will need to make two changes to your institution’s account in order to use the API. To make these changes, the administrator needs to login to his or her account and click on the integrations icon next to your school’s account.

Only the primary account needs to be updated; any sub-accounts that you may have added do not need updating.

Click on the configure link to the right of the Open API.

In the Open API configure box there are three fields to fill out for the API integration: Create Your Own Shared Key, Your Institution’s IP Address, and the Error Callback URL. Please provide a shared key which must be exactly 8 alphanumerical characters in the Create Your Own Shared Key field.


TurnitinUK API Manual Section: Getting Started

In the Open API configure box, there are two fields for the API integration: the IP address authentication and the callback URL for errors.

If you want to restrict connections to your account to users at your institution, enter your institution’s IP address or IP range. If you do not want to restrict connections, enter 255.255.255.255.

Administrators have the option to enter in a range of IP addresses. This IP masking is done using the CIDR format. The format is xxx.xxx.xxx.xxx/y where x stands for any digits from 0-9, and y is for the number of bits of the IP address you wish to use as a mask. For example: 64.140.5.0/25 will allow any addresses form 64.140.5.0-127; 64.140.5.128/25 will allow any address from 64.140.5.128-255; 64.140.5.0/24 will allow any addresses from 64.140.5.0-255.

It is critical that you enter the correct IP address, as we will only accept API calls from the IP address specified.

You will also be required to provide a callback URL for errors (for example, http://www.yourdomain.edu/catch_turnitin_error.asp). The API will issue a redirect to this URL if an error is encountered. The API will pass the callback URL two variables: ec (the error code - see the section titled Error Codes for more information) and em (a short error message). Using our previous example, a redirect call might look like this:

https://submit.ac.uk/api.error.asp?ec=100&em=Primary account ID is missing.

The TurnitinUK callback URL:

https://submit.ac.uk/api.error.asp


TurnitinUK API Manual Section: Calling the API

Calling the API

To call our API, information must be passed over an SSL connection as a URL. The example below is an example of a GET request. For an example of a POST request please view page 24.

https://submit.ac.uk/api.asp?gmtime=x&fid=x&fcmd=x&encrypt=x&md5=x&aid=x&said=x&diagnostic=x&uem=x&upw=x&ufn=x&uln=x&utp=x

The variable names sent in the URL to the TurnitinUK API are case insensitive but the data values are case sensitive. All data sent in the URL must also be properly escaped for proper URL syntax.

Overview of Function Variables

Required Function Variables

gmtime - GMT timestamp

The timestamp must be sent in an 11 digit numeric format YYYYMMDDHHM. The TurnitinUK server clocks are kept synchronized using the network time protocol.

fid - the function id

The numeric API command

fcmd - the function command

The numeric API function specific command

encrypt - encryption flag

The encryption flag can be set to 0 (off) or 1 (on). If encryption is enabled, the following user-sensitive data must be encrypted using your shared secret key with the Blowfish encryption scheme:

said sub-account id

uem user email

upw user password

ufn user first name

uln user last name

utp user type

ctl class title (only applicable if fid=2 or 3)

cpw class enrollment password (only applicable if fid=2 or 3)

tem email of instructor who created the class (only applicable if fid=3)


TurnitinUK API Manual Section: Calling the API

md5 - the function specific MD5 hex signature

The MD5 signature is generated by concatenating the data values associated with specific URL variables arranged in alphabetical order according to variable name. The shared secret key is included at the end of the MD5 string. For more information on the MD5, see the section titled Calculating the MD5 later in this document.

aid - primary account id

The id of the account which is associated with your school’s TurnitinUK license.

diagnostic - diagnostic flag

The diagnostic flag can be set to 1 (on) or 0 (off). When testing the API, the diagnostic flag should be enabled. Requests will be validated but not performed.

uem - user email

The user email is used as the TurnitinUK user name. The email address must be 6-50 characters in length.

ufn - user first name

User first name must be 1-50 characters in length.

uln - user last name

Must be 1-50 characters in length.

utp - user type

1 for students, 2 for instructors, and 3 for administrators.

Note: Encrypting variables might not be necessary or recommended for everyone since the API is accessed with an https url.

Note: There may be additional required function variables to perform different function requests. These variables will be detailed for the specific API functions in the additional function variables for fid = (#) subsection.


TurnitinUK API Manual Section: Functions Specific Variables

Functions Specific Variables

The two function parameters, fid and fcmd, included in the URL sent to the API determine the function the API will execute and the action that will be taken afterward.

fid

The fid determines the function that the API will perform. Possible values for the fid are:

1 - creates a user profile (if one does not exist) and logs the user in (instructor or student)

2 - creates a class under a given account (instructor only)

3 - enrolls a student in a class (student only)

4 - creates an assignment (instructor only)

5 - submits a paper to an assignment (student or teacher)

6 - generates an Originality Report for a submitted paper

7 - displays a submitted paper in a separate browser window or downloads it in file format

8 - deletes a submitted paper

9 - changes a user’s password

10 - lists the papers that have been submitted to an assignment

11 - checks to see if a user has submitted a paper to a specified assignment

12 - views administrator statistics page

13 - view the GradeMark screen for a submission

14 - Originality Report turnaround times

15 - load/set submission scores

16 - Anonymous Marking

17 - login a user to and create a session

18 - end a session


TurnitinUK API Manual Section: Functions Specific Variables

fcmd

The fcmd variable determines whether the user will be logged in after the requested action. If the fcmd is set to 1, the action specified by the fid is performed and the user is redirected to a URL. If the action fails, a code is returned to your institution’s callback URL.If the fcmd is set to 2, the action specified by the fid is performed and the user is not logged in. Instead, a code is returned in XML format showing whether the action has succeeded or failed (see section entitled Return Codes and Short Messages later in this document for more information).



Section: API Functions

API Functions

Create user and login (fid=1)

When a user is added successfully to an account, the default user type (student or teacher) will be set to the utp as the default. A user who has already been created and is in the database will already have their default utp number depending on their user type (1 for student, 2 for an instructor). If the user is in the database:

utp=1 - The student must belong to a class that was created in the primary ac-count or one of its children

utp=2 - The instructor must be joined to the primary account or one of its children. If the instructor does not belong to the primary account or one of its children, the upw must match and be verified for the existing user in order for the instructor to be joined to the account

Logic

If upw (user password) is not set, a random user password will be created instead in the case of user creation. The user can change this password using the “forgot your password?” link on the TurnitinUK homepage, thereby allowing the user to log in directly to TurnitinUK without the use of the API or through fid 9.

An email with passwords will be sent to the user if a new user was created and if the dis flag is not set to 1.

If idsync is set to 1, the API will check to see if the uid is provided. If the uid is pro-vided, it will ignore the idsync parameter. If uid is not set, then the API will check to see if there is an existing user with the corresponding email. If the class exists and has a corresponding uid, it will NOT change the uid. If the user exists and it doesn’t have a corresponding uid, the uid will be set the TurnitinUK internal user ID. If the user doesn’t exist, the user will be created and store the internal user ID as the uid.

If uid is set, the API will check to see if there is an existing match and use the corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the existing user first name, last name, or user email address is different than the ufn, uln, or uem being sent, the API will update the existing user information accordingly. If the uid does not exist in our database but is included in the API call, the API will use the included information and store the uid with the corresponding TurnitinUK user id.

Return States (rcode - event)

Success

10-11 - User creation successful


TurnitinUK API Manual Section: API Functions

Failure

100-199 - Data Errors200-299 - TurnitinUK Database Errors300-399 - Inconsistency Errors400 - User creation failed

fcmd=1

Action on Success - The API creates user if the user does not already exist in the database and logs the user in, redirecting the caller of the function to the appropriate web page.

Action on Failure - The API redirects the user to the callback URL with an error code and error message.

Return values - Success, logs the user into TurnitinUK via browser redirect. Failure, redirects user to the callback URL

Examples - Non-working example using GET request:

https://submit.ac.uk/api.asp?gmtime=200310231011&fid=1&fcmd=1&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&said=101&diagnostic=0&[email protected]&upw=john123&ufn=John%20II&uln=Doe&utp=2

fcmd=2

Action on Success - The API will return XML with success code an message

Action on Failure - The API will return XML with a corresponding error code and error message

Return Values - Success- XML <rcode>, <rmessage> <userid>

Failure- XML <rcode>, <rmessage>


https://submit.ac.uk/api.asp?gmtime=200310231011&fid=1&fcmd=2&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&said=101&diagnostic=0&[email protected]&upw=john123&ufn=John%20II&uln=Doe&utp=2



Create class under the given account and assign the user as the instructor of the class (fid=2)

Additional Function Variables for fid=2

ctl: class title (5-50 character in length)(required)cpw: class join password (6-12 characters in length)(optional)ced: class end date (format: YYYYMMDD)(optional)utp: must be 2 (instructor)idsync: either 1 or 0new_teacher_email: new teacher email (used in fcmd=4)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

The API will use the aid (account ID) or said (sub-account ID) if one is set. If the user is in the database, the user must already be joined to the primary account or one of its children.

A complication arises if an instructor’s class names remain the same from one semester to another. The client is responsible for maintaining the uniqueness of the class names. Possible strategies for maintaining uniqueness include: adding semester and year information or the course identifier to the class title, or using the cid parameter.

To change the instructor of a class (fcmd=4) enter the uem, utp, ctl. The user entered into the uem must be the current instructor of the class to use this function. The new teacher’s email for the class must already exist in our system and the user must be joined to this account in order to successfully run this function.

If the cpw (class join password) is not set, a randomly generated password will be used in its place. However, the randomly generated password may be changed from within TurnitinUK.

If uid is set, the API will check to see if there is an existing match and use the corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the existing user first name, last name, or user email address is different than the ufn, uln, or uem being sent, the API will update the existing user information accordingly. If the uid is not set, the API will use the included information and store the uid with the corresponding TurnitinUK user id.

If idsync is set to 1, it will affect the user creation function (fid=1). If it is set, the API will check to see if the cid is provided. If the cid is provided, it will ignore the idsync parameter. If the cid is not set, then the API will check to see if there is an existing class with the corresponding class title in the account. If the class exists and has a corresponding cid, it will NOT change the cid. If the class exists and it doesn’t have a corresponding cid, the cid will be set to the TurnitinUK internal class ID. If the



class doesn’t exist, the class will be created and the API will store the internal class ID as the cid.

If cid is set, the API will check to see if there is an existing match and use the corresponding class id on the TurnitinUK side, ignoring uem, ctl. If the cid is not set, the API will store the cid with the corresponding TurnitinUK class id.

If ced is set, the API will try to set the class end date to the value of ced, instead of the default end date of 6 months.


Success

20-21 - Class creation successful22 - Class update successful

Failure

101-199 - Data Errors200-299 - TurnitinUK Database Errors300-399 - Inconsistency Errors401 - Unauthorized access402 - User is not an instructor405 - Class title is not unique406 - Class creation failed

fcmd=1

Action on Success -

The API creates the user (as with fid=1, fcmd=2) if user is not already in data-base.

The API creates a class with title ctl for that user if a class with the same title has not already been created for that user in the specified account. Log the user in if the operation was successful or if this class already existed, otherwise the API sends the user to the callback URL.

Action on Failure -

The API redirects the user to the callback URL

Return Values -

Success - logs user into TurnitinUKOn Failure - redirects user to callback URL



Examples -

Non-working example using GET request:

https://submit.ac.uk/api.asp?gmtime=200310231011&fid=2&fcmd=1&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&upw=john123&ufn=John%20II&uln=Doe&utp=2&ctl=English%20For%20Freshman

fcmd=2

Action on Success - The API will return XML

Action on Failure - The API will return XML

Return Values -

Success - XML <rcode>, <rmessage>, <classid>, <userid>Failure - XML <rcode>, <rmessage>


https://submit.ac.uk/api.asp?gmtime=200310231011&fid=2&fcmd=2&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&upw=john123&ufn=John%20II&uln=Doe&utp=2&ctl=English%20For%20Freshman

fcmd=3

This fcmd is mainly used to update the class end date.

Action on Successful - The API will return XML


Return Values -



https://submit.ac.uk/api.asp?gmtime=200310231011&fid=2&fcmd=3&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&upw=john123&ufn=John%20II&uln=Doe&utp=2&ctl=English%20For%20Freshman&ced=20061030




fcmd=4

This fcmd allows the API user to switch the instructor for a class.

Action on Successful - The API will return XML


Return Values -



https://submit.ac.uk/api.asp?gmtime=200310231011&fid=2&fcmd=4&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&upw=john123&ufn=John%20II&uln=Doe&utp=2&ctl=English%20For%20Freshman&[email protected]



Join Class (fid=3)


ctl: class title (5-50 characters in length)(required)tem: user email of instructor who created the class (required)utp: must be 1 (student)(required)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

To join a class, the class must already exist and belong to the primary account or one of its children.

If the user is successfully joined to the class an email will be sent to the user notifying that he/she was joined to the class.


If cid is set, the API will check to see if there is an existing match and use the corresponding class id on the TurnitinUK side, ignoring the ctl and tem. If there is no match and the information is included, the cid will be saved with the corresponding TurnitinUK class id.


Success

30-31 - User joined to class

Failure

100-199 - Data Errors200-299 - TurnitinUK Database Errors300-399 - Inconsistency Errors407 - Student failed to join or log into a class



fcmd=1

Action on Success -

The API creates user (as with fid=1, fcmd=2) if the user is not in the database

The student is joined to the given class if they have not already joined the class.

Action on Failure - The API redirects user to the callback URL

Return Values -

Success - logs user into TurnitinUK

Failure - redirects user to callback URL


https://submit.ac.uk/api.asp?gmtime=200310231011&fid=3&fcmd=1&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&[email protected]&upw=student123&ufn=student&uln=x&utp=1&ctl=English%20For%20Freshman

fcmd=2

Action on Success - The API returns XML

Action on Failure - The API returns XML

Return Values -



https://submit.ac.uk/api.asp?gmtime=200310231011&fid=3&fcmd=2&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&[email protected]&upw=student123&ufn=student&uln=x&utp=1&ctl=English%20For%20Freshman



Create Assignment (fid=4)


ctl: title of class to create assignment in (required)assign: title of assignment to create (required)upw: user password (optional)utp: must be 2 (instructor) (required)dtstart: date the assignment begins (in YYYYMMDD format) (required)dtdue: date the assignment is due (in YYYYMMDD format) (required) dtpost: date when the grade and marked paper are available to students (in YYYYMMDD or YYYY-MM-DD HH::MM:SS format) (required)ainst: assignment instructions (optional)newassign: new title of assignment if modifying assignment (optional)ced: class end date (in YYYYMMDD format) (optional)

s_view_report: allow students to view the Originality Report (optional, default is set to not allow students to view Originality Reports) s_paper_check: compare submitted papers with other student papers (optional, default =1 allow) internet_check: compare submitted papers to internet database (optional, default = 1 allow) journal_check: compare submitted papers with journals, periodicals, publications (optional, default = 1 allow) institution_check: Compare submitted papers with papers submitted within this institution (optional, default = 1 allow) max_points: max points for assignment (optinoal, default = 0) late_accept_flag: allow submission past due date (optional, default = 0 not allow) submit_papers_to: where to store the submission (optional, default = 1) 0 = no repository, 1 = standard repository, 2 = institutional repository (if the institurtion has one) report_gen_speed: when to generate the Originality Reports (optional, default = 0) 0 = immediately (first report is final), 1 =immediately (can overwrite reports until the due date), 2 = on the due date

anon: anonymous marking option for an assignmentexclude_biblio: exclude bibliographic material from the Originality Reports generated for that assignment (default 1)exclude_quoted: exclude quoted material from the Originality Reports generated for that assignment (default 1)exclude_type: for excluding small matches and is the exclusion type (by word count = 1, by percentage = 2)exclude_value: this is for excluding small matches and is the value of the match to exclude from the Originality Report depending upon the exclusion type (word count or percentage). If exclude by word count is chosen it will exclude all matches with a word count beneath the set value, if exclude by percent is chosen it will exclude all matches with a percentage beneath the set valuesession-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)



Logic

The title of the assignment must be unique to that class.

Create an assignment with title assign for the class with ctl as class title and uem as the instructor’s email in the given account.

If the user and the class do not exist, both will be created.

For fcmds 2, 3, and 4 a POST request is required to be made to the API server from the client with user info. It would be best to use a GET request for fcmds 1 and 5.

If present, ainst is not to be included in the calculation of the MD5.


If idsync is set to 1, it will affect the class creation function (please see fid = 2). If it is set, the API will check to see if the assignid is provided. If the assignid is provided, it will ignore the idsync parameter. If assignid is not set, then the API will check to see if there is an existing assignment with the corresponding assignment title in the class. If the assignment exists and has a corresponding assignid, it will NOT change the assignid. If the assignment exists and it doesn’t have a corresponding assignid, the API will store TurnitinUK internal assignment ID as the assignid. If the assignment does not exist, the assignment will be created and store the internal assignment ID as the assignid.

Assignid not allowed if idsync is set to 1 and fcmd = 2.

If cid is set, the API will check to see if there is an existing match and use the corresponding class id on the TurnitinUK side, ignoring the ctl. If there is no match and the information is included, the cid will be saved with the corresponding TurnitinUK class id.


Success

40 - Redirect to assignment creation/modification screen successful41 - Assignment creation successful42 - Assignment modification successful43 - Assignment deletion successful

Failure

100-199 - Data Errors



200-299 - TurnitinUK Database Errors300-399 - Inconsistency Errors411 - Assignment creation failed419 - Assignment already existed

fcmd=1

Action on Success - The API redirects the user to the TurnitinUK assignment creation screen

Action on Failure - The API redirects the user to the callback URL

Return Values -

Success - logs the user into the TurnitinUK assignment creation screen Failure - redirects to callback URL


https://submit.ac.uk/api.asp?gmtime=200310231011&fid=4&fcmd=1&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=instructor&uln=x&utp=2&ctl=English%20For%20Freshman&uid=_1_1&cid=_1_3

fcmd=2

Action on Success -

The API creates a new assignment for the given class, and returns XML

If assignid is set, it will be saved with the corresponding TurnitinUK assignment id that is created


Return Values -

Success - XML <rcode>, <rmessage>, <assignmentid>, <classid>, <userid> Failure - XML <rcode>, <rmessage>

Examples - Please see fid 5, fcmd 2 for a POST example

fcmd=3

Action on Success -

The API will modify the current assignment, and return XML



If assignid is set, the API checks to see if there is an existing match. If assign is included and there is no match, the API will use assign and store the assignid with the corresponding TurnitinUK assignment id.


Return Values -



fcmd=4,6

Action on Success -

The API deletes the current assignment, and returns XML

If assignid is set, the API checks to see if there is an existing match. If assign is included and there is no match, the API will use assign.


Return Values -



fcmd=5

Action on Success - The API redirects the user to the TurnitinUK assignment modification screen


Return Values -

Success - logs the user into the assignment modification screen Failure - redirects user to the callback URL






fcmd=7

Action on Success - The API returns XML of assignment settings


Return Values -

Success - XML <rcode>, <rmessage>, <object>, <assign>, <maxpoints>, <dstart>, <dtdue>, <dtpost>, <ainst>, <userubrics>, <draft>, <generate>, <sviewreports>. <latesubmissions>, <repository>, <searchpapers>, <searchinternet>, <searchjournals>, <searchinstitution>, <anon>

Failure - XML <rcode>, <rmessage>

Example Return XML -

<returndata> <object> <assign>Assignment #1</assign> <maxpoints>100</maxpoints> <dtstart>2009-08-13 00:00:00-07</dtstart> <dtdue>2009-08-31 00:00:00-07</dtdue> <dtpost>2009-08-31 00:00:00-07</dtpost> <ainst>Assignment Instructions</ainst> <userubrics>0</userubrics> <draft>0</draft> <generate>0</generate> <sviewreports>0</sviewreports> <latesubmissions>0</latesubmissions> <repository>1</repository> <searchpapers>1</searchpapers> <searchinternet>1</searchinternet> <searchjournals>1</searchjournals> <searchinstitution>1</searchinstitution> <anon>0</anon> </object> <rcode>85</rcode> <rmessage>Successful!</rmessage></returndata>






Submit Paper Function (fid=5)


If utp=1 tem: user email of instructor who created the class (required)If utp=2 pfn: author of paper’s first name (required) pln: author of paper’s last name (required)ptl: title of paper to submit (required)pdata: paper in original format (required)ptype: type of file (1-text, 2-file) (required)ctl: title of class to submit paper to (required)assign: title of assignment to submit paper to (unique for that class) (required)submit_date: allows the submissions to have a custom submit date. If the user wants to specify a specific date/time that is before the start date it can’t be submitted and if it is after the due date it cannot be submitted (optional)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

This function will submit a paper to the given assignment. The assignment, class, and user all need to exist prior to submitting a paper.

There are two ways we can receive the request:

We receive a GET request with fcmd=1 that redirects the user to our TurnitinUK submission page.

We receive a POST from the client with user info and the user paper object.

For bulk uploads, we require to just call this function as many times as papers in bulk upload.


If submit_date is not set, the time of the submission is the current time. The submit_date is still subject to the due date and start date of the assignment, meaning that if the date specified is before the start date or after the due date

Note: The POST cannot be directly sent to our website, but must be a re-post of the required data to our site. See fcmd 2 for an example.



it cannot be submitted. The format for this field is (yyyymmdd or yyyy-mm-dd hh:mm:ss)

If cid is set, the API will check to see if there is an existing match. If there is no match, the API will use the ctl and tem and store the cid with the corresponding TurnitinUK class id.

If assignid is set, the API checks to see if there is an existing match. If they are included and there is no match, the API will use assign, ctl and tem and store assignid with the corresponding TurnitinUK assignment id.


Success

50 - Redirects user to the submission screen 51 - Paper submitted to the assignment

Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 409 - Function requires POST request 413 - Paper submission failed 1000-1099 - Paper Submission Errors

fcmd=1

Action on Success - The API redirects the user to the TurnitinUK submission screen


Return Values -

Success - logs the user into the TurnitinUK submission screen Failure - redirects the user to the callback URL


https://submit.ac.uk/api.asp?gmtime=200310231011&fid=5&fcmd=1&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=instructor&uln=x&utp=1&ctl=English%20For%20Freshman&assign=Test1&uid=_1_1&cid=_1_3&assignid=_1_1

fcmd=2

Action on Success - The API returns a unique object identifier for the paper that has been submitted, and returns XML




Return Values -

Success - XML <rcode>, <rmessage>, <objectid> Failure - XML <rcode>, <rmessage>

Examples -

Since you cannot POST directly to our site, you can submit the form to your own site, process the data, and repost the data to us:

One way to do that is using HTTP::REQUEST::COMMON as specified in RFC 1867

POST ‘https://submit.ac.uk/api.asp’, Content_Type => ‘form-data’, Content => [ ufn =>’Person’, uem =>’[email protected]’, uln =>”M”, gmtime => [“$ENV{HOME}/.profile”], ]

This will create a HTTP::Request object that almost looks like this (the boundary and the content of your~/.profile is likely to be different):

POST https://submit.ac.uk/api.asp Content-Length:388 Content-Type: multipart/form-data; boundary=”6G+f”

--6G+f Content-Disposition: form-data; name=”ufn”

Person --6G+f

Content-Disposition: form-data; name=”uem” [email protected]+fContent-Disposition: form-data; name=”uln” M--6G+fContent-Disposition: form-data; name=”gmtime” 1964--6G+fContent-Disposition: form-data; name=”paper”; filename=”.profile”Content-Type: text/plain PATH=/local/perl/bin:$PATHexport PATH

--6G+f--



Return Report Function (fid=6)


oid: unique Object ID of paper for which to generate a report for (required)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

This API function retrieves the Originality Report for the given object ID.



Success

60-61 - Originality Report/score retrieved

Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 414 - Originality Report not generated yet 415 - Originality Score not available yet

fcmd=1

Action on Success - The API opens a new window containing the specified Originality Report


Return Values -

Success - loads a new window containing the Originality Report Failure - redirects user to callback URL




https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=6&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&utp=1&oid=1546545

fcmd=2

Action on Success - The API retrieves the originality score for the given object ID, and returns XML


Return Values -

Success - XML <rcode>, <rmessage>, <originalityscore> Failure - XML <rcode>, <rmessage>


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=6&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&upw=password&utp=1&oid=2390481




View/Download Submission (fid=7)


oid: unique ObjectID of paper to view or download (required)If utp=1 tem: user email of instructor who created the class (required)

ctl: title of class the paper was submitted to (required)assign: title of assignment that the paper was submitted to (unique for that class) (required) session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

This API function allows the user to view or download the paper that has been submitted.



If assignid is set, the API checks to see if there is an existing match. If there is no match, the API will use assign, ctl and tem and store assignid with the corresponding TurnitinUK assignment id.


Success -

70 - Paper viewed/downloaded

Failure -

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 420 - Error trying to view/download original paper



fcmd=1

Action on Success - The API opens a new window containing the original submitted paper


Return Values -

Success - loads window containing the original submitted paper Failure - redirects user to callback URL


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=7&fcmd=1&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&upw=password&utp=1&oid=1546545&ctl=classtitle&assign=assignment

fcmd=2

Action on Success - The API downloads the original submitted paper. If Anonymous Marking is enabled for the assignment the instructor will not be able to download the paper until the post date of the assignment


Return Values -

Success - downloads original paper to local machine Failure - XML <rcode>, <rmessage>


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=7&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&upw=password&utp=1&oid=2390481&ctl=classtitle&assign=assignment



Delete Submission (fid=8)


oid: unique ObjectID of paper to view or download (required)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

This function deletes the paper that matches the Object ID.



Success

71 - Paper successfully deleted

Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 418 - Error trying to delete submission

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API deletes the specified paper, and returns XML


Return Values -

Success - XML <rcode>, <rmessage>









Change Password (fid=9)


upw: current user password (required)npw: new password to change to (required)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

This API function changes the password for the given user after the user is validated with their current password.



Success

75 - Password changed successfully

Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 417 - Error trying to change user password

fcmd=1

Not Defined YET

fcmd=2

Action on Success - The API change password, and returns XML




Return Values -

Success - XML <rcode>, <rmessage> Failure - XML <rcode>, <rmessage>


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=9&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&npw=newpassword&[email protected]&ufn=person&uln=x&upw=password&utp=1




List Submissions (fid=10)


If utp = 1 tem: user email of instructor who created the class (required)ctl: title of class (required)assign: title of assignment to view submissions for (unique for that class) (required)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

hide_gm_nav: disables or hides the navigation for GradeMark, so the instructor cannot move between papers from within GradeMark. Only for FCMD=1 (1 hides navigation, 0 does not hide navigation)

Logic

This API function lists all the papers that have been submitted to the specified assignment for the specified class.





Success

70 - Redirect the user to the TurnitinUK inbox screen for either student or instructor user depending upon user type 72 - Submission data successfully retrieved

Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors



300-399 - Inconsistency Errors 420 - Error trying to build up session date for user/class 421 - Error trying to retrieve paper submission info for assignment

fcmd=1

Action on Success - The API redirects the user to the TurnitinUK inbox screen for either the student or instructor user depending upon the user type


Return Values -

Success - logs the user into the submission screen Failure - redirects to callback URL


https://submit.ac.uk/api.asp?gmtime=200310231011&fid=10&fcmd=1&encrypt=0&md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=instructor&uln=x&utp=1&ctl=English%20For%20Freshman&assign=Test 1&uid=_1_1&cid=_1_3&assignid=_1_1

fcmd=2



Return Values -

Success - XML <rcode>, <rmessage>, <object>, <userid>, <firstname>, <lastname>, <title>, <objectid>, <similarityscore>, <overlap>, <web_overlap>, <publication_overlap>, <student_paper_overlap>, <score>, <grademarkstatus>



<returndata> <object> <userid>9876543</userid> <firstname>John</firstname> <lastname>Doe</lastname> <title>My Title</title> <objectID>49247310</objectID> <date_submitted>14-08-09 16:37:47 PDT</date_submitted> <similarityScore>0</similarityScore> <overlap>30</overlap> <web_overlap>20</web_overlap> <publication_overlap>10</publication_overlap> <student_paper_overlap>5</student_paper_overlap>




<score>100</score> <anon>1</anon> <gradeMarkStatus>1</gradeMarkStatus> </object> <object> <userid>1234567</userid> <firstname>Jane</firstname> <lastname>Doe</lastname> <title>My Title</title> <objectID>49247311</objectID> <date_submitted>14-08-09 16:37:47 PDT</date_submitted> <similarityScore>0</similarityScore> <overlap>0</overlap> <web_overlap>20</web_overlap> <publication_overlap>10</publication_overlap> <student_paper_overlap>5</student_paper_overlap> <score>100</score> <anon>1</anon> <gradeMarkStatus>1</gradeMarkStatus> </object> <rcode>72</rcode> <rmessage>Successful!</rmessage></returndata>

Note: If Anonymous Marking is enabled for an assignment the first name of the student will be “Anonymous Marking” and the last name will be “Enabled” up until the post date of the assignment


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=10&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&utp=1&ctl=classtitle&assign=assignment



Check for Submission (fid=11)


utp: must be set to 1tem: user email of instructor who created the class (required)ctl: title of class (required)assign: title of assignment to view submissions for (unique for that class) (required)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

This API function checks to see if user has submitted a paper to the specified assignment and checks to see if the class allows students to view their own originality reports





Success

73 - Check successfully completed

Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 416 - Error trying to verify if user has submitted to assignment



fcmd=1

Not Defined YET

fcmd=2



Return Values -



https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=11&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&utp=1&ctl=classtitle&assign=test



Administrator Statistics (fid=12)


utp: must be set to 3fcmd: must be set to 1session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

This API function checks to see if the user is an administrator and then the API redirects the user to a page that contains the administrator statistics for the account.


Success

70 - Redirect the user to the administrator statistics page

Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 420 - Error trying to build session data for user/class

fcmd=1

Action on Success - The API redirects the user to the administrator statistics page


Return Values -

Success - logs user into submission screen Failure - redirects to callback URL


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=12&fcmd=1&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&utp=3

fcmd=2Not defined yet




Return GradeMark Function (fid=13)


oid: unique Object ID of paper for which to access GradeMark for (required)session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

hide_gm_nav: disables or hides the navigation for GradeMark, so the instructor cannot move between papers from within GradeMark. Only for FCMD=1 (1 hides navigation, 0 does not hide navigation)

Logic

This API function retrieves the GradeMark screen for the given object ID.



Success

80-81 - GradeMark screen/markup status

Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 433 - GradeMark not available yet

fcmd=1

Action on Success - The API opens a new window containing the specified GradeMark paper


Return Values -

Success - loads a new window containing GradeMark Failure - redirects user to callback URL






fcmd=2

Action on Success - The API retrieves the status of the paper: whether it has been marked up or not


Return Values -

Success - XML <rcode>, <rmessage>, <markup_exists> Failure - XML <rcode>, <rmessage>


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=13&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&upw=password&utp=2&oid=2390481

fcmd=3

Action on Success - The API redirects the user to the GradeMark Report page which provides details about the use of QuickMark editing marks and Rubrics within an assignment and allows the user to export the report as an excel spreadsheet


Return Values -



https://api.turnitin.com/api.asp?gmtime= 20040329113&fid=13&fcmd=3&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&upw=password&utp=2&cid=1787187&assignid=_1_1




Report Turn Around Time (fid=14)

Additional Function Variables for fid=14:

utp: must be set to 2 or 3fcmd: must be set to 2starttime: can take in one parameter “starttime” in the format of “YYYY-MM-DD HH:MM:SS”, of which if specified, will generate the values based on the given parameter. If none is specified will generate the values based off the current timesession-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

The API will return to the user in XML format the average originality report turnaround times in seconds for the time intervals of 1, 5, 10 and 15 minutes.


Success

74 - Report turnaround time retrieval successful Failure

100-199 - Data Errors 200-299 - TurnitinUK Database Errors 300-399 - Inconsistency Errors 434 - Start time parameter not in the right format

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API returns in XML format the average originality report turnaround times in seconds for the time intervals of 1, 5, 10 and 15 minutes


Return Values -

Success - XML <rcode>, <rmessage>, <returndata>, <averagetime15>, <averagetime10>, <averagetime5>, <averagetime1>






<returndata> <object> <averagetime15>47</averagetime15> <averagetime10>48</averagetime10> <averagetime5>47</averagetime5> <averagetime1>36</averagetime1> </object> <rmessage>Successful!</rmessage> <rcode>74</rcode></returndata>


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=14&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&upw=password&utp=2




Submission Score (fid=15)


utp: must be set to 2 or 3 objectID: submission to retrieve score or submit score for

session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

The API function will retrieve the score or submit the score for the object if the object exists, and the user has permission to access the object.


Success

83-84 - Retrieval/Submission of score succeeded Failure

435 - error in inputting grade for submission

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API returns in XML the retrieved scoreAction on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <score>

fcmd=3

Action on Success - The API returns in XML the set scoreAction on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <score>




Anonymous Marking (fid=16)


utp: must be set to 2 or 3 oid: submission to retrieve score or submit score for anon_reason: reason for revealing authors identity for anonymous marking

session-id: users can log in using the session-id which allows them to make certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

The API function will retrieve the score or submit the score for the object if the object exists, and the user has permission to access the object.


Success

83-84 - Retrieval/Submission of score succeeded Failure

435 - error in inputting grade for submission

fcmd=1

Action on Success - The API redirects the user to the Administrator Log page for Anonymous Marking

Action on Failure - The API redirects to callback URL


https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=16&fcmd=1&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&utp=3

fcmd=2

Action on Success - The API returns in XML the Administrator Log for Anonymous Marking





Return Values -

Success - XML <rcode>, <rmessage>, <object>, <instructor_firstname>, <instructor_lastname>, <author_lastname>, <author_firstname>, <paperID>, <assignmentID>, <date_off>, <reason>


Example:

<object> <instructor_firstname>Class</instructor_firstname> <instructor_lastname>Instructor</instructor_lastname> <author_lastname>Doe</author_lastname> <author_firstname>John</author_firstname> <paperID>49245220</paperID> <assignmentID>5401502</assignmentID> <date_off>2009-01-20 01:10:25.422231-08</date_off> <reason>Reason for disabling AM</reason></object>

fcmd=3

Action on Success - The API reveals the name of the author for the submission



https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=13&fcmd=2&encrypt=0&md5=0b83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&[email protected]&ufn=person&uln=x&upw=password&utp=2&oid=2390481&anon_reason=Some reason




Login Session (fid=17)


utp: must be set to 2 or 3 fcmd: must be set to 2 session-id: users can log in using the session-id which allows them to make

certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

The API function will log in the user described by the user email, first name, last name, and user type.


Success

92 - login succeeded Failure

210 - user password (optional) did not match 420 - could not create Session (user name does not match email)

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API returns in XML the session IDAction on Failure - The API returns XML

Return values -

Success - XML <rcode>, <rmessage>, <sessionid>

Examples - Non-working example using GET request:http://api.turnitin.com/api.asp?gmtime=20091022211&fid=17&fcmd=2&encrypt=0&md5=ae2a071a1502a8a908ca9ee066c530f8&aid=39219&said=&diagnostic=0&uem=test_user1%40turnitin.com&upw=&ufn=Test&uln=User1&utp=2




End a Session (fid=18)


utp: must be set to 2 or 3 fcmd: must be set to 2 session-id: users can log in using the session-id which allows them to make

certain write-then-read combinations of API calls in rapid succession, where the second call depends on data as a result of the first call (optional)

Logic

The API function will log out the user described by the user email, first name, last name, and user type and end the Session with session-id.


Success

92 - logout succeeded Failure

210 - user password (optional) did not match 420 - could not create Session (user name does not match email) 446 - Session ID missing from URL

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API returns in XML the session IDAction on Failure - The API returns XML

Return values -

Success - XML <rcode>, <rmessage>


http://api.turnitin.com/api.asp?gmtime=20091022211&fid=18&fcmd=2&encrypt=0&md5=b337d2036a8e5638b1d9094f0eec7ae9&aid=39219&said=&diagnostic=0&uem=test_user1%40turnitin.com&upw=&ufn=Test&uln=User1&utp=2&session-id=16f69a5f9d93feb01edc8c794ff2c3e4



Error Checking

If an error occurs, the API redirects the client back to the callback URL if diagnostic=0 or to the output error diagnostic information if diagnostic=1. The following error checks are made in the order given below. The error checking stops after the first error is encountered and diagnostic information is only provided for that step and previous ones. The ordering is meant to limit the amount of valid information a user has access to, given an incomplete/invalid request.

All errors are uniquely identifiable by a numeric code and shall have a short error message associated with them. The full return code set includes both the error codes and success codes, all of which are unique.

1. The request is transmitted over HTTPS2. The primary account ID must be in the authentication table3. IP address or mask check 4. The values of fid and fcmd point to a valid function5. The function’s required parameters are all set and the data is of a valid type, (e.g.

numeric)6. The MD5 in the request and TurnitinUK’s calculated MD5 have to match. If data is

encrypted, the MD5 uses the unencrypted values7. The server GMT and request GMT match to the first minutes digit8. The data constraints are met (e.g. email is between 6-50 characters)

For successful requests, diagnostic information will include:

• All request variables. If encryption is enabled, the encrypted and unencrypted values are provided.

• Function specific information

1. State of user prior to and after application of function (fid=1, fcmd=1) 2. State of class prior to and after application of function (fid=2,fcmd=1)

3. State of enrollment in class prior to and after application of function (fid=3, fcmd=1)

4. State of assignment prior to and after application of function (fid=4, fcmd=1)

5. State of paper prior to and after application of function (fid=5, fcmd=1)

6. Return value after application of function (fid=6, fcmd=1 or 2)


8. State of submission before and after deletion (fid=8, fcmd=2)

9. State of password before and after change (fid=9, fcmd=2)


TurnitinUK API Manual Section: Success States

10. Return value after application of function (fid=10, fcmd=2)

11. Return value after application of function (fid=11, fcmd=2)

12. Diagnostic mode won’t do anything (fid=12, fcmd=2)


14. Return value after application of function (fid=14, fcmd 2)

15. Return value after application of function (fid=15, fcmd 2,3)

17. Returns session-id (fid=17, fcmd 2)

18. Will not show anything (fid=18, fcmd 2)

Logging

All requests and the result of those requests are logged. This should include the requesting URL, the return code, and any other diagnostic information (DB rollbacks/errors, etc.)

Return Codes

Success States

1-99

1 General Success State, no errors10 FID 1, FCMD 1 – successful, send to login11 FID 1, FCMD 2 – successful, do not send to login 20 FID 2, FCMD 1 – successful, send to login21 FID 2, FCMD 2 – successful, do not sent to login30 FID 3, FCMD 1 – successful, send to login31 FID 3, FCMD 2 – successful, do not send to login40 FID 4, FCMD 1,5 – successful, redirect user to assignment creation/modification page41 FID 4, FCMD 2 – successful42 FID 4, FCMD 3 – successful43 FID 4, FCMD 4 – successful50 FID 5, FCMD 1 – successful, redirect user to submission page51 FID 5, FCMD 2 - successful60 FID 6 & 13, FCMD 1 - successful61 FID 6 & 13, FCMD 2 - successful70 FID 7, FCMD 1,2 – successful70 FID 12, FCMD 1 – successful, redirect user to administrator statistics page71 FID 8, FCMD 2 - successful


TurnitinUK API Manual Section: Error States

72 FID 10, FCMD 2 - successful73 FID 11, FCMD 2 – successful74 FID 14, FCMD 2 – successful 75 FID 9, FCMD 2 - successful80 FID 13, FCMD 1 - successful, redirect to grademark screen81 FID 13, FCMD 2 - successful83 FID 15, FCMD 2 - successful84 FID 15, FCMD 3 - successful

Error States

Data Errors

100-199

100 Primary account ID missing from URL 101 No HTTPS - the URL was not transmitted via HTTPS102 GMT missing from URL103 GMT malformed - the date/time in the URL is bad104 Email missing from URL105 Email address is not between 5-75 characters106 Email address contains white space107 Email address in URL is malformed108 Password in URL contained white space109 Diagnostic value in URL is bad110 MD5 missing from URL111 fcmd missing from URL112 User first name missing from URL or incorrect length113 User last name missing from URL or incorrect length114 Class title missing from URL, or not between 5-50 characters115 Password is not between 6-12 characters116 fid missing from URL, or does not reference existing function117 User type missing from URL or is not valid118 encrypt value in URL is bad or missing119 Paper author’s first name missing or incorrect length120 Paper author’s last name missing or incorrect length121 Paper title missing – Please make sure to include a paper title before submitting your paper122 Paper type missing or invalid123 Assignment title missing or incorrect length124 ObjectID missing125 Password is required for function126 Date start and date due is required for function127 If one unique ID is used, they must all be used128 The class end date parameter is not in the right format. Please make sure that the format is in YYYYMMDD.”129 The class end date parameter is not set. Please make sure that the class end date is set if you wish to update the class.130 The web services url is not valid. Please make sure that the web services url is a well-formed url.131 The grade for the object is missing. Please make sure to include a grade for this



submission132 The grade for the object in invalid. Please make sure the grade is between 0 and max points for the assignment.133 AssignID not allowed if creating an assignment with IDSync on. Please either turn IDSync off or remove the assignID field.134 submit_papers_to parameter needs to be between 0 and 2 inclusive.

TurnitinUK Database Errors

200-299

200 Primary account ID for TurnitinUK not activated to use the API201 IP address validation range for TurnitinUK not configured202 Primary account entry not active in TurnitinUK database 203 MD5 key missing from TurnitinUK database204 Class does not exist in TurnitinUK database. Please contact you instructor for further details.205 Database error verifying class206 The assignment you are trying to access does not exist in TurnitinUK for this class. The assignment may have been deleted. If you created your assignment via a course copy method, it may not have been done with a course copied enabled version of the integration. In such a case, please delete the assignment and recreate it manually.207 Database error verifying assignment208 User is not enrolled in class209 Database error verifying user’s enrollment in class210 User password does not match user email211 Database error verifying objectID212 objectID does not exist for this user213 objectID does not belong to this user 214 Filename does not exist for this paper215 This primary account ID is not authorized to use this product216 Student limit for this account has been reached. Cannot join student to this class.217 The product for this account has expired. Please contact your sales agent to renew the product218 Database Error inserting unique ID into the database219 Unique user id in the database does not match submitted uid220 More than one class exists with this title and unique ids must be used in this case221 More than one assignment exists with this title and unique ids must be used in this case222 User is associated with a different external uid. If you have another user account with the same email address as the user account you are currently using, that could be the cause of the problem. Please try modifying the email address for your current user account to a unique email address and try again.223 Cannot verify Blackboard user’s identity within TurnitinUK. Missing Blackboard user id224 Could not verify user as primary instructor for this course225 Database error checking if student can view reports



226 The class you are trying to update could not be found. Please check to make sure that the class exists.227 The class you are trying to update has an assignment which ends after the class end date you have specified. Please change you class end date or modify the assignment.228 The assignment with the assignment id that you entered does not belong to the class with the class id you entered. Please check to make sure that you are not using a duplicate assignment id.229 There was an error creating the rollover assignment.230 You have been dropped from this class on the TurnitinUK end by your instructor. Please contact your instructor if you think you are receiving this message in error.231 There was an error processing your request: please try your action again. Please contact the TurnitinUK helpdesk if the problem persists.232 Grademark is currently inactive for this account.233 There was an error accessing this TurnitinUK Assignment because it was created via Course Copy, Snapshot, or some other process, and the original TurnitinUK Assignment could not be found.234 Could not find class with the given unique ID or title.235 Could not find assignment with the given assignment ID or title.236 Could not retrieve assignment info with the given information.237 Could not retrieve grade for the given object.238 Could not find user with the given userid or email.

Inconsistency Errors

300-399

300 Your IP address does not fall within the range of accepted IP addresses as specified by your TurnitinUK account administrator. Please check with your TurnitinUK account administrator if your IP address needs to be added as an accepted IP address.301 Date/time expired – GMT timestamp used in MD5 calculation is off. API calls must have a GMT within 60 minutes of the current GMT301 For Blackboard users. Your request has exceeded the time limit. Perhaps you have left the page open for an extended period of time. Please reload the page and try again.302 MD5 not authenticated - the MD5 in the URL does not match the MD5 calculated

Function Errors

400-499

400 Creating new user failed401 Unauthorized access - user exists, but does not belong to correct primary account ID or sub-account ID, do not execute function402 User is not an instructor, must be an instructor to run this function403 User is not a student, must be a student to run this function404 FCMD is not valid



405 Class title is not unique406 Creating new class failed in fid 2407 Student failed to join or log in to a class in fid 3408 Attempt to join new user to account failed409 Function requires POST request410 Function requires GET request411 Creating/Updating/Deleting assignment failed in fid 4412 Assignment title is not unique413 Error while trying to save the paper414 Originality report not generated yet in fid 6, fcmd 1415 Originality score not available yet in fid 6, fcmd 2416 Error checking if submission existed for user417 Error trying to change user password418 Error trying to delete submission419 Could not create a new assignment. An assignment with this title already exists for this class and instructor. Please change the assignment title.420 Error trying to build up session data for user/class421 Error trying to retrieve paper submission info for assignment422 Updating user information failed423 Updating user information failed because user email was changed to an address that is already associated with an account423 TurnitinUK encountered an error while trying to automatically update your user information. It appears that your Blackboard email address has changed, and when trying to update the corresponding user profile in TurnitinUK, it was discovered that email address already belonged to another user. Please update your email address in your Blackboard user profile to a different email address.424 Updating class title failed425 Error trying to sync grades between servers426 Error trying to sync roster between servers427 Unable to establish web services session with remove webct server428 Unable to create WebCT gradebook column for assignment429 Web services parameters error430 (This is a general web services error – there could be a number of different messages that come with it)431 Error trying to connect back to the Blackboard web service.432 Students are not allowed to view reports in this assignment434 The start time you specified is invalid or not formatted correctly (YYYY-MM-DD HH:MM:SS).435 Error trying to grade submission.436 Intitution repository is not available for this account, please change the submit_ papers_to parameter to either 0 (no repository) or 1 (standard repository).437 The account administrator has set that all papers must be submitted to a repository, please change the submit_papers_to parameter.438 Error trying to set submissions to be stored in a standard repository. The account is using its own private institutional node. Please change the submit_ papers_to parameter.439 The institutional check is not available for this account. Please set the institution_check parameter to 0440 Please specify an email for the new instructor for this course.441 New instructor specified doesn’t exist, please create the user first.442 New Instructor is not joined to this account, please join them to the account



first.443 Anonymous Marking is enabled for this assignment. Cannot download file until after the assignment post date.444 Usage of this account is not currently high enough to generate meaningful statistics. If you would like more information or would like to see these statistics any way, please contact your Turnitin sales representative.445 User login failed.446 Session ID missing from URL

Paper Submission Errors

1000-1099

1000 The due date for this assignment has passed. Please see your instructor to request a late submission.1001 You may not submit a paper to this assignment until the assignment start date1002 You may not submit a paper to this assignment because the Plagiarism Prevention product is unavailable1003 You have reached the maximum limit of 10 papers for the InSite demo account1004 Paper author’s first name missing or incorrect length in URL1005 Paper author’s last name missing or incorrect length in URL1006 Paper title missing1007 The file you have uploaded is too big1008 No file uploaded! Please make sure that you have attached the file that you wish to submit before sending the request1009 Invalid file type! Valid file types are MS Word, Acrobat PDF, Postscript, Text, HTML, WordPerfect (WPD) and Rich Text Format. Please make sure the format of your file is one of the valid file types.1010 You must submit more than 100 characters of non-whitespace1011 The paper you are trying to submit is incorrectly formatted. There seems to be spaces between each letter in your paper. Please try submitting again or contact our help desk if the problem persists.1012 Paper length exceeds limits1013 You must submit more than 20 words of text1014 You must select an enrolled student as the author of this paper1015 You have already submitted a paper to this assignment. Please contact your instructor to request a resubmission1016 This student has already submitted a paper to this assignment. Please delete the original paper before submitting a new one.1017 Paper author’s first name missing or incorrect length in URL1018 Paper author’s last name missing or incorrect length in URL1019 Paper title exceeds maximum of 200 characters1020 This document cannot be accepted because it contains characters from a character set we do not support. 1021 You have already submitted a paper to this assignment. Please contact your instructor to request a resubmission.1022 This student has already submitted a portfolio item to this assignment. Please delete the original portfolio item before submitting a new one.1023 We’re sorry, but we could not read the PDF you submitted. Please make sure that the file is not password protected and contains selectable text rather than scanned images.



Section: Error States

1024 The paper you are trying to submit does not meet our criteria for a legitimate paper. Please try submitting again or contact our help desk if the problem persists.

Assignment Creation Errors

2025-2324

2025 The class name must be between 5-200 characters2026 The class enrollment password must be between 4-12 characters2027 There was an error processing your request2028 The class end date must be within 6 months of the start date2029 The end date for this class must occur on or after today2030 The end date for this class must occur on or after the start date2031 The end date for this class must occur at least 3 months after the start date2032 There was an error updating the class end date2035 There was an error processing your request2036 There was an error processing your request2100 User first name missing from URL2101 User last name missing from URL2102 Email is missing. Please make sure that your email address has been set2110 We only allow email addresses with 5-75 characters2111 The email address cannot contain white space2112 Please make sure you are entering a valid email address. The email address you enter can only contain letters, numbers, and the symbols _ (underscore), - (dash), . (period), ‘ (apostrophe), and + (plus).”2200 The section enrollment password must be between 4-12 characters2201 There was an error processing your request2300 You have entered an invalid date!2301 You must select a rubric set to user with re-mediation2302 The assignment title must be between 2-100 characters2303 The assignment must have a point value between 0 and 10002304 The assignment instructions must be less than 1000 characters2305 The start date for this assignment must occur on or after today2306 The due date for this assignment must occur on or after the start date2307 The due date for this assignment must occur within 6 months of the start date2308 When creating your assignment, the post date must occur on or before the class end date. The class end date in TurnitinUK is by default set to 6 months from the day the class was created. The class end date can be changed in the class update area in TurnitinUK2309 When creating your assignment, please make sure that the post date is on or after the due date of the assignment2310 You must specify a point value for this assignment because this class is using distributed grading2314 When modifying your assignment, please make sure that the post date is on or after the due date of the assignment2315 There was an error processing your request2316 There was an error processing your request2317 There was an error processing your request2318 You cannot change the search targets because papers have already been



Section: Error States

submitted to this assignment. You must create a new assignment if you would like to change the search targets2319 There was an error processing your request2320 There was an error processing your request2321 When excluding small matches by word, you must enter a positive number2324 When excluding small matches by percentage, you must enter a number between 1 and 100


TurnitinUK API Manual Section: FID/FCMD Error Code Table

FID 1,FCMD 1, 2

FID 2,FCMD 1, 2

FID 3,FCMD 1, 2

FID 4,FCMD 1, 2

FID 5,FCMD 1, 2

FID 6,FCMD 1, 2

FID 7,FCMD 1, 2

FID 8,FCMD 1, 2

FID 9,FCMD 1, 2

FID 10,FCMD 1, 2

FID 11,FCMD 1, 2

FID 12,FCMD 1, 2

FID 13,FCMD 1, 2

FID 14,FCMD 1, 2

FID 15,FCMD 1, 2

100 X X X X X X X X X X X X X X X101 X X X X X X X X X X X X X X X102 X X X X X X X X X X X X X X X103 X X X X X X X X X X X X X X X104 X X X X X X X X X X X X X X X105 X X X X X X X X X X X X X X X106 X X X X X X X X X X X X X X X107 X X X X X X X X X X X X X X X108 X X X X X X X X X X X X X X X109 X X X X X X X X X X X X X X X110 X X X X X X X X X X X X X X X111 X X X X X X X X X X X X X X X112 X X X X X X X X X X X X X X X113 X X X X X X X X X X X X X X X114 X X X X X X X X X X X X X X X115 X X X X X X X X X X X X X X X116 X X X X X X X X X X X X X X X117 X X X X X X X X X X X X X X X118 X X X X X X X X X X X X X X X119 X120 X121 X122 X123 X X X X X124 X X X X X125 X126 X127 X X X X X X X X X X X128 X X129 X131 X132 X

URL Errors

FID/FCMD Error Code Table



FID 1,FCMD 1, 2

FID 2,FCMD 1, 2

FID 3,FCMD 1, 2

FID 4,FCMD 1, 2

FID 5,FCMD 1, 2

FID 6,FCMD 1, 2

FID 7,FCMD 1, 2

FID 8,FCMD 1, 2

FID 9,FCMD 1, 2

FID 10,FCMD 1, 2

FID 11,FCMD 1, 2

FID 12,FCMD 1, 2

FID 13,FCMD 1, 2

FID 14,FCMD 1, 2

FID 15,FCMD 1, 2

200 X X X X X X X X X X X X X X X201 X X X X X X X X X X X X X X X202 X X X X X X X X X X X X X X X203 X X X X X X X X X X X X X X X204 X X X X205 X X X X206 X X X X207 X X X X208 X X X X 209 X X X X210 X X X X211 X X X X X212 X X X X X213 X X X X X214 X215 X X X X X X X X X X X X X X X216 X X217 X X X X X X X X X X X X X X X218 X X X X X X X X X X X X X219 X X X X X X X X X X X220 X X X X X X X221 X X X X X222 X X X X X X X X X X X X X223 X X X X X X X X X224 X X X X X X X X X225 X X X X226 X X227 X X232 X234235236237 X238

TurnitinUK Database Errors

300 X X X X X X X X X X X X X X X301 X X X X X X X X X X X X X X X302 X X X X X X X X X X X X X X X

Inconsistency Errors



FID 1,FCMD 1, 2

FID 2,FCMD 1, 2

FID 3,FCMD 1, 2

FID 4,FCMD 1, 2

FID 5,FCMD 1, 2

FID 6,FCMD 1, 2

FID 7,FCMD 1, 2

FID 8,FCMD 1, 2

FID 9,FCMD 1, 2

FID 10,FCMD 1, 2

FID 11,FCMD 1, 2

FID 12,FCMD 1, 2

FID 13,FCMD 1, 2

FID 14,FCMD 1, 2

FID 15,FCMD 1, 2

400 X X X X401 X X X X402 X X X403 X404 X X X X X X X405 X406 X X407 X408 X X409 X X410411 X412 X X X X X X413 X414 X415 X416 X417 X418 X419 X420 X421 X422 X X X X X X X X X X X423 X X X X X X X X X X X424 X X X X X X X425426427428429430431432433 X434 X435 X437 X X

Function Errors



Section: FID/FCMD Error Code Table

FID 1,FCMD 1, 2

FID 2,FCMD 1, 2

FID 3,FCMD 1, 2

FID 4,FCMD 1, 2

FID 5,FCMD 1, 2

FID 6,FCMD 1, 2

FID 7,FCMD 1, 2

FID 8,FCMD 1, 2

FID 9,FCMD 1, 2

FID 10,FCMD 1, 2

FID 11,FCMD 1, 2

FID 12,FCMD 1, 2

FID 13,FCMD 1, 2

FID 14,FCMD 1, 2

FID 15,FCMD 1, 2

439 X X440 X441 X442 X443 X444 X

FID 17,FCMD 2

FID 18,FCMD 1, 2

445 X446 X



FID 1,FCMD 1, 2

FID 2,FCMD 1, 2

FID 3,FCMD 1, 2

FID 4,FCMD 1, 2

FID 5,FCMD 1, 2

FID 6,FCMD 1, 2

FID 7,FCMD 1, 2

FID 8,FCMD 1, 2

FID 9,FCMD 1, 2

FID 10,FCMD 1, 2

FID 11,FCMD 1, 2

FID 12,FCMD 1, 2

FID 13,FCMD 1, 2

FID 14,FCMD 1, 2

FID 15,FCMD 1, 2

1000 X1001 X1002 X1003 X1004 X1005 X1006 X1007 X1008 X1009 X1010 X1011 X1012 X1013 X1014 X1015 X1016 X1017 X1018 X1019 X1020 X1021 X1022 X1023 X1024 X

Paper Submission Errors



FID 1,FCMD 1, 2

FID 2,FCMD 1, 2

FID 3,FCMD 1, 2

FID 4,FCMD 1, 2

FID 5,FCMD 1, 2

FID 6,FCMD 1, 2

FID 7,FCMD 1, 2

FID 8,FCMD 1, 2

FID 9,FCMD 1, 2

FID 10,FCMD 1, 2

FID 11,FCMD 1, 2

FID 12,FCMD 1, 2

FID 13,FCMD 1, 2

FID 14,FCMD 1, 2

FID 15,FCMD 1, 2

2025 X2026 X2027 X2028 X2029 X2030 X2031 X2032 X2033 X2034 X2035 X2036 X2100 X X X X X X X X X X X X X X X2101 X X X X X X X X X X X X X X X2102 X X X X X X X X X X X X X X X2110 X X X X X X X X X X X X X X X2111 X X X X X X X X X X X X X X X2112 X X X X X X X X X X X X X X X2300 X2301 X2302 X2303 X2304 X2305 X2306 X2307 X2308 X2309 X2310 X2311 X2312 X2313 X2314 X2315 X2316 X2317 X2318 X2319 X2320 X

Assignment Creation Errors



FID 1

FID 2

FID 3

FID 4

FID 5

FID 6

FID 7

FID 8

FID 9

FID 10

FID 11

FID 12

FID 13

FID 14

FID 15

aid X X X X X X X X X X X X X X Xainst Xassign X X X X X X Xassignid X X X X X X Xced X Xcid X X X X X X X Xcpw Xctl X X X X X X X Xdiagnostic X X X X X X X X X X X X X X Xdis X X X X X X X X X X X X X X Xdtdue Xdtstart Xencrypt X X X X X X X X X X X X X X Xfcmd X X X X X X X X X X X X X X Xfid X X X X X X X X X X X X X X Xgmtime X X X X X X X X X X X X X X Xnewassign Xnewupw Xoid X X X Xpdata Xpfn Xpln Xptl Xptype Xsaid X X X X X X X X X X X X X X Xsession-id X X X X X X X X X X X X X X Xtem X X X X X Xuem X X X X X X X X X X X X X X Xufn X X X X X X X X X X X X X X Xuid X X X X X X X X X X X Xuln X X X X X X X X X X X X X X Xupw X X X X X Xusername X X X X X X X X X X X X X X Xutp X X X X X X X X X X X X X X Xmd5 X X X X X X X X X X X X X X X

FID/Data Elements Table

Data Elements to Include in Request

Note: Blue X’s are to indicate optional variables for that FID


TurnitinUK API Manual Section: FID/MD5 Table

FID 1

FID 2

FID 3

FID 4

FID 5

FID 6

FID 7

FID 8

FID 9

FID 10

FID 11

FID 12

FID 13

FID 14

FID 15

aid X X X X X X X X X X X X X X Xainstassign X X X X X X Xassignid X X X X X X Xced X Xcid X X X X X X X Xcpw Xctl X X X X X X X Xdiagnostic X X X X X X X X X X X X X X Xdis X X X X X X X X X X X X X X Xdtdue Xdtstart Xencrypt X X X X X X X X X X X X X X Xfcmd X X X X X X X X X X X X X X Xfid X X X X X X X X X X X X X X Xgmtime X X X X X X X X X X X X X X Xnewassign Xnewupw Xoid X X Xpdatapfn Xpln Xptl Xptype Xsaid X X X X X X X X X X X X X X Xtem X X X X X Xuem X X X X X X X X X X X X X X Xufn X X X X X X X X X X X X X X Xuid X X X X X X X X X X X X X X Xuln X X X X X X X X X X X X X X Xupw X X X X X Xusername X X X X X X X X X X X X X X Xutp X X X X X X X X X X X X X X Xmd5 X X X X X X X X X X X X X X X

FID/MD5 Table

Data Elements to Include in the MD5

Note: A general rule when preparing the MD5 string is to include in the string all the values of the data elements that have a value set.


TurnitinUK API Manual Section: FID/Encrypt Data Table

FID 1

FID 2

FID 3

FID 4

FID 5

FID 6

FID 7

FID 8

FID 9

FID 10

FID 11

FID 12

FID 13

FID 14

FID 15

aidainstassign X X X X X X Xassignid X X X X X X Xcedcid X X X X X X X Xcpw Xctl X X X X X X X Xdiagnosticdisdtduedtstartencryptfcmdfidgmtimenewassign Xnewupw Xoid X Xpdatapfn Xpln Xptl Xptype Xsaid X X X X X X X X X X X X X X Xtem X X X X X Xuem X X X X X X X X X X X X X X Xufn X X X X X X X X X X X X X X Xuid X X X X X X X X X X X X X X Xuln X X X X X X X X X X X X X X Xupw Xusername X X X X X X X X X X X X X X Xutp X X X X X X X X X X X X X X Xmd5

FID/Encrypt Data Table

Data Elements to Encrypt if Flag is Set


FID FCMD Function Description GET/POST/BOTH?1 1 Create a user and login BOTH1 2 Create a user BOTH

2 1Create a class under the given account and assign (create if necessary) user as the instructor of the class and login

BOTH

2 2Create a class under the given account and assign (create if necessary) user as the instructor of the class

BOTH

2 3 Modify a class BOTH

3 1 Join the given class as a student (create user if necessary) BOTH

3 2 Join the given class as a student (create user if necessary) BOTH

4 1 Create an assignment through the TurnitinUK assignment creation screen BOTH

4 2 Create an assignment under the given account and given class POST

4 3 Modify an assignment under the given account and given class POST

4 4 Delete the assignment under the given account and given class POST

4 5 Modify an assignment through the TurnitinUK assignment modification screen BOTH

5 1 Submit a paper through the TurnitinUK submission screen BOTH

5 2 Submit a paper to the given account, class, assignment POST

6 1 Retrieve the originality report (or link) for the given object ID BOTH

6 2 Retrieve the originality score for the given object ID BOTH

7 1 View original paper BOTH7 2 Download original paper BOTH8 2 Delete Submission BOTH9 2 Change password BOTH

10 1 List all submissions in the TurnitinUK inbox screen BOTH

10 2 List all submissions for given assignment BOTH11 2 Check if user has submitted to assignment BOTH12 1 Show administrator statistics for account BOTH

13 1 The API opens a new window containing the specified GradeMark paper BOTH

13 2 The API retrieves GradeMark for the given object ID BOTH

14 2The API returns the average originality report turnaround times in seconds for the time intervals of 1, 5, 10 and 15 minutes

BOTH

15 2 The API retrieves the score for a GradeMark paper BOTH

15 3 The API sets the score for a GradeMark paper BOTH

GET/POST Requirements for Functions



Section: GET/POST Requirements for Functions

FID FCMD Function Description GET/POST/BOTH?

16 1The API redirects the user to the Administrator Log page for Anonymous Marking

BOTH

17 2The API function will log in the user described by the user email, first name, last name, and user type.

BOTH

18 2

The API function will log out the user described by the user email, first name, last name, and user type and end the Session with session-id.

BOTH


FID FCMD Function Description Creates Profile?1 1 Create a user and login YES1 2 Create a user YES2 1 Create a class under the given account

and assign (create if necessary) user as the instructor of the class and login

YES

2 2 Create a class under the given account and assign (create if necessary) user as the instructor of the class

YES

2 3 Modify a class YES3 1 Join the given class as a student (create

user if necessary) YES

3 2 Join the given class as a student (create user if necessary) YES

4 1 Create an assignment through the TurnitinUK assignment creation screen YES

4 2 Create an assignment under the given account and given class YES

4 3 Modify an assignment under the given account and given class YES

4 4 Delete the assignment under the given account and given class YES

4 5 Modify an assignment through the TurnitinUK assignment modification screen YES

5 1 Submit a paper through the TurnitinUK submission screen NO

5 2 Submit a paper to the given account, class, assignment NO

6 1 Retrieve the originality report (or link) for the given objectID NO

6 2 Retrieve the originality score for the given object ID NO

7 1 View original paper NO7 2 Download original paper NO8 2 Delete Submission NO9 2 Change password NO

10 1 List all submissions in the TurnitinUK inbox screen NO

10 2 List all submissions for given assignment NO11 2 Check if user has submitted to assignment NO12 1 Show administrator statistics for account NO13 1 The API opens a new window containing

the specified GradeMark paper NO

13 2 The API retrieves GradeMark for the given object ID NO

14 2The API returns the average originality report turnaround times in seconds for the time intervals of 1, 5, 10 and 15 minutes

NO

15 2, 3The API either retrieves or sets score for a GradeMark paper NO

Functions which Create User Profiles


Glossary

Glossary


Glossary Section: Definitions

Definitions

aid - the primary account id (must not be encrypted)

ainst - assignment instructions

assign - title of the assignment a paper is being submitted to (unique for that class)

assignid - unique assignment id. Either third party id, or possibly a unique TurnitinUK assignment id

ced - to allow students to submit files, an instructor must create a class for their students. A class requires a name, a class ID, and a class enrollment password

cid - unique class id. Either a third party id, or possibly a unique TurnitinUK class id

cpw - class enrollment password (only applicable if fid=2 or 3)

ctl - class title (only applicable if fid=2 or 3)

diagnostic - the diagnostic flag provides diagnostic output for API debugging. When enabled it will only validate request but will not perform any action.

dis - email notification. By default, email notifications are sent for user creation, class creation, student class enrollment, and paper submission (digital receipt). Setting this flag to 1 disables these notifications

dtdue - date the assignment is due (in YYYYMMDD format)

dtstart - date the assignment begins (in YYYYMMDD format)

encrypt - the encryption flag. The encryption flag can be set to 0 (off) or 1 (on). If encryption is enabled, the following user sensitive data must be encrypted using your shared secret key with the Blow-fish encryption scheme: said, uem, upw, ufn, uln, utp, ctl, cpw, tem

fcmd - the numeric API function specific command

fid - the numeric API command. The fid determines the function that the API will perform

gmtime - the GMT timestamp. The timestamp must be sent in the form YYYYMMDDHHM. The TurnitinUK server clocks are kept synchronized using the network time protocol

md5 - the MD5 signature is generated by a concatenating the data values associated with specific URL variables arranged in alphabetical order according to variable name. The shared secret key is included at the end of the MD5 string

newassign - new title for the assignment if modifying assignment (only applicable if fid=4)

npw - new password to change to

oid - unique Object ID of paper for which to generate report for, view or download paper

pdata - paper in original format (fid=5)

pfn: author of paper’s first name (used only for fid=5)

pln: author of paper’s last name (used only for fid=5)


Glossary Section: Definitions

ptl - title of paper being submitted (used only for fid=5)

ptype - type of file (1=text, 2=file)(fid=5)

said - sub-account id. The sub-account id is optional. If a sub-account is included, it must be an account beneath the primary account

shared secret key - Before you can begin calling the TurnitinUK API, you must provide a TurnitinUK representative with a shared secret key. This key will be used in calculating an MD5 signature for all your API requests and to encrypt your data, if you choose to, using Blowfish encryption. The shared secret key is included at the end of the MD5 signature

tem - email of instructor who created class (only applicable if fid=3)

uem - user email. The user email is used as the TurnitinUK user name. The email address must be 6-50 characters in length

ufn - user first name. Must be 1-50 characters in length

uid - unique user id. Either a third party user id, or possibly a unique TurnitinUK user id

uln - user last name. Must be 1-50 characters in length

upw - user password. The user password is optional, must be 6-12 characters in length, and must contain at least one letter and one number. If this variable is not in-cluded and the user is not already registered, we will automatically generate a password and email it to

the user

username - the user name

utp - user type. 1 for students, 2 for instructors and 3 for administrators

Date post:	26-Nov-2014
Category:	Documents
Upload:	philiptubman
View:	806 times
Download:	10 times

API Manual

Documents