Use the CloudBees CD/RO Perl API

9 minute readReferenceDeveloper productivity

You can use the CloudBees CD/RO Perl API for the following operations:

  • Model and deploy applications

  • Create and manage resources

  • Create environment models and add resources to them

  • Model and run pipelines

  • Model and run releases

  • Create and call procedures

  • Create and manage artifacts

  • Create and manage object properties

The Perl API can be used from a command-line interface, in a shell script, or in a batch file. It supports ectool and cb-perl commands:

  • ectool is a command-line tool developed to script CloudBees CD/RO operations. Refer to Use the CloudBees CD/RO ectool API.

  • cb-perl is delivered as a Perl package during CloudBees CD/RO installation, or you can use any Perl of your choice. Refer to Use cb-perl for details.

Use cb-perl

When a CloudBees CD/RO component is installed—server, agent, or tools (using the express or advanced installation type)—a copy of Perl is installed. This copy is pre-configured with all the packages you need to run the CloudBees CD/RO Perl API. CloudBees CD/RO does not, however, automatically add this version of Perl to your path because:

  • The CloudBees CD/RO installation must not interfere with existing scripts, which depend on finding another copy of Perl you already use.

  • Special environment variables need to be set before calling Perl.

Both of these issues are addressed with a small wrapper program called cb-perl. The wrapper is installed as part of CloudBees CD/RO, and it is in a directory that is added to your path. When the cb-perl wrapper runs, it sets up the environment, finds and calls the CloudBees CD/RO copy of Perl, and passes its parameters to Perl.

To run cb-perl from a command line (or in a CloudBees CD/RO step) enter:

cb-perl yourPerlOptions yourPerlScript.pl

The Perl script can include API calls to CloudBees CD/RO with no other special handling required.

For a CloudBees CD/RO step, you can enter the Perl script directly into the "Command" field, and set the "Shell" field to cb-perl. The CloudBees CD/RO-installed Perl is used to process the Perl script.

You can develop Perl scripts to access the Perl API directly. Because ectool uses the Perl API to execute its commands, any ectool command you can execute can be executed using the Perl API. If you are writing (or currently using) a script that makes tens or hundreds of calls, the Perl API provides a significant performance improvement over ectool.

The Perl API is delivered as a collection of Perl packages pre-installed in a Perl 5.8 distribution. The main API package is called ElectricCommander.

For details about the API commands to install or upgrade remote agents, refer to Install remote agents using the API. The section describes how to use the CloudBees CD/RO Centralized Agent Management (CAM) feature, which significantly simplifies distribution of new agents and reduces the administrative cost of upgrading CloudBees CD/RO to newer versions.

Perl API structure

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

Specify global options

To use the CloudBees CD/RO Perl API, you must first create an object. Global arguments are specified at the time the object is created. These arguments are passed as members of an anonymous hash reference, as shown in the following example:

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

In the example above, port options are not really necessary because they specify default values. When you want to specify the server name only, you can use the shorthand form:

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

An even simpler form can be used if you call the Perl API from a script running as part of a CloudBees CD/RO job step. In this case, the CloudBees CD/RO package sets the server name based on the environment variable, COMMANDER_SERVER, set by the CloudBees CD/RO agent.

use ElectricCommander; $cmdr = ElectricCommander->new();

To see a complete list of global commands you can use with Perl, click here.

If your script uses international characters (non-ASCII), add the following block to the top of your cb-perl command block:

use utf8; ElectricCommander::initEncodings();

Specify subcommands

For each subcommand, there is a corresponding CloudBees CD/RO object function.

For example, to retrieve a list of jobs, use

$cmdr->getJobs();

Specify arguments

Most subcommands expect one or more arguments. Arguments are specified as key value pairs in a hash ref passed as the final argument to the subcommand. Additionally, as a convenience, some arguments may be specified as positional arguments prior to the options hash ref.

For example, setProperty has two positional arguments, propertyName and value, and an optional jobId argument that can be specified in either of the following forms:

$cmdr->setProperty("/projects/test/buildNumber", "22", {jobId => $jobId} );

or

$cmdr->setProperty({ propertyName => "/projects/test/buildNumber", value => "22", jobId => $jobId });

Some API commands include arguments that expect a list of values in one of two list forms: value lists and name/value pairs.

  • value list: the argument value is a reference to an array of values.

    Example:

    $cmdr->addUsersToGroup({ groupName => group1,userName => ['user1', 'user2']});
  • name/value pairs: the argument value is a reference to an array of hash references. Each hash contains a pair of entries, one for the name and one for the value. The hash keys depend on the specific API.

    Example:

    $cmdr->runProcedure({ projectName => 'proj1', procedureName => 'proc1', actualParameter => [ { actualParameterName => 'parm1', value => 'value1'}, { actualParameterName => 'parm2', value => 'value2'} ] });

Handle return values

Every function for the requested object returns an object of type XML::XPath. This is an object that returns a parsed representation of the CloudBees CD/RO returned XML block. See documentation on CPAN for more information.

