This is a simple Perl script that shows an example usage of the Turnitin for Admissions XML-RPC interface.
iParadigms provides this example code to help developers integrate applications with Turnitin for Admissions. Not every API method is included, and very few non-standard return values are examined. Developers should develop more robust code than provided in the simple examples below. This is just intended as a primer for new users.
The account credentials and one or more files are passed to the script and response output is shown if the --verbose flag is included.
See API documentation for more information.
./tiifa_api_example.pl \ --email $USERNAME \ --password $PASSWORD \ --file test.txt test.pdf \ --folder_id 1234 \ --group_name 'api_test_group' \ --folder_name 'api_test_folder' \ --endpoint $URL \ --notify_url $CALLBACK_URL \ --title 'some title' \ --author_first 'First' \ --author_last 'Lastname' \ --author_email 'firstname.lastname@example.org' \ --owner_id '123-abc-456' \ --sample_text \ --add_to_index \ --queue_report \ --verbose email (required) email address used to log into the account. password (required) password used with email that make up credentials for accessing the account. Note: Passing the password on the command line is considered insecure on a shared server. folder_id ID of folder where to upload. This takes precedence over specifying group_name and folder_name. group_name (default "api_test_group") "Folder group" name used when uploading. Each account has one or more folder groups and each folder group holds zero or more folders. The folder group is created is a folder group of the same name is not found. folder_name (default "api_test_folder" The folder name used when uploading the document. The folder is created if a folder of the same name is not found. It is created within the specified folder group. file Specifies one or more files to upload. queue_report Queue document for report generation. add_to_index Request document is added to the index. sample_text If this flag is specified will upload some simple text that is hard-coded into this program. This shows how to upload text directly. Any files specified with --files will be included. poll Specifies a document id to poll until ready until exceeds the poll_timeout seconds. Using this method will skip uploading of any files. poll_timeout (default 120) This integer value is the number of seconds to wait while polling for a document to be complete. endpoint Specify the URL of the XMLRPC server endpoint. Defauls to: https://api.turnitinadmissions.com/rpc notify_url This is a URL that will called with a GET request when each report is completed and ready to view. For example: --notify_url 'http://example.com/notify?my_id=1234 Might result with a GET request to example.com with the request /notify?my_id=1234&document_id=154007&report_id=154198&word_count=217&part=1&total_parts=1&percent_match=20 where: document_id ID assigned to the uploaded document. word_count total words found in the document. part This should always be 1 unless the document is very large and must be split into parts. Large is about 75,000 words, but subject to change. total_parts Total parts for the document. percent_match The Originality Score. The response from this URL is ignored. (This is the "callback_url" request parameter.) verbose When specified this flag will cause every response to be printed.
RPC::XML Getopt::Long LWP::UserAgent Crypt::SSLeay (and OpenSSL) RPC::XML provides automatic conversion between Perl data types and XML-RPC data types.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Log in. Every request (except the login method) must include a session id. Logging in provides that session id.
Pass in folder id and one or more files to upload.
Now that we have a folder id we are ready to upload one or more documents.
Uploads are simply XMLRPC base64-encoded elements. Most client libraries provide a way to supply a file handle for the upload. This avoids the need to bring the entire file into memory.
Now we poll until the document has been processed. When finished we will have a report id that can be used to access the report URL.
Copyright (C) (2011) iParadigms, LLC. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.