Roadmap to CloudBees CD APIs
IntroductionUsing the Groovy APIUsing JRubyCloudBees CD API error messages
Using DSL
IntroductionGetting started with DSLGenerating DSL scriptsDSL automation as codeDSL editorsTroubleshooting and FAQs
DSL method reference
Using the RESTful API
Using the Perl API
Perl API response and element glossary
Perl API reference
IntroductionACL managementApplication dependencyApplicationsApplication tierArtifact managementCatalogsChange historyCI Build detailCI configurationCI JobsComponentsCredential managementCustom filtersDatabase configurationData retentionDevOps insightDirectory Provider managementDynamic environmentsemail configuration managementEmail Notifier managementEnvironmentEnvironment tierGateway and Zone managementInstalling or upgrading remote agentsJob managementMicroservicesObject tagsParameter managementPersonasPipelines and releasesPlugin managementProcedure managementProcessProcess dependencyProcess stepProject managementProperty managementResource managementRolling deploySchedule managementServer managementSingle sign-onSnapshotsTier mapUser and Group managementWait dependenciesWebhhook managementWorkflow definition managementWorkflow managementWork itemsWorkspace managementMiscellaneous management
Using the Groovy API
IntroductionExamples
Groovy API reference
Introductionaclaclentryactualparameteractualparametersapplicationapplicationdependencyapplicationservicemappingapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuilddetailciconfigurationclustercomponentcontainercredentialdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeployerservicedeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmentmapenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvironmentvariableenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensenoteobjectoutputparameterpersonapersonacategorypersonapagepipelinepluginportprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulesearchfilterserverserviceaccountserviceserviceclustermappingservicedependencyservicemapdetailsessionsnapshotstagestatestatedefinitiontagtasktiermaptiermappingtransitiontransitiondefinitionuserutilityresourcewaitdependencywidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezone

Microservices

8 minute readReference

createService

Creates a new microservice for a project or application.

You must specify the projectName and serviceName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

serviceName

Name of the microservice. This name must be unique among all projects.

Argument Type: String

addDeployProcess

If set to true, then a service process is also created.

Argument type: Boolean

applicationName

The name of an application to scope this service to.

Argument type: String

defaultCapacity

The default service capacity.

Argument type: String

description

(Optional) Comment text describing this object that is not interpreted at all by CloudBees CD .

Argument Type: String

maxCapacity

The max service capacity.

Argument type: String

minCapacity

The min service capacity.

Argument type: String

volume

Volume JSON of the service.

Argument type: String

Positional arguments

projectName, serviceName

Response

Returns a microservice element.

ec-perl

syntax: $<object>->createService(<projectName>, <serviceName>, {<optionals>});

Example

$ec->createService("Default", "Deploy", {description => "QA testing"});

ectool

syntax: ectool createService <projectName> <serviceName> [optionals]

Example

ectool createService "Default" "Deploy" --description "QA testing"

Back to top

createServiceClusterMapping

Creates a new mapping between an application or project microservice and an environment cluster.

You must specify the projectName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

actualParameters

(Optional) Actual parameters specific to plugin procedure associated with the application service.

Argument type: Map

applicationEntityRevisionId

(Optional) Revision ID of the versioned object.

Argument type: UUID

applicationName

(Optional) The name of the application which contains the service.

Argument type: String

applicationServiceMappingName

(Optional) The name of the application service mapping.

Argument type: String

clusterName

(Optional) The name of the environment cluster.

Argument type: String

clusterProjectName

(Optional) The name of the project which contains the cluster.

Argument type: String

defaultCapacity

(Optional) The default service capacity.

Argument type: String

environmentMapName

(Optional) The name of the environment map. If not provided, will use service name and environment name to resolve environmentMap.

Argument type: String

environmentName

(Optional) The name of the environment which contains the cluster.

Argument type: String

environmentProjectName

(Optional) The name of the environment which contains the cluster.

Argument type: String

maxCapacity

(Optional) The max service capacity.

Argument type: String

minCapacity

(Optional) The min service capacity.

Argument type: String

serviceClusterMappingName

(Optional) The name of the service cluster mapping.

Argument type: String

serviceEntityRevisionId

(Optional) Revision ID of the versioned object.

