KBEC-00020 - Calling the ElectricCommander Perl API

Summary

ElectricCommander's features can be accessed in three ways.

1. The most common way to access ElectricCommander is through the Web UI. The GUI provides web pages to create projects and procedures, launch jobs and manage all ElectricCommander administration tasks.
2. Accessing ElectricCommander using "ectool" - a command-line interface that can be used directly from a command line, from a shell script, or from a batch file. It can do anything and everything that the Web UI can do because they both rely on the same interface to the ElectricCommander server. "ectool" is intended to make it easy to script ElectricCommander operations. The ElectricCommander online help system lists and describes ectool commands and arguments. You can also access and download the help system from the Electric Cloud Community Web Site.
3. Accessing ElectricCommander using the Perl API, which is delivered as a Perl package, named ElectricCommander.pm. The Perl API provides exactly the same API as "ectool." This article is a guide for translating "ectool" commands into Perl API calls.

Solution

ectool command structure

An ectool command consists of four elements:

1. global arguments
2. subcommand
3. required arguments
4. optional arguments

For example, the command:

ectool --server vm-xpsp2 createResource "Test Resource" --description "Create for Testing"

breaks down like this:

Perl API structure

The Perl API has the same four elements as ectool, but the way that they are specified is quite different.

Specifying global options

To use the ElectricCommander Perl API, create an ElectricCommander object. The global arguments are specified at the time the object is created. These arguments are passed as members of an anonymous hash, as shown in the example:

use ElectricCommander ();
$ec = new ElectricCommander->new({
        server      =>  "vm-xpsp2",
        port        =>  "8000",
        securePort  =>  "8443",
        secure      =>  "",
});

In the example above, port options are not really necessary because they just specify default values. The following is a shorthand form when you just want to specify the name of the server:

use ElectricCommander ();
$ec = new ElectricCommander->new("vm-xpsp2");

Or use an even simpler form if you are calling the Perl API from a script running as part of an ElectricCommander job step. In this case, the ElectricCommander package sets the server name based in the environment variable, COMMANDER_SERVER set by the ElectricCommander agent.

use ElectricCommander ();
ec = new ElectricCommander->new();

Specifying a subcommand

For each subcommand, there is a corresponding function for the ElectricCommander object. For example, to retrieve a list of jobs, use:

use ElectricCommander ();
$ec = new ElectricCommander->new();
$ec->getJobs();

Specifying required arguments

Most subcommands have required arguments. Required arguments are passed in a list, just like any Perl function arguments. For example, setProperty has two required arguments, propertyPath and value:

use ElectricCommander ();
$ec = new ElectricCommander->new();
$ec->setProperty("/projects/test/buildNumber", "22");

Specifying optional arguments

Some subcommands can take one or more optional arguments also. These arguments are passed in a Perl "anonymous hash", where keys correspond to the optional argument name and hash values are values of the optional arguments. Here is another call to setProperty with two optional arguments in addition to the required arguments:

use ElectricCommander ();
$ec = new ElectricCommander->new();
$ec->setProperty("filename", "temp.xml",
    {jobId       => $ENV{COMMANDER_JOBID},
     description => "File for storing output" });

Handling return values

Every function to the ElectricCommander object returns an object of type XML::XPath. This object returns a parsed representation of ElectricCommander's returned XML block. See documentation on CPAN for more information.

use ElectricCommander ();
$ec = new ElectricCommander->new();
$xPath = $ec->setProperty("filename", "temp.xml",
    {jobId       => $ENV{COMMANDER_JOBID},
     description => "File for storing output" });
print "Return data from Commander:\n" .
    $xPath->findnodes_as_string("/") . "\n";

Error handling

If a function call to the ElectricCommander object encounters an error, by default it "dies" inside Perl and prints an error message. If you want error messages ignored and processing to continue, set a flag to disable internal error handling and then handle the error in your code.

use ElectricCommander ();
$ec = new ElectricCommander->new();
$ec->abortOnError(0);
$xPath = $ec->getResource("NonExistant Resource");

if ($xPath) {
    my $code = $xPath->findvalue('//code');
    if ($code ne "") {
        my $mesg = $xPath->findvalue('//message');
        print "Returned code is '$code'\n$mesg\n";
        exit 1;
    }
}

The Windows version The Windows version of ElectricCommander (Server, Agent, or Tools) includes a Perl interpreter that has all of the necessary packages installed to be able to run the examples.