Using the Perl API
IntroductionAccess tokensACL managementApplication dependencyApplicationsApplication tier Artifact managementCatalogsChange historyCI build detailCI configurationCI jobsComponentsCredential managementCustom filtersDatabase configurationData retentionCloudBees AnalyticsDirectory provider managementDynamic environmentsEmail configuration managementEmail notifier managementEnvironmentEnvironment tierGateway and zone managementInstalling or upgrading remote agentsJob managementMicroservicesObject tagsParameter managementPersonasPipelines and releasesPlugin managementPlugin configuration managementProcedure managementProcessProcess dependencyProcess stepProject managementProperty managementResource managementRolling deploySchedule managementService accounts for webhooksServer managementSingle sign on for SAMLSnapshotsTier mapTrigger managementUser and group managementUser profile email managementWait dependenciesWorkflow definition managementWorkflow managementWork itemsWorkspace managementMiscellaneous management
Perl API response and element glossary
IntroductionExamplesTroubleshooting
IntroductionaccesstokenaclaclentryactualparameteractualparametersapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitiontagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

Using the Groovy API

3 minute readReferenceDeveloper 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.

Examples