Argument type: UUID

serviceName

(Optional) The name of the independent microservice.

Argument type: String

tierMapName

(Optional) The name of the tier map. If not provided, will use application name and environment name to resolve tierMap.

Argument type: String

volume

(Optional) Volume JSON of the service.

Argument type: String

Positional arguments

projectName

Response

Returns the flowRuntimeId object.

ec-perl

syntax: $<object>->createServiceClusterMapping(<projectName>, {<optionals>});

Example

$ec->createServiceClusterMapping("service_proj1", {environmentName => "qe env name", serviceName => "qe service 1", clusterName => "qe cluster", environmentMapName => "map", environmentProjectName => "env_proj"});

ectool

syntax: ectool createServiceClusterMapping <projectName> [optionals]

Example

ectool createServiceClusterMapping "service_proj1" --environmentName "qe env" --serviceName "qe service 1" --clusterName "qe cluster" --environmentMapName "map"  --environmentProjectName "env_proj"

Back to top

createServiceDependency

Adds a microservice dependency to the specified microservice.

You must specify the projectName and serviceName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

serviceName

Name of the microservice. This name must be unique among all projects.

Argument Type: String

dependentApplicationName

(Optional) The name of application which this application depends on.

Argument Type: String

dependentProjectName

(Optional) The name the project containing the dependent application.

Argument Type: String

dependentServiceName

(Optional) The name of service which this application depends on.

Argument Type: String

dependentSnapshotName

(Optional) The name of snapshot of the dependent application.

Argument Type: String

effectiveDate

(Optional) The date when this dependency is applicable (for example, 2006-05-15).

Argument Type: String

serviceDependencyName

(Optional) The name of the service dependency. If not specified, a system generated GUID is used.

Argument Type: String

snapshotName

(Optional) Name of the snapshot; must be unique within the application.

Argument Type: String

Positional arguments

projectName, serviceName

Response

Returns a microservice dependency for the specified microservice.

ec-perl

syntax: $<object>->createServiceDependency(<projectName>, <serviceName>, {<optionals>});

Example

$ec->createServiceDependency("service_proj1", "qe service name 1" {dependentServiceName => "qe service 3", serviceDependencyName => "dependency 1"});

ectool

syntax: ectool createServiceDependency <projectName> <serviceName> [optionals]

Example

ectool createServiceDependency "service_proj1" "qe service name 1" --dependentServiceName "qe service 3" --serviceDependencyName "dependency 1"

Back to top

deleteService

Deletes a microservice.

You must specify the projectName and serviceName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

serviceName

Name of the microservice. This name must be unique among all projects.

Argument Type: String

applicationName

Name of the application to which the application level service belongs to, null for a project-level service.

Argument Type: String

Positional arguments

projectName, serviceName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteService (<projectName>, <serviceName>);

Example

$ec->deleteService ("Default", "Undeploy");

ectool

syntax: ectool deleteService <projectName> <serviceName>

Example

ectool deleteService "Default" "Undeploy"

Back to top

deleteServiceClusterMapping

Deletes a microservice cluster mapping.

You must specify the projectName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

applicationEntityRevisionId

(Optional) Revision ID of the versioned object.

Argument Type: UUID

applicationName

(Optional) The name of the application which contains the service.

Argument Type: String

applicationServiceMappingName

(Optional) The name of the application service mapping.

Argument Type: String

clusterName

(Optional) The name of the environment cluster.

Argument Type: String

clusterProjectName

(Optional) The name of the project which contains the cluster.

Argument Type: String

environmentMapName

(Optional) The name of the environment map. If not provided, will use service name and environment name to resolve environmentMap.

Argument Type: String

environmentName

(Optional) The name of the environment which contains the cluster.

Argument Type: String

environmentProjectName

(Optional) The name of the environment which contains the cluster.

Argument Type: String

serviceClusterMappingName

(Optional) The name of the service cluster mapping.

Argument Type: String

serviceEntityRevisionId

(Optional) Revision ID of the versioned object.

Argument Type: UUID

serviceName

(Optional) The name of the independent service.

Argument Type: String

tierMapName

(Optional) The name of the tier map. If not provided, will use application name and environment name to resolve tierMap.

Argument Type: String

