DESCRIPTION

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.

Script Usage:

    ./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 'author@example.com' \
        --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.

Dependency Modules:

    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.

login_user

Log in. Every request (except the login method) must include a session id. Logging in provides that session id.

upload_files

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.

poll_upload

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

Copyright (C) (2011) iParadigms, LLC. All rights reserved.

LICENSE

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.