Using the Groovy API

ReferenceDeveloper productivity

The CloudBees CD/RO Groovy API is a client-side Apache Groovy library for the CloudBees CD/RO REST APIs. When CloudBees CD/RO is installed—Server, Agent, or Tools (using the express or advanced installation type)—the client-side Groovy library for the CloudBees CD/RO REST APIs is installed along with ec-groovy, which is a small wrapper program that can be used to run Groovy scripts.

Running ec-groovy

The default location for ec-groovy on Linux is:

/opt/cloudbees/sda/bin/ec-groovy

The default location for ec-groovy on Windows is:

C:\Program Files\CloudBees\Software Delivery Automation\bin\ec-groovy

On Windows hosts, the CloudBees CD/RO installation process automatically adds ec-groovy to your path. On Linux hosts, you need to add $INSTAL_DIE/bin to the path manually:

export PATH=$PATH:/opt/cloudbees/sda/bin

ec-groovy command line options

ec-groovy supports all command-line options supported by the groovy CLI with the exception of -n option. For example, the -cp option can be used with ec-groovy to specify the location for class files referenced by the groovy script as:

ec-groovy -cp <PathToJarFile> <GroovyScriptName>.groovy
In multizone CloudBees CD/RO deployments, CloudBees CD/RO agents that are in a different zone than the CloudBees CD/RO server must be running version 9.2 or later for the ec-groovy job step to run successfully on those agents. If you have any other zones in between that lead back to the server, you must also upgrade their gateway agents to version 9.2 or later.

For details about multiple zones and gateway agents, see Zones and Gateways.

ec-groovy restrictions

To ensure that the getProperties ec-groovy API command is invoked instead of the Groovy getProperties method, you must invoke the command in the following form if you do not specify any arguments:

def result = ef.getProperties([:])

Signing in

When running ec-groovy within a CloudBees CD/RO job context, you do not need to sign in because ec-groovy uses the CloudBees CD/RO server login session and credentials for that job. If running ec-groovy outside of a job, ec-groovy attempts to sign in using the following defaults.

  • CloudBees CD/RO server (COMMANDER_SERVER): localhost

  • CloudBees CD/RO server protocol (based on COMMANDER_SECURE): https

  • CloudBees CD/RO server secure port (COMMANDER_HTTPS_PORT): 8443

  • CloudBees CD/RO user name (COMMANDER_USER): admin

  • CloudBees CD/RO user password (COMMANDER_PASSWORD): changeme

To sign in to a specific version, you can set the appropriate environment variables to override the defaults or use the login API. Login example for logging in to testServer at https://testServer:8443, with user name testUser and password pwd using the login API:

import com.electriccloud.client.groovy.ElectricFlow

ElectricFlow ef = new ElectricFlow()
ef.login('testServer', 'testUser', 'pwd')

Another login example for logging in to testServer at https://testServer:8000 with user name testUser and password pwd using the login API and environment variables:

import com.electriccloud.client.groovy.ElectricFlow

ElectricFlow ef = new ElectricFlow()
ef.login('testUser', 'pwd')

Then use the following ec-groovy command to connect to the CloudBees CD/RO server at https://anotherTestServer:8443.

ec-groovy -DCOMMANDER_SERVER=anotherTestServer -DCOMMANDER_SECURE=1 <_GroovyScriptName_>.groovy

Comparing with Perl API

CloudBees CD/RO provides Perl APIs that can be invoked through ec-perl. The following lists the differences and similarities between the Groovy API and the Perl API.

  • Both the CloudBees CD/RO Groovy APIs and the CloudBees CD/RO Perl APIs are client-side APIs.

  • The CloudBees CD/RO Groovy API is a client-side groovy library for the CloudBees CD/RO REST APIs. The CloudBees CD/RO Perl API supports these additional APIs which not supported through REST and Groovy: publishArtifact, retrieveArtifact, and sendEmail.

  • The CloudBees CD/RO client-side Groovy library supports models for complex API arguments such as actualParameters, filters, etc. See example argument models.