$xPath = $cmdr->setProperty("/projects/test/filename", "temp.xml"); print "Return data from Commander:\n". $xPath->findnodes_as_string ("/") . "\n";

Error handling

If a function call to the CloudBees CD/RO object encounters an error, by default, it dies inside Perl and prints an error message. If you want to handle errors yourself and continue processing, you must set a flag to disable internal error handling and handle the error in your code. For example:

$cmdr->abortOnError(0); $xPath = $cmdr->getResource("NonExistent Resource"); if ($xPath) { my $code = $xPath->findvalue('//code')->value(); if ($code ne "") { my $mesg = $xPath->findvalue('//message'); print "Returned code is '$code'\n$mesg\n"; exit 1; } }

An alternative to using the abortOnError flag:

eval {$cmdr->getResource("NonExistent Resource")}; if ($@) { print "bad stuff: $@"; exit 1; }

Specify a named object

Any API argument that refers to a named object (for example, projectName or procedureName) performs property reference expansion before looking in the database for the object. This process allows constructs like the following to work without making two separate server requests:

$cmdr->getProject ('$[/server/defaultProject]');

Property reference expansion for names occurs in the global context, so context-relative shortcuts like "myProject" are not available.

Command line arguments

For help using cb-perl, run cb-perl -h. This provides a reference to forming cb-perl commands, a list of all available arguments, and a description for using each.

For help with Perl, run perldoc perl .

Batch API operation mode

The Perl API supports a batch operation mode that allows you to send multiple API requests in a single envelope, which has several advantages over standard, individual API calls in some situations. For example, you could use the batch API when you need to set multiple property values.

Use the batch API

To use the batch API, first create an instance of ElectricCommander as you would for a standard API. From your newly created instance, create a batch object using the newBatch method.

Example—creating a batch object:

use ElectricCommander; my $ec = new ElectricCommander(); # Create the batch API object my $batch = $ec->newBatch();

The batch object supports all the same calls as the standard API. The result of each call is a numeric requestId that can be used to locate a response from an individual request within the batch.

Example—creating multiple requests in a batch:

# Create multiple requests my @reqIds = ( $batch->setProperty("/myJob/p1", 99), $batch->incrementProperty("/myJob/p2") );

After the batch is created, submit it to the server for processing. The return from the submit() call is an XPath object that represents an XML document containing the responses for all the API requests.

Example—submitting the batch:

# Submit all the requests in a single envelope $batch->submit();

Sample response from this example:

<responses xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:version="2.1" dispatchId="1680"> <response requestId="1"> <property> <propertyId>199827</propertyId> <propertyName>p1</propertyName> <createTime>2010-07-21T16:41:20.003Z</createTime> <expandable>1</expandable> <lastModifiedBy>project: EA Articles</lastModifiedBy> <modifyTime>2010-07-21T16:41:20.003Z</modifyTime> <owner>project: EA Articles</owner> <value>99</value> </property> </response> <response requestId="2"> <property> <propertyId>199828</propertyId> <propertyName>p2</propertyName> <createTime>2010-07-21T16:41:20.019Z</createTime> <expandable>1</expandable> <lastModifiedBy>project: EA Articles</lastModifiedBy> <modifyTime>2010-07-21T16:41:20.019Z</modifyTime> <owner>project: EA Articles</owner> <value>1</value> </property> </response> </responses>

To extract information from the response to a request, use standard XPath syntax, and enter the requestId returned by that specific API call to either find or findvalue functions on the batch object.

Example: Extract response information:

# Extract the value from the "increment" request my $value = $batch->findvalue($reqIds[0], 'property/value'); print "New value is $value\n";

By default, the server processes each request in the envelope serially, each in its own transaction. But as an optimization, if all the requests in the envelope are read-only requests, such as getProperty API requests, then the server handles the requests in parallel, each request in its own transaction. The newBatch method has an optional argument to request the processor mode that can be used to tell the server how to process multiple requests, overriding the server’s default behavior. There are three request processor modes:

  • serial: each request in the envelope is processed serially, each in its own transaction. This is the default mode when one or more requests in the envelope are update requests or requests that can affect a change in the system.

  • parallel: each request in the envelope is processed in parallel, each in its own transaction. This is the default mode when all the requests in the envelope are read-only requests.

  • single: each request in the envelope is processed serially, all in the same transaction. The difference between single and serial mode is that in a single mode, since all requests are processed in the same transaction, then in case of an error, all the requests will be rolled back by default. Another key difference is that all locks acquired by the requests are held for the duration of the transaction while all the requests are being processed. This can increase contention in the system, including the database when other requests that are not part of the batch need access to the same objects locked by the batch API. So use the single mode only when needed and the likelihood of contention is not high.

Single-transaction batch processing can continue after errors if you enter an ignoreErrors attribute in the request,requests, or both elements. The ignoreErrors value is evaluated as a regular expression against any error codes from the batch. If the expression matches, an error does not cause the batch to fail.

