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

Environment

15 minute readReference

createEnvironment

Creates a new environment.

ArgumentDescription

projectName

The project name.

Argument Type: String

environmentName

Name of the environment that must be unique among all projects.

Argument Type: String

applicationName

(Optional) Name of the application . Supply one of applicationName or serviceName. Argument Type: String

applicationProjectName

(Optional) Name of the project to which applicationName belongs. Used with applicationName.

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted by CloudBees CD .

Argument Type: String

environmentEnabled

(Optional) True to enable rolling deploy on this environment.

Argument Type: Boolean

reservationRequired

(Optional) < Boolean flag - 0|1|true|false > Set this flag to "true" to allow deployments to run using only using environment reservations.

Argument Type: Boolean

rollingDeployEnabled

(Optional) < Boolean flag - 0|1|true|false > Set this flag to "true" or "1" to enable the environment.

Argument Type: Boolean

rollingDeployType

(Optional) The type of rolling deploy supported by the environment.

Argument Type: RollingDeployType

serviceName

(Optional) Name of the service. Supply one of applicationName or serviceName. Argument Type: String

serviceProjectName

(Optional) Name of the project to which serviceName belongs. Used with serviceName.

Argument Type: String

Positional arguments

projectName, environmentName

Response

Returns an environment object.

ec-perl

Syntax:

$<object>->createEnvironment(<projectName>, <environmentName>, {<optionals>});

Example:

$ec->createEnvironment("Default", "Web Server", {environmentEnabled => true, description => "Web Services", rollingDeployEnabled => true});

ectool

Syntax:

ectool createEnvironment <projectName> <environmentName> [optionals]

Example:

ectool createEnvironment "Default" "Web Server" --environmentEnabled true --description "Web Server" --rollingDeployEnabled true

Back to top

createEnvironmentInventoryItem

Creates a new environment inventory item.

ArgumentDescription

projectName

Name of the project.

Argument Type: String

environmentName

Name of the environment.

Argument Type: String

Required for application-scoped component objects:

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

componentName

Name of the component that owns the inventory item. Argument Type: String

resourceName

Name of the resource where the item is installed. Argument Type: String

Required for application-scoped service objects:

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

containerName

Name of the container. Argument Type: String

Required for project-scoped service objects:

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

containerName

Name of the container. Argument Type: String

Optional arguments:

applicationTierName

(Optional) Name of the application tier.

Argument Type: String

artifactName

(Optional) Artifact name for the inventory item.

Argument Type: String

artifactSource

(Optional) Source of the artifact.

Argument Type: String

artifactUrl

(Optional) URL of the artifact.

Argument Type: String

artifactVersion

(Optional) Artifact version for the inventory item.

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted by CloudBees CD .

Argument Type: String

environmentProjectName

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

Argument Type: String

status

(Optional) Deployment status of the inventory item. Possible values include: success, warning, error, skipped

Argument Type: String

Positional arguments

projectName, environmentName

Response

Retrieves an environmentInventoryItem object.

ec-perl

Syntax:

$<object>->createEnvironmentInventoryItem(<projectName>, <environmentName>, <applicationName>, <componentName>,  <resourceName>, {<optionals>});

Example:

$ec->createEnvironmentInventoryItem("Default", "Web Server", "Deploy", "WAR file", "local", {artifactName =>"com.ec:myApp", artifactVersion=>"3.1", description => "Required"});

ectool

Syntax:

ectool createEnvironmentInventoryItem <projectName> <environmentName> <applicationName> <componentName> <resourceName> [optionals]

Example:

ectool createEnvironmentInventoryItem "Default" "Web Server" "Deploy" "WAR file" "local" -- artifactName "com.ec:myApp" --artifactVersion "3.1" --description "Required"

Back to top

createEnvironmentMap

Creates a new service environment map for a service.

ArgumentDescription

projectName

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

Argument Type: String

environmentName

Name of the environment.

Argument Type: String

serviceName

(Optional) The name of the service.

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted by CloudBees CD .

Argument Type: String

environmentMapName

(Optional) The name of the tier map. If not specified the operation will assume a hyphenated service and environment name.

Argument Type: String

environmentProjectName

(Optional) The name of the environment’s project.

Argument Type: String

serviceEntityRevisionId

(Optional) Revision ID of the versioned object.

Argument Type: String

Positional arguments

projectName, environmentName

Response

