NAME WebService::iThenticate::Client - a client class to access the iThenticate service SYNOPSIS # construct a new client $client = WebService::iThenticate::Client->new({ username => $username, password => $password, url => 'https://api.ithenticate.com:443/rpc', # default https://test.api.ithenticate.com:443/rpc }); # authenticate the client, returns an WebService::iThenticate::Response object $response = $client->login; # access the session id from the response object $sid = $response->sid; # submit a document $response = $client->add_document({ title => 'Moby Dick', author_first => 'Herman', author_last => 'Melville', filename => 'moby_dick.doc', folder => 72, # folder id submit_to => 1, # 1 => 'Generate Report Only' upload => `cat moby_dick.doc`, # binary content of document # the client module will base64 and chunk it }); # get the newly created document id $document_id = $response->id; $document = $response->document; # get the document parts (note use of hash reference instead of object method) $parts = $document->{parts}; DESCRIPTION This module provides a client library interface to the iThenticate API web services. It encapsulates different transport engines to provide a set of methods through which the user can access the iThenticate API programmatically. See the iThenticate API reference web page at http://www.ithenticate.com/faq.html for more details. METHODS CONSTRUCTORS AND AUTHENTICATION new() # construct a new client $client = WebService::iThenticate::Client->new({ username => $username, password => $password, host => 'api.ithenticate.com', # default test.api.ithenticate.com path => 'rpc', # default rpc port => 3000, # default 3000 }); Returns an WebService::iThenticate::Response object credentials() # pass basic auth credentials to the client $client->credentials({ realm => 'My Authenticated Realm', username => 'foo@example.com', password => 'zimzamfoo123', }); login() # authenticate the client, returns an WebService::iThenticate::Response object $response = $client->login; # access the session id from the response object $sid = $response->sid; The session id (sid) is stored internally in the client for future authentication so there is no need to pass it explicitly FOLDER GROUPS add_folder_group() # add a folder group $response = $client->add_folder_group({ name => 'iThenticate', }); $folder_group_id = $response->id; list_folder_groups() # list folder groups $response = $client->list_folder_groups; # returns an array reference of hash references holding the folder group data owned by the api user $folder_groups = $response->groups; # Example response data: # $folder_groups->[0] = { id => 1, name => 'First Folder Group' }; group_folders() # returns all the folders in a group $response = $client->group_folders({ id => $folder_group_id }); # returns an array reference of folder hashes $folders = $response->folders; # Example response data: # $folders->[0] = { id => 1, # name => 'First Folder', # group => { # id => 1, # name => 'First Folder Group', }, }; drop_group() # remove a folder group $response = $client->drop_group({ id => $folder_group_id }); # Returns a message on successful response, with no errors if (!$response->errors && $response->messages->[0] eq "Group \"$folder_group_id\" removed") { print "Group $folder_group_id dropped successfully\n"; } FOLDERS add_folder() # add a folder $response = $client->add_folder({ name => 'API Specification', description => 'Holds documentation referencing the iThenticate API', folder_group => 79, # id of the folder group exclude_quotes => 1, # 1 (true), or 0 (false) add_to_index => 1, # 1 (true), or 0 (false), needed if account has # a private storage node }); # returns the id of the newly created folder $folder_id = $response->id; get_folder() # get a folder and related documents $response = $client->get_folder({ id => $folder_id }); # see group_folders() for folder response data format $folder = $response->folder; # get the documents for this folder $documents = $response->documents; # Example document data # $documents->[0] = { author_first => 'Jules', author_last => 'Varne', # is_pending => 1, percent_match => '83.2', # processed_time => '94.3', title => '10,000 Leagues Over The Sea', # parts => $parts, uploaded_time => '2008-03-13 07:35:35 PST', # id => 1, }; # Example document parts data # $parts->[0] = { part_id => 1, doc_id => 1, score => '95.2', word => 456, }; list_folders() # returns all the folders for a user $response = $client->list_folders(); # returns an array reference of folder hashes $folders = $response->folders; # see get_folder() for the response folder data example trash_folder() # move a folder to the trash $response = $client->trash_folder({ id => $folder_id }); print "Folder trashed ok!" if ( !$response->errors && $response->messages->[0] eq 'Moved to Trash' ); DOCUMENTS add_document() # submit a document $response = $client->add_document({ title => 'Moby Dick', author_first => 'Herman', author_last => 'Melville', filename => 'moby_dick.doc', # binary content of document # the client module will base64 and chunk it # note - don't actually use backticks like shown here :) upload => `cat moby_dick.doc`, folder => 72, # folder id # options 2 and 3 only available for accounts with private nodes submit_to => 1, # 1 => 'Generate Report Only' # 2 => 'to Document Repository Only' # 3 => 'to Document Repository & Generate Report' }); # get the newly created document id $document_id = $response->id; $document = $response->document; # see get_folder() for the response data format for the document get_document() # check the status of a document submission $response = $client->get_document({ id => $document_id, }); # access the document attributes from the response $document_id = $response->id; # returns an array reference of document part hash references $document_parts = $document->{parts}; # see get_folder() for the document and document parts data formats trash_document() # move a document to the trash $response = $client->trash_document({ id => $document_id }); REPORTING get_report() # get an get report $response = $client->get_report({ id => $document_part_id, }); # see if the report is ready if ( $response->errors && ( $response->status == 404 ) ) { # the report may still be in progress if ( $response->messages->[0] =~ m/report in progress/i ) { print "Report is still being prepared, please try later\n"; } else { print STDERR "Report not found found document part $document_part_id\n"; } } else { # report is ready, see WebService::iThenticate::Response for report object details $report = $response->report; $report_url = $report->{view_only_url}; # save the report content to disk $grab_report = `wget --output-document=$HOME/reports/new.html $report_url`; } ACCOUNTS get_account() # get the account status $response = $client->get_account; $account_status = $response->account_status; USERS add_user() # add a user $response = $client->add_user({ first_name => 'Joe', last_name => 'User', email => 'joe@user.com', password => 'swizzlestick123', }); $user_id = $response->id; put_user() # update a user's information $response = $client->put_user({ email => 'joeuser@gmail.com', }); if ( $response->messages->[1] eq 'Email updated for user joeuser@gmail.com' ) { print 'got the right message'; } drop_user() # delete a user from the account $response = $client->drop_user({ id => $user_id }); print 'some errors occurred' if $response->errors; list_users() # users listing $response = $client->list_users; # returns a an array reference of user data in hashes $users = $response->users; # Example user data format # $users->[0] = { id => 1, email => 'jules@varne.com', # first_name => 'Jules', last_name => 'Varne', }; TESTING To enable testing against the iThenticate live test API, set the following environment variables before running 'make test'. IT_USERNAME IT_PASSWORD IT_API_URL See your iThenticate account representative to obtain these credentials to the API testing environment. BUGS IT_API_URL If you receive an error back from the server that looks like 'mismatched tag' then you likely have an invalid url specified for IT_API_URL instead of an actual mismatched tag in the request xml. FAQ Q: Why doesn't this code do X? A: Because that feature hasn't been requested yet :) Q: How is this module related to iThenticate::API::Client? A: This module takes the place of iThenticate::API::Client in a more generally accepted namespace SEE ALSO WebService::iThenticate::Request, WebService::iThenticate::Response, RPC::XML, SOAP::Lite AUTHOR Fred Moyer COPYRIGHT Copyright 2008 iParadigms LLC