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 <fred@iparadigms.com>
COPYRIGHT
Copyright 2008 iParadigms LLC