Retrieves an environmentMap object.

ec-perl

Syntax:

$<object>->createEnvironmentMap(<projectName>, <environmentName>, {<optionals>});

Example:

$ec->createEnvironmentMap("Default", "Web Server Env", {description => "Required"});

ectool

Syntax:

ectool createEnvironmentMap <projectName> <environmentName> [optionals]

Example:

ectool createEnvironmentMap "Default" "Web Server Env" --description "Required"

Back to top

createReservation

Creates a new reservation.

ArgumentDescription

projectName

The name for the project that must be unique among all projects.

Argument Type: String

reservationName

The name of the environment reservation.

Argument Type: String

environmentName

The name of the environment.

Argument Type: String

beginDate

The date when the reservation begins, formatted as yyyy-mm-ddThh:mm .

endDate

The date when reservation ends, formatted as yyyy-mm-ddThh:mm .

Argument Type: String

timeZone

The time zone to use when interpreting times.

Argument Type: String

applicationName

(Optional) The name of the application.

Argument Type: String

blackout

(Optional) < Boolean flag — 0|1|true|false > When this argument is set to true or 1, no deployments are allowed to run during the specified time period.

Argument Type: Boolean

description

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

Argument Type: String

environmentProjectName

(Optional) The name of the environment project.

Argument Type: String

environmentTierName

(Optional) The name of the environment tier.

Argument Type: String

monthDays

(Optional) A list of numbers from 1 to 31 separated by spaces, indicating zero or more days of the month.

Argument Type: String

overlap

(Optional) < Boolean flag — 0|1|true|false > When this argument is set to true or 1, this reservation can overlap with another reservation. By default, reservations are not overlapped.

Argument Type: Boolean

pipelineName

(Optional) The name of the pipeline.

recurrence

(Optional) < Boolean flag — 0|1|true|false > Recurrence reservation When this argument is set to true or 1, the reservation is a recurring reservation.

Argument Type: Boolean

recurrenceEndDate

(Optional) The date when the recurring reservation ends.

Argument Type: String

releaseName

(Optional) The name of the release.

Argument Type: String

serviceName

(Optional) The name of the service.

Argument Type: String

weekDays

(Optional) Restricts the schedule to specified days of the week. Specify days of the week separated by spaces. Use English names Monday, Tuesday, etc.

Argument Type: String

Positional arguments

projectName, reservationName

Response

Retrieves an reservation object.

ec-perl

Syntax:

$<object>->createReservation(<projectName>, <reservationName>, {<optionals>});

Example:

$ec->createReservation('Default', 'Main branch', {environmentName => "Web Server", applicationName => "Heat Clinic", beginDate => "2019-04-30T00:00", endDate => "2019-05-15T00:00", timeZone => GMT});

ectool

Syntax:

ectool createReservation <projectName> <reservationName> [optionals]

Example:

ectool createReservation 'Default' 'Main branch' --environmentName "Web Server" --applicationName "Heat Clinic" --beginDate "2019-04-30T00:00" --endDate "2019-05-15T00:00" --timeZone GMT

Back to top

deleteEnvironment

Deletes an environment.

ArgumentDescription

projectName

Name of the project. This name must be unique among all projects. Argument Type: String

environmentName

Name of the environment that must be unique among all projects. Argument Type: String

Positional arguments

projectName, environmentName

Response

None or a status OK message.

ec-perl

Syntax:

$<object>->deleteEnvironment(<projectName>, <environmentName>);

Example:

$cmdr->deleteEnvironment("Default", "PROD");

ectool

Syntax:

ectool deleteEnvironment <projectName> <environmentName>

Example:

ectool deleteEnvironment "Default" "PROD"

Back to top

deleteEnvironmentInventoryItem

Deletes an inventory item.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

Required for application-scoped component objects:

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

componentName

Name of the component that owns the inventory item. Argument Type: String

resourceName

Name of the resource where the item is installed. Argument Type: String

Required for application-scoped service objects:

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

containerName

Name of the container. Argument Type: String

Required for project-scoped service objects:

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

containerName

Name of the container. Argument Type: String

Optional arguments:

environmentProjectName

(Optional) Name for the project to which the environment or environment template belongs. Argument Type: String

Positional arguments

projectName, environmentName

Response

None or a status OK message.

ec-perl

Syntax:

