9. Web Services

To access Inca from a Web services API, you will need to install the Inca web services component, incaws.

% wget http://inca.sdsc.edu/releases/2.3/incaInstall.sh
% sh incaInstall.sh $INCA_DIST incaws

The results should look similar to:

Retrieving http://inca.sdsc.edu/releases/latest/Inca-WS.tar.gz
--12:59:23--  http://inca.sdsc.edu/releases/latest/Inca-WS.tar.gz
           => `Inca-WS.tar.gz'
Resolving inca.sdsc.edu...
Connecting to inca.sdsc.edu||:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 1,226,347 (1.2M) [application/x-tar]

100%[====================================>] 1,226,347     --.--K/s             

12:59:23 (81.68 MB/s) - `Inca-WS.tar.gz' saved [1226347/1226347]

Unpacking http://inca.sdsc.edu/releases/latest/Inca-WS.tar.gz
Will install Inca prerequisite Net::SSLeay
Will install Inca prerequisite IO::Socket::SSL
Will install Inca prerequisite Expat
Will install Inca prerequisite LWP::UserAgent
Will install Inca prerequisite MIME::Base64
Will install Inca prerequisite SOAP::Lite
Writing Makefile.perl.inc for Inca-WS
Inca-WS installed

To start incaws, specify the port, credentials, and hostname/port for the Inca agent and depot as below. Replace "origHost", "agentHost" and "depotHost" with the correct names for your installation.

% ./bin/inca incaws \
 --auth=yes \
 --cert=etc/agentcert.pem \
 --key=etc/agentkey.pem \
 --trusted=etc/trusted/origHostcert.pem \
 --port=8001 \
 --password=yes \
 depotHost:6324 \
enter password (no prompt displayed)

Check to make sure the incaws is running on port 8001:
% netstat -an | grep 8001
tcp4       0      0  *.8001                 *.*                    LISTEN
Error logs are in $INCA_DIST/var.

The WSDL file for the incaws component is in $INCA_DIST/etc/IncaWS.wsdl. The following table summarizes the available functions.

Table 6. Web services functions



getCatalog( [$url] )

Asks the agent to retrieve and return the package catalog from the reporter repository accessed via $url. An undefined $url indicates that the agent should return a merged catalog for all known repositories.


Asks the agent to return XML for the Inca deployment configuration.

pingAgent( $string )

Check that the Inca agent is accessible.

pingDepot( $string )

Check that the Inca depot is accessible.


Asks the depot to return a space-separated list of known suite guids.


Asks the depot use the HQL select statement $hql to extract and return information from the DB. On success, returns a reference to an array that contains the objects selected by the select statement.

queryInstance($instanceId, $configId)

Asks the depot to report details about one particular invocation of a reporter. $instanceId is the DB id of the instance for the invocation; $configId the related series configuration DB id. On success, returns a reference to a single-element array that contains a ReportDetails document describing the instance.


Asks the depot to retrieve information about all instances related to the series configuration identified by $configId. On success, returns a reference to an array that contains a set of ReportDetail documents related to the series.


Asks the depot to retrieve information about all the series of the suite identified by $guid. On success, returns a reference to an array that contains a set of ReportSummary documents related to the series configurations of the suite.

Below shows an example of how to access the Inca web services from Perl using SOAP::Lite.

use SOAP::Lite;
use Cwd;

my $cwd = getcwd();
my $ws = SOAP::Lite->service("file:$cwd/etc/IncaWS.wsdl");

# check agent and depot are available
print $ws->pingAgent('hello agent'), "\n";
print $ws->pingDepot('hello depot'), "\n";

# get the Inca configuration
print $ws->getConfig(), "\n";
my $guid = $ws->queryGuids();

# get the latest instances of a suite
my $results = $ws->querySuite( $guid );
for my $result ( @{$results} ) {
  print $result;

Place the above code in a file called $INCA_DIST/sampleWS.pl and set the environment variable PERL5LIB to $INCA_DIST/lib/perl. Then type,

% perl sampleWS.pl

When run against the default installation, the results should look similar to below.

hello agent
hello depot
<inca:inca xmlns:inca="http://inca.sdsc.edu/dataModel/inca_2.0">
        <xpath>//resource[matches(name, "localSite")]</xpath>
          <uri>http:// ... cluster.math.atlas.version</uri>

<reportSummary xmlns="http://inca.sdsc.edu/queryResult/reportSummary_2.0">
  <hostname xmlns="">localResource</hostname>
  <uri xmlns="">http:// ... cluster.math.atlas.version</uri>
  <nickname xmlns="">atlas_version</nickname>
  <seriesConfigId xmlns="">1</seriesConfigId>
  <instanceId xmlns="">24</instanceId>
  <gmt xmlns="">2007-02-01T13:21:01.000-08:00</gmt>
  <body xmlns:rep="http://inca.sdsc.edu/dataModel/report_2.1" xmlns=""/>
  <errorMessage xmlns="">Cannot locate ATLAS installation; use