Groovy API overview

2 minute readReference

The CloudBees Flow Groovy API is a client-side groovy library for the CloudBees Flow REST APIs.

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

The default location for ec-groovy on Unix is /opt/electriccloud/electriccommander/bin/ec-groovy.

The default location for ec-groovy on Windows is C:\Program Files\Electric Cloud\ElectricCommander\bin\ec-groovy.`

CloudBees Flow automatically adds ec-groovy to your path. To run ec-groovy from a command-line:

  1. Set COMMANDER_HOME and COMMANDER_DATA as environment variables.

  2. Enter ec-groovy <yourGroovyOptions> <GroovyScriptName>.groovy on the command line.

To run ec-groovy within a CloudBees Flow job step enter the groovy script directly into the Command field, and set the Shell field to ec-groovy. The COMMANDER_HOME and COMMANDER_DATA environment variables are automatically set when running within a CloudBees Flow job context.

ec-groovy command line options

ec-groovy supports all command-line options supported by 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

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 Flow job context, you do not need to log in because ec-groovy uses the login session (and credentials) for that job. If running ec-groovy outside of a job, ec-groovy will attempt to login using the following defaults.

  1. CloudBees Flow server (COMMANDER_SERVER): localhost

  2. CloudBees Flow server protocol (based on COMMANDER_SECURE): https

  3. CloudBees Flow server secure port (COMMANDER_HTTPS_PORT): 8443

  4. CloudBees Flow user name (COMMANDER_USER): admin

  5. CloudBees Flow 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 Flow server at https://anotherTestServer:8443.

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

Comparing with Perl API

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

  1. Both the CloudBees Flow Groovy APIs and the CloudBees Flow Perl APIs are client-side APIs.

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

  3. The CloudBees Flow client-side Groovy library supports models for complex API arguments such as actualParameters, filters, etc. See example argument models.