$<object>->deleteEnvironmentInventoryItem(<projectName>, <environmentName>, <applicationName>, <componentName>, <resourceName>, {optionals});

Example:

$cmdr->deleteEnvironmentInventoryItem("Utilities", "PROD", "Deploy", "WAR file", "Server 1", {environmentProjectName => "Default");

ectool

Syntax:

ectool deleteEnvironmentInventoryItem <projectName> <environmentName> <applicationName> <componentName> <resourceName> [optionals]

Example:

ectool deleteEnvironmentInventoryItem "Utilities" "PROD" "Deploy" "WAR file" "Server 1" --environmentProjectName "Default"

Back to top

deleteEnvironmentMap

Deletes a microservice environment map from a microservice.

ArgumentDescription

projectName

Argument Type: String include::partial$name-for-the-project.adoc[]

environmentName

Name of the environment that must be unique among all projects. Argument Type: String

environmentProjectName

(Optional) The name of the environment’s project. Argument Type: String

serviceEntityRevisionId

(Optional) Revision ID of the versioned object. Argument Type: UUID

serviceName

(Optional) The name of the service. Argument Type: String

Positional arguments

projectName, environmentName

Response

None or a status OK message.

ec-perl

Syntax:

$<object>->deleteEnvironmentMap(<projectName>, <environmentName>), {<optionals>});

Example:

$cmdr->deleteEnvironmentMap("Default", "PROD", {serviceName => "service1"});

ectool

Syntax:

ectool deleteEnvironmentMap <projectName> <environmentName> [optionals]

Example:

ectool deleteEnvironmentMap "Default" "PROD" --serviceName "service1"

Back to top

deleteReservation

Deletes the specified reservation.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

reservationName

The name of the environment reservation. Argument Type: String

Positional arguments

projectName, reservationName

Response

None or a status OK message.

ec-perl

Syntax:

$<object>->deleteReservation(<projectName>, <reservationName>);

Example:

$cmdr->deleteReservation("Default", "Main branch");

ectool

Syntax:

ectool deleteReservation <projectName> <reservationName>

Example:

ectool deleteReservation "Default" "Main branch"

Back to top

getEnvironment

Retrieves an environment by name.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment that must be unique among all projects. Argument Type: String

Positional arguments

projectName, environmentName

Response

Returns an environment object.

ec-perl

Syntax:

$<object>->getEnvironment(<projectName>, <environmentName>);

Example:

$ec->getEnvironment("Default", "Test Server");

ectool

Syntax:

ectool getEnvironment <projectName> <environmentName>

Example:

ectool getEnvironment "Default" "Test Server"

Back to top

getEnvironmentApplications

Retrieves a list of applications installed on the given environment.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

Positional arguments

projectName, environmentName

Response

Returns a list of environmentApplication objects.

ec-perl

Syntax:

$<object>->getEnvironmentApplications(<projectName>, <environmentName>);

Example:

$ec->getEnvironmentApplications("Default", "Test Server");

ectool

Syntax:

ectool getEnvironmentApplications <projectName> <environmentName>

Example:

ectool getEnvironmentApplications "Default" "Test Server"

Back to top

getEnvironmentDeployments

Gets environment deployments for the specified environment.

ArgumentDescription

projectName

Name of the project. This name must be unique among all projects. Argument Type: String

environmentName

Name of the environment that must be unique among all projects. Argument Type: String

Positional arguments

projectName, environmentName

Response

One or more environmentDeployment objects.

ec-perl

Syntax:

$<object>->getEnvironmentDeployments(<projectName>, <environmentName>);

Example:

$cmdr->getEnvironmentDeployments("Default", "PROD");

ectool

Syntax:

ectool getEnvironmentDeployments <projectName> <environmentName>

Example:

ectool getEnvironmentDeployments "Default" "PROD"

Back to top

getEnvironmentInventory

Retrieves a per-component grouped list of inventory items.

ArgumentDescription

Required for application objects without a snapshot:

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

Required for application objects with a snapshot:

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

applicationEntityRevisionId

Revision ID of the versioned object. Argument Type: UUID

Required for project-scoped service objects without a snapshot:

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

Required for project-scoped service objects with a snapshot:

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

serviceEntityRevisionId

Revision Id of the service entity. Argument Type: UUID

Optional:

environmentProjectName

(Optional) Name for the project to which the environment or environment template belongs. Argument Type: String

Positional arguments

projectName, environmentName