Positional arguments

projectName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteServiceClusterMapping(<projectName>, {<optionals>});

Example

$ec->deleteServiceClusterMapping("qe proj service" {environmentName => "qe env", serviceName => "qe service1", clusterName => "qe cluster1", environmentProjectName => "qe proj env"});

ectool

syntax: ectool deleteServiceClusterMapping <projectName> [optionals]

Example

ectool deleteServiceClusterMapping "qe proj service" --environmentName "qe env" --serviceName "qe service1" --clusterName "qe cluster1" --environmentProjectName "qe proj env"

Back to top

deleteServiceDependency

Deletes a microservice dependency.

You must specify the projectName and serviceName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

serviceName

Name of the microservice. This name must be unique among all projects.

Argument Type: String

dependentApplicationName

(Optional) The name of application which this application depends on.

Argument Type: String

dependentProjectName

(Optional) The name the project containing the dependent application.

Argument Type: String

dependentServiceName

(Optional) The name of the service which this application depends on.

Argument Type: String

dependentSnapshotName

(Optional) The name of snapshot of the dependent application.

Argument Type: String

serviceDependencyName

(Optional) The name of service dependency. If not specified, a system generated GUID is used.

Argument Type: String

snapshotName

(Optional) Name of the snapshot; must be unique within the application.

Argument Type: String

Positional arguments

projectName, serviceName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteServiceDependency(<projectName>, <serviceName>, {<optionals>});

Example

$ec->deleteServiceDependency("service_proj1", "qe service name 1" {dependentServiceName => "qe service 3", serviceDependencyName => "dependency 1"});

ectool

syntax: ectool deleteServiceDependency <projectName> <serviceName> [optionals]

Example

ectool deleteServiceDependency "service_proj1" "qe service name 1" --dependentServiceName "qe service 3" --serviceDependencyName "dependency 1"

Back to top

deleteServiceMapDetail

Deletes a microservice detail map for the given container.

You must specify the projectName and containerName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

containerName

The name of the container.

Argument Type: String

applicationEntityRevisionId

(Optional) Revision ID of the versioned object.

Argument Type: UUID

applicationName

(Optional) The name of the application which contains the service.

Argument Type: String

applicationServiceMappingName

(Optional) The name of the application service mapping.

Argument Type: String

environmentMapName

(Optional) The name of the environment map. If not provided, will use service name and environment name to resolve environmentMap.

Argument Type: String

environmentName

(Optional) The name of the environment which contains the cluster.

Argument Type: String

environmentProjectName

(Optional) The name of the environment which contains the cluster.

Argument Type: String

serviceClusterMappingName

(Optional) The name of the application service mapping.

Argument Type: String

serviceEntityRevisionId

(Optional) Revision ID of the versioned object.

Argument Type: UUID

serviceMapDetailName

(Optional) The name of the service map detail.

Argument Type: String

serviceName

(Optional) The name of the independent service.

Argument Type: String

tierMapName

(Optional) The name of the tier map. If not provided, the application name and environment name is used to resolve tierMap.

Argument Type: String

Positional arguments

projectName, containerName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteServiceMapDetail(<projectName>, <containerName>, {<optionals>});

Example

$ec->deleteServiceMapDetail("service_proj1", "qe container name 1" {serviceMapDetailName => "service map detail 3"});

ectool

syntax: ectool deleteServiceMapDetail <projectName> <containerName> [optionals]

Example

ectool deleteServiceMapDetail "service_proj1" "qe container name 1" --serviceMapDetailName "service map detail 3"

Back to top

getService

Retrieves a microservice by name.

You must specify the projectName and serviceName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

serviceName

Name of the microservice. This name must be unique among all projects.

Argument Type: String

applicationEntityRevisionId

Revision ID of the versioned object.

Argument type: UUID

applicationName

The name of an application that this service is scoped to.

Argument type: String

includeDetails

True to include details (default is false ).

Argument type: Boolean

serviceEntityRevisionId

(Optional) The revision ID of the versioned object.

Argument type: UUID

Positional arguments

projectName, serviceName

Response

Retrieves the specified microservice element.

ec-perl

syntax: $<object>->getService(<projectName>, <serviceName>, {<optionals>});

Example