There are two ways to specify ignoreErrors when issuing a single-transaction batch call:

  • Specify the ignoreErrors attribute when creating the batch object. In this case, the attribute applies to all requests in the batch:

    my $batch = $N->newBatch('single', 'DuplicateResourceName');
  • Specify the ignoreErrors attribute as an argument to an individual request. In this case, the attribute applies only to that request and will override any global value specified:

    my $req2 = $batch->createResource($resource, {ignoreErrors => 'DuplicateResourceName'});

Use your existing Perl distribution

You may want to use your existing Perl distribution. If so, CloudBees CD/RO uses a CPAN style module, located in <installdir>/src, that can be installed with the following commands:

tar xzvf ElectricCommander-<your version>.tar.gz cd ElectricCommander-<your version> perl Makefile.PL make install #Use nmake on Windows

These commands install the CloudBees CD/RO Perl and all of its submodules. If some prerequisite modules are missing, the Makefile.PL script will indicate which modules are needed.

Expand the CloudBees CD/RO Perl distribution

You may want to expand the CloudBees CD/RO Perl distribution by adding Perl modules from CPAN or third party vendors.

Install Perl modules using the CPAN installer. The installer comes with the CloudBees CD/RO Perl distribution in <installdir>/perl/bin.

During a CloudBees CD/RO upgrade, the installer makes every attempt to preserve Perl packages. However, future CloudBees CD/RO versions may contain an upgraded Perl version, which may then require a reinstalling any added Perl packages.

Linux

From the command line, use: <installdir>/perl/bin/perl -MCPAN -e 'install <module>'

Windows

Compatibility with CloudBees CD/RO is important. CloudBees CD/RO v2023.12.0 and later use Perl v5.32.1 for both cb-perl and the legacy ec-perl.

In CloudBees CD/RO v2023.10.0 and earlier, ec-perl used Perl v5.8.

If the Perl package is not Perl-only and requires compiling (for example, for C code):

  • Use Windows Visual Studio 2015 (the same version used by CloudBees CD/RO).

  • Make sure that cl and nmake are both in your path. The Visual Studio installation has a command prompt with these executables already in the path.

Extra steps are needed for Windows because of a problem with Perl and CPAN if you are running from a directory with spaces in the name. (By default, CloudBees CD/RO has spaces in the installed directory.)

  • Use a network drive to eliminate references to spaces.

    1. Use subst to mount the Perl directory under a different drive letter: c:\> subst x: "c:\program files\CloudBees\Software Delivery Automation"

    2. Start CPAN from the new location: c:\> x:\perl\bin\perl -MCPAN -e shell

    3. Configure CPAN to install into the new location: cpan> o conf makepl_arg PREFIX=x:/perl

    4. Install the module: cpan> install <module> Ending CPAN: ` cpan> quit`

  • Change the <CloudBees CD/RO _Dir>\perl\lib\config.pm file to eliminate spaces in references to the CloudBees CD/RO path. For example:

#archlibexp => 'C:\Program Files\\CloudBees\Software Delivery Automation\perl\lib', archlibexp => 'X:\perl\lib', #privlibexp => 'C:\Program Files\\CloudBees\Software Delivery Automation\perl\lib', privlibexp => 'X:\perl\lib', #scriptdir => 'C:\Program Files\\CloudBees\Software Delivery Automation\perl\lib', scriptdir => 'X:\perl\lib', #sitearchexp => 'C:\Program Files\\CloudBees\Software Delivery Automation\perl\site\lib', sitearchexp => 'X:\perl\lib', #sitelibexp => 'C:\Program Files\\CloudBees\Software Delivery Automation\perl\site\lib', sitelibexp => 'X:\perl\lib',
  • Temporarily add X:\perl\bin to your Windows path.

Use Perl API commands in Javascript

You can use CloudBees CD/RO Perl API commands in Javascript. In previous releases, Javascript was read-only, and only getProperty and setProperty were called in Javascript.

These are examples for how to use Perl API commands in Javascript:

  • To create a project:

    ectool evalScript --value "(api.createProject( { 'projectName':'alex34' } )).project.projectName ; "
  • To return the object type, use this Javascript script:

    ectool evalScript --value "api.getResources({})" [object Object]
  • For a parsed object, use the "JSON.stringify()" call:

    ectool evalScript --value "JSON.stringify(api.getResources({}));"
  • To retrieve the first resourceName:

    ectool evalScript --value "api.getResources({}).resource[0].resourceName"

Use cb-perl to allow the web server to proxy incoming application server requests

You can configure and execute a cb-perl script to allow the Apache web server to proxy incoming access to the CloudBees CD/RO application server. These requests occur even when server ports (8000/8443) are not available externally.

Outgoing or incoming requests to other CloudBees CD/RO components are not supported.
  1. Create a script (script.pl) to modify the server and securePort arguments to specify the Apache web server address.

    use ElectricCommander; my $ec = new ElectricCommander({server => "localhost", securePort => "443"}); $ec->login('admin','changeme'); print $ec->getVersions()->findvalue('//version');
  2. Execute the script.

    $ cb-perl script.pl 10.6.0.154698 $