Response

Returns zero or more environmentInventory objects.

ec-perl

Syntax:

$<object>->getEnvironmentInventory(<projectName>, <environmentName>, <applicationName>);

Example:

$ec->getEnvironmentInventory("Default", "Test Server", "Save snapshot");

ectool

Syntax:

ectool getEnvironmentInventory <projectName> <environmentName> <applicationName>

Example:

ectool getEnvironmentInventory "Default" "Test Server" "Save snapshot"

Back to top

getEnvironmentInventoryItem

Retrieves an inventory item.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

Required for application-scoped component objects:

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

componentName

Name of the component that owns the inventory item. Argument Type: String

resourceName

Name of the resource where the item is installed. Argument Type: String

Required for application-scoped service objects:

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

containerName

Name of the container. Argument Type: String

Required for project-scoped service objects:

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

containerName

Name of the container. Argument Type: String

Optional arguments:

environmentProjectName

(Optional) Name for the project to which the environment or environment template belongs. Argument Type: String

includeResourceDetails

(Optional) < Boolean flag — 0|1|true|false > When this argument is set to true or 1, the response includes the resource details. The default is false or 0. Argument Type: Boolean

Positional arguments

projectName, environmentName

Response

Retrieves an environmentInventoryItem object.

ec-perl

Syntax:

$<object>->getEnvironmentInventoryItem(<projectName>, <environmentName>, <applicationName>, <componentName>, <resourceName>, {<optionals>});

Example:

$ec->getEnvironmentInventoryItem("Default", "Test Lab", "Save snapshot", "WAR file", "QA server", {environmentProjectName => "QA only"});

ectool

Syntax:

ectool getEnvironmentInventoryItem <projectName> <environmentName> <applicationName> <componentName> <resourceName> [optionals]

Example:

ectool getEnvironmentInventoryItem "Default" "Test Lab" "Save snapshot" "WAR file" "QA server" --environmentProjectName "QA only"

Back to top

getEnvironmentInventoryItems

Retrieves all the inventory items for a given environment.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

includeResourceDetails

(Optional) < Boolean flag — 0|1|true|false > When this argument is set to true or 1, the response includes the resource details. The default is false or 0. Argument Type: Boolean

Positional arguments

projectName, environmentName

Response

Retrieves zero or more environmentInventory objects.

ec-perl

Syntax:

$<object>->getEnvironmentInventoryItems(<projectName>, <environmentName>);

Example:

$ec->getEnvironmentInventoryItems("Default", "Test Lab");

ectool

Syntax:

ectool getEnvironmentInventoryItems <projectName> <environmentName>

Example:

ectool getEnvironmentInventoryItems "Default" "Test Lab"

Back to top

getEnvironmentMaps

Get microservice environment maps.

ArgumentDescription

projectName

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

Argument Type: String

serviceEntityRevisionId

(Optional) Revision ID of the versioned object. Argument Type: UUID

serviceName

(Optional) The name of the service. Argument Type: String

Positional arguments

projectName

Response

Retrieves zero or more environmentMap objects .

ec-perl

Syntax:

$<object>->getEnvironmentMaps(<projectName>), {<optionals>});

Example:

$cmdr->getEnvironmentMaps("Default", "PROD", {serviceName => "service1"});

ectool

Syntax:

ectool getEnvironmentMaps <projectName>  [optionals]

Example:

ectool getEnvironmentMaps "Default" "PROD" --serviceName "service1"

Back to top

getEnvironments

Retrieves all environments in a project.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

Positional arguments

projectName

Response

Returns zero or more environment objects.

ec-perl

Syntax:

$<object>->getEnvironments(<projectName>);

Example:

$ec->getEnvironments("Default");

ectool

Syntax:

ectool getEnvironments <projectName>

Example:

ectool getEnvironments "Default"

Back to top

getReservation

Retrieves an environment reservation by its name.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

reservationName

The name of the environment reservation. Argument Type: String

beginDate

(Optional) The date when the reservation begins. Argument Type: String

endDate

(Optional) The date when the reservation ends. Argument Type: String

includeTimeslots

(Optional) < Boolean flag — 0|1|true|false > When this argument is set to true or 1, time slots are included in the reservation response. Argument Type: Boolean

timeZone

(Optional) The time zone to use when interpreting times. Argument Type: String

Positional arguments

projectName,reservationName

Response

Retrieve a reservation object.

