ElectricCommander's features can be accessed in three ways.
- 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.
- 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.
- 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.
An ectool command consists of four elements:
- global arguments
- required arguments
- optional arguments
For example, the command:
breaks down like this:
|global arguments||--server vm-xpsp2|
|required arguments||"Test Resource"|
|optional arguments||--description "Create for Testing"|
The Perl API has the same four elements as ectool, but the way that they are specified is quite different.
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:
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:
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.
For each subcommand, there is a corresponding function for the ElectricCommander object. For example, to retrieve a list of jobs, use:
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:
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:
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.
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.
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.