$ec->getService("Default", "Deploy", {serviceEntityRevisionId => "4fa765dd-73f1-11e3-b67e-b0a420524153"});

ectool

syntax: ectool getService <projectName> <serviceName> [optionals]

Example

ectool getService "Default" "Deploy" --serviceEntityRevisionId 4fa765dd-73f1-11e3-b67e-b0a420524153

Back to top

getServices

Retrieves all microservices in a project or application.

You must specify the projectName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

applicationEntityRevisionId

Revision ID of the versioned object.

Argument Type: UUID

applicationName

The name of an application that this service is scoped to.

Argument Type: String

includeDetails

True to include details (default is false ).

Argument type: Boolean

includeEntityRevisions

(Optional) < Boolean flag— 0|1|true|false >

If set to 1 or true, the search results include the revisions of microservice.

Argument type: Boolean

Positional arguments

projectName

Response

Retrieves zero or more microservice elements.

ec-perl

syntax: $<object>->getServices(<projectName>, {<optionals>});

Example

$ec->getServices("Default", {referenceProject => "Financial Summaries"});

ectool

syntax: ectool getServices <projectName> [optionals]

Example

ectool getServices "Default" --referenceProject "Financial Summaries"

Back to top

modifyService

Modifies an existing microservice.

You must specify the projectName and the serviceName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

serviceName

Name of the microservice. This name must be unique among all projects.

Argument Type: String

applicationName

The name of an application to scope this service to.

Argument type: String

defaultCapacity

The default service capacity.

Argument type: String

description

(Optional) Comment text describing this object that is not interpreted at all by CloudBees CD .

Argument Type: String

maxCapacity

The max service capacity.

Argument type: String

minCapacity

The min service capacity.

Argument type: String

newName

(Optional) New name for an existing object that is being renamed.

Argument Type: String

volume

Volume JSON of the service.

Argument type: String

Positional arguments

projectName, serviceName

Response

Returns a modified microservice element.

ec-perl

syntax: $<object>->modifyService(<projectName>, <serviceName>, {<optionals>});

Example

$ec->modifyService("Default", "Deploy config", {newName=> "Deploy new service", description => "Pet store website"});

ectool

syntax: ectool modifyService <projectName> <serviceName> [optionals]

Example

ectool modifyService "Default" "Deploy config" --newName "Deploy new service" --description "Pet Store website"

Back to top

runServiceProcess

Runs a service process.

You must specify the projectName, serviceName, and processName.

Arguments Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument Type: String

serviceName

Name of the microservice. This name must be unique among all projects.

Argument Type: String

processName

The name of the application process.

Argument Type: String

actualParameters

(Optional) Parameters passed as arguments to the process.

Argument Type: Map

credentials

(Optional) Credentials to be used in the job.

Argument Type: Collection

destinationProject

(Optional) The project that will own the job.

Argument Type: String

enforceDependencies

(Optional) If application dependencies are defined for the specified application, enforce them for successful deployment.

Argument Type: Boolean

environmentMapName

(Optional) The name of the Service Environment map used to determine where to run the process.

Argument Type: String

environmentName

(Optional) Environment name to create from template.

Argument Type: String

environmentProjectName

(Optional) The name of the project to which the environment or environment template belongs to.

Argument Type: String

priority

(Optional) The priority of the job.

Argument Type: JobPriority

scheduleName

(Optional) Name for the schedule; must be unique among all schedules for the project.

Argument Type: String

snapshotName

(Optional) Name for the snapshot.

Argument Type: String

validate

(Optional) Validate the process and environment.

Argument Type: Boolean

Positional arguments

projectName, serviceName, processName

Response

Returns the new job ID.

ec-perl

syntax: $<object>->runServiceProcess(<projectName>, <serviceName>, <processName>, {<optionals>});

Example

$ec->runServiceProcess("qe proj 1", "qe service", "qe proc", {environmentName => "qe env", environmentProjectName => "qe proj 2"});

ectool

syntax: ectool runServiceProcess <projectName> <serviceName> <processName> [optionals]

Example

ectool runServiceProcess "qe proj 1" "qe service" "qe proc" --environmentName "qe env" --environmentProjectName "qe proj 2"

Back to top

Job management
Object tags