ec-perl

Syntax:

$<object>->getReservation(<projectName>, <reservationName>, {<optionals>});

Example:

$ec->getReservation("Default", "Main branch", {includeTimeslots => true, timeZone => "local"} );

ectool

Syntax:

ectool getReservation <projectName> <reservationName> [optionals]

Example:

ectool getReservation "Default" "Main branch" --includeTimeslots true --timeZone "local"

Back to top

getReservations

Retrieves all the environment reservations.

ArgumentDescription

applicationName

(Optional) The name of the application. Argument Type: String

beginDate

(Optional) The date when the reservation begins. Argument Type: String

blackout

(Optional) < Boolean flag — 0|1|true|false > When this argument is set to true or 1, no deployments are allowed to run during the specified time period Argument Type: Boolean

endDate

(Optional) The date when the reservation ends. Argument Type: String

environmentName

(Optional) The name of the environment. Argument Type: String

environmentProjectName

(Optional) The name of the environment project. Argument Type: String

environmentTierName

(Optional) The name of the environment tier. Argument Type: String

includeTimeslots

(Optional) < Boolean flag — 0|1|true|false > When this argument is set to true or 1, time slots are included in the response. Argument Type: Boolean

pipelineName

(Optional) The name of the pipeline. Argument Type: String

projectName

(Optional) The name for the project that must be unique among all projects. Argument Type: String

releaseName

(Optional) The name of the release. Argument Type: String

reserverTypes

(Optional) The types of the objects reserving the environments (the Reserver). Argument Type: Collection

timeZone

(Optional) The time zone to use when interpreting times. Argument Type: String

Positional arguments

projectName,reservationName

Response

Retrieves zero or more reservation objects.

ec-perl

Syntax:

$<object>->getReservations({<optionals>});

Example:

$ec->getReservations({environmentName => "PROD", pipelineName => "RC build", includeTimeslots => true, timeZone => "local"});

ectool

Syntax:

ectool getReservations [optionals]

Example:

ectool getReservations --environmentName "PROD" --pipelineName => "RC build" --includeTimeslots true --timeZone "local"

Back to top

getRunSchedules

Retrieves the run schedules with environment reservations.

ArgumentDescription

beginDate

endDate

(Optional) The beginning and ending dateof the reservation. The format is yyyy-mm-dd . Must be specified if includeTimeslots is false. Argument Type: String

includeTimeslots

(Optional) < Boolean flag— 0|1|true|false > If this is set to true or 1, the response includes the resource count. Argument Type: Boolean

filters

(Optional) Filters to use during the search operation. Argument Type: Collection

timeZone

(Optional) The time zone to use when interpreting times. Argument Type: String

Response

Retrieves zero or more schedule objects.

ec-perl

Syntax:

$<object>->getRunSchedules({<optionals>});

Example:

$ec->getRunSchedules({beginDate => "2016-07-01", endDate => "2016-09-01", includeTimeslots => true, timeZone => "local"});

ectool

Syntax:

ectool getRunSchedules [optionals]

Example:

ectool getRunSchedules --beginDate "2016-07-01" --endDate => "2016-09-01" --includeTimeslots true --timeZone "local"

Back to top

modifyEnvironment

Modifies an environment.

ArgumentDescription

projectName

The project name.

Argument Type: String

environmentName

Name of the environment that must be unique among all projects.

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted by CloudBees CD .

Argument Type: String

environmentEnabled

(Optional) True to enable rolling deploy on this environment.

Argument Type: Boolean

newName

(Optional) New name for the environment. Argument Type: String

reservationRequired

(Optional) < Boolean flag - 0|1|true|false > Set this flag to "true" to allow deployments to run using only using environment reservations.

Argument Type: Boolean

rollingDeployEnabled

(Optional) < Boolean flag - 0|1|true|false > Set this flag to "true" or "1" to enable the environment.

Argument Type: Boolean

rollingDeployType

(Optional) The type of rolling deploy supported by the environment.

Argument Type: RollingDeployType

Positional arguments

projectName, environmentName

Response

Returns the modified environment object.

ec-perl

Syntax:

$<object>->modifyEnvironment(<projectName>, <environmentName>, {<optionals>});

Example:

$ec->modifyEnvironment("Default", "Pet Store", {newName => "New Pet Store", description => "Pet store website", rollingDeployEnabled => true});

ectool

Syntax:

ectool modifyEnvironment <projectName> <environmentName> [optionals]

Example:

ectool modifyEnvironment "Default" "Pet Store" --newName "New Pet Store" --description "Pet store website" --rollingDeployEnabled true

Back to top

modifyEnvironmentInventoryItem

Modifies an existing environment inventory item.

ArgumentDescription

projectName

Name of the project.

Argument Type: String

environmentName

Name of the environment.

Argument Type: String

Required for application-scoped component objects:

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

componentName

Name of the component that owns the inventory item. Argument Type: String

resourceName

Name of the resource where the item is installed. Argument Type: String

Required for application-scoped service objects:

applicationName

Name of the application. Supply one of applicationName or serviceName. Argument Type: String

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

containerName

Name of the container. Argument Type: String

Required for project-scoped service objects:

serviceName

Name of the service. Supply one of applicationName or serviceName. Argument Type: String

containerName

Name of the container. Argument Type: String

Optional arguments:

applicationTierName

(Optional) Name of the application tier.

Argument Type: String

artifactName

(Optional) Artifact name for the inventory item.

Argument Type: String

artifactSource

(Optional) Source of the artifact.

Argument Type: String

artifactUrl

(Optional) URL of the artifact.

Argument Type: String

artifactVersion

(Optional) Artifact version for the inventory item.

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted by CloudBees CD .

Argument Type: String

environmentProjectName

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

Argument Type: String

newName

(Optional) The new name for the object.

Argument Type: String

status

(Optional) Deployment status of the inventory item. Possible values include: success, warning, error, skipped

Argument Type: String

Positional arguments

projectName, environmentName

Response

Retrieves the modified environmentInventoryItem object.

ec-perl

Syntax:

$<object>->modifyEnvironmentInventoryItem(<projectName>, <environmentName>, <applicationName>, <componentName>, <resourceName>, {<optionals>});

Example:

$ec->modifyEnvironmentInventoryItem("Default", "PROD", "Deploy", "WAR file", "Server 1", {artifactVersion => "V3"});

ectool

Syntax:

ectool modifyEnvironmentInventoryItem <projectName> <environmentName> <applicationName> <componentName> <resourceName> [optionals]

Example:

ectool modifyEnvironmentInventoryItem "Default" "PROD" "Deploy" "WAR file" "Server 1" --artifactVersion "V3"

Back to top

modifyEnvironmentMap

Modifies an existing service environment map.

ArgumentDescription

projectName

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

Argument Type: String

environmentName

Name of the environment.

Argument Type: String

serviceName

(Optional) The name of the service.

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted by CloudBees CD .

Argument Type: String

environmentMapName

(Optional) The name of the tier map. If not specified the operation will assume a hyphenated service and environment name.

Argument Type: String

environmentProjectName

(Optional) The name of the environment’s project.

Argument Type: String

newName

(Optional) New name for an existing object. Argument Type: String

serviceEntityRevisionId

(Optional) Revision ID of the versioned object.

Argument Type: String

Positional arguments

projectName, environmentName

Response

Retrieves an environmentMap object.

ec-perl

Syntax:

$<object>->modifyEnvironmentMap(<projectName>, <environmentName>, {<optionals>});

Example:

$ec->modifyEnvironmentMap("Default", "Web Server Env", {description => "Required"});

ectool

Syntax:

ectool modifyEnvironmentMap <projectName> <environmentName> [optionals]

Example:

ectool modifyEnvironmentMap "Default" "Web Server Env" --description "Required"

Back to top

modifyReservation

Modifies an environment reservation.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

reservationName

The name of the environment reservation. Argument Type: String

applicationName

(Optional) The name of the application Argument Type: String

beginDate

(Optional) The date when the reservation begins. Argument Type: String

blackout

(Optional) < Boolean flag — 0|1|true|false > When this argument is set to true or 1, no deployments are allowed to run during the specified time period. Argument Type: Boolean

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD . Argument Type: String

endDate

(Optional) The date when the reservation ends. Argument Type: String

environmentName

(Optional) The name of the environment. Argument Type: String

environmentProjectName

(Optional) The name of the environment project. Argument Type: String

environmentTierName

(Optional) The name of the environment tier. Argument Type: String

monthDays

(Optional) A list of numbers from 1 to 31 separated by spaces, indicating zero or more days of the month. Argument Type: String

newName

(Optional) New name for an existing object. Argument Type: String

overlap

< Boolean flag — 0|1|true|false > When this argument is set to true or 1, this reservation can overlap with another reservation. By default, reservations are not overlapped. Argument Type: Boolean

pipelineName

(Optional) The name of the pipeline. Argument Type: String

recurrence

(Optional) < Boolean flag — 0|1|true|false > Recurrence reservation When this argument is set to true or 1, the reservation is a recurring reservation. Argument Type: Boolean

(Optional) recurrenceEndDate

The date when the recurring reservation ends. Argument Type: String

releaseName

(Optional) The name of the release. Argument Type: String

timeZone

(Optional) The time zone to use when interpreting times. Argument Type: String

weekDays

(Optional) Restricts the schedule to specified days of the week. Specify days of the week separated by spaces. Use English names "Monday", "Tuesday". Argument Type: String

Response

Retrieves the modified reservation object.

ec-perl

Syntax:

$<object>->modifyReservation(<projectName>, <reservationName>, {<optionals>});

Example:

$ec->modifyReservation('Default', 'Main branch', {environmentName => "Web Server", applicationName => "Heat Clinic", beginDate => '22:00', endDate => '23:30', timeZone => 'local', overlap => false, weekDays => 'Monday' 'Wednesday' 'Friday' 'Sunday'});

ectool

Syntax:

ectool modifyReservation <projectName> <reservationName> [optionals]

Example:

ectool modifyReservation 'Default' 'Main branch' --environmentName "Web Server" --applicationName "Heat Clinic" --beginDate '22:00' --endDate '23:30' --timeZone 'local' --overlap true --weekDays 'Monday' 'Wednesday' 'Friday' 'Sunday'

Back to top

seedEnvironmentInventory

Seeds the environment with a new inventory to mimic an actual application- or release-scoped deployment.

ArgumentDescription

projectName

include::partial$name-for-the-project.adoc[] Argument Type: String

environmentName

Name of the environment. Argument Type: String

applicationName

Application that owns the inventory item. Use for existing applications. Argument Type: String

applicationProcessName

Application process that will be deployed to the environment. Argument Type: String

status

Deployment status of the environment inventory. Argument Type: JobOutcome

Seeding an inventory for a non-existing application (release and not-release scoped):

applicationTierName

Application tier that owns the inventory item. Use for non-existing applications. Argument Type: String

Seeding an inventory for an application object without a snapshot:

resourceNames

Resources assigned to the environment. Argument Type: Collection

componentName

Component that owns the inventory item Argument Type: String

artifactName

Artifact name for the inventory item. Argument Type: String

artifactVersion

Artifact version for the inventory item. Argument Type: String

Seeding an inventory for an application object with a snapshot:

resourceNames

Resources assigned to the environment. Argument Type: Collection

snapshotName

Name of the snapshot. Argument Type: String

Seeding an inventory for a release-scoped application object:

artifactName

Artifact name for the inventory item. Argument Type: String

artifactVersion

Artifact version for the inventory item. Argument Type: String

componentName

Component that owns the inventory item Argument Type: String

releaseName

Name of the release. Argument Type: String

releaseProjectName

Name of the project to which releaseName belongs. Argument Type: String

resourceNames

Resources assigned to the environment. Argument Type: Collection

stageName

Name of the stage. Argument Type: String

Optional arguments:

artifactSource

(Optional) Source of the artifact. Argument Type: String

artifactUrl

(Optional) URL of the artifact. Argument Type: String

environmentProjectName

(Optional) Name for the project to which the environment or environment template belongs. Argument Type: String

Positional arguments

projectName, environmentName, applicationName, applicationProcessName, status

Response

Returns the new environmentInventory object.

ec-perl

Syntax:

$<object>->seedEnvironmentInventory(<projectName>, <environmentName>, <applicationName>, <applicationProcessName>, <status>, {<optionals>});

Example:

$ec->seedEnvironmentInventory("Default", "PROD", "Deploy", "Clean up DB", "success", {artifactVersion => "3.0"});

ectool

Syntax:

ectool seedEnvironmentInventory <projectName> <environmentName> <applicationName> <applicationProcessName> <status> [optionals]

Example:

ectool seedEnvironmentInventory "Default" "PROD" "Deploy" "Clean up DB" "success" --artifactVersion "3.0"

Back to top

Email Notifier management
Environment tier