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 managementGet application environment inventoryInstalling 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
IntroductionaccesstokenaclaclentryactualparameterapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitionstringresulttagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

Miscellaneous Management

37 minute readReference

acquireNamedLock

Retrieves the named lock.

Arguments Descriptions

lockName

Name of the lock.

Argument type: String

create

< Boolean flag — 0|1|true|false >

When this argument is set to true or 1, the system creates a lock if it does not exist.

Argument type: Boolean

Positional arguments

lockName, create

Response

None or a status OK message.

ec-perl

syntax: $cmdr->acquireNamedLock(<lockName>, <create>);

Example

$cmdr->acquireNamedLock ("Group2", true);
▼

ectool

syntax: ectool acquireNamedLock <lockName> <create>

Example

ectool acquireNamedLock "Group 2" true
▼

changeOwner

Changes the owner of an object.

You must specify an object name. You must also specify the new owner name if it is not the current user.

The modify privilege on the "admin" system ACL is required to change the owner of an object. For email notifiers, the owner can be changed if the current user has sufficient privileges to delete and recreate the object.
Arguments Descriptions

applicationName

(Optional) The name of the application.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

credentialName

(Optional) credentialName can be in one of these formats:

  • relative (for example, "cred1" ) —the credential is assumed to be in the project that contains the request target object. Requires a qualifying project name.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" ) —the credential can be from any specified project, regardless of the target object’s project.

Argument type: String

dashboardName

(Optional) The name of a dashboard.

Argument type: String

environmentName

(Optional) The name of an environment.

Argument type: String

environmentTemplateName

(Optional) The name of an environment template.

Argument type: String

environmentTierName

(Optional) The name of an environment tier.

Argument type: String

groupName

(Optional) The full name of a group. For Active Directory and LDAP, this is a full domain name.

Argument type: String

newOwnerName

(Optional) The name of the new owner for this object. This defaults to the current user.

Argument type: String

notifierName

(Optional) The name of the email notifier.

Argument type: String

pluginName

(Optional) The name of the plugin. This is the plugin key for a promoted plugin or a plugin key and version for an unpromoted plugin.

Argument type: String

procedureName

(Optional) The name of the procedure. It can be a path to the procedure. When using this argument, you must also enter the projectName.

Argument type: String

processName

(Optional) The name of a process. It can be a path to the process.

Argument type: String

processStepName

(Optional) The name of a process step. It can be a path to the process step.

Argument type: String

projectName

(Optional) The name of the project. It can be a path to the project. The project name is ignored for credentials, procedure, steps, and schedules when it is specified as a path.

Argument type: String

propertySheetId

(Optional) The unique identifier for a property sheet that is assigned automatically when the property sheet is created.

Argument type: UUID

reportName

(Optional) The name of a report.

Argument type: String

reportObjectTypeName

(Optional) The name of a report object type.

Argument type: String

resourceName

(Optional) The name of the resource.

Argument type: String

scheduleName

(Optional) The name of the schedule. It can be a path to the schedule. When using this argument, you must also use projectName.

Argument type: String

serviceName

(Optional) The name of the service.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stepName

(Optional) The name of the step. It can be a path to the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

userName

(Optional) The full name of the user. For Active Directory and LDAP, the name can be user@domain.

Argument type: String

widgetName

(Optional) The name of a widget.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workspaceName

(Optional) The name of the workspace.

Argument type: String

Positional arguments

None

Response

Returns the modified object.

ec-perl

syntax: $cmdr->changeOwner({<optionals>});

Examples

The following example changes the owner of the default project to the current user:

$cmdr->changeOwner ({"projectName" => "Default"});
▼

The following example changes the owner of a project named Q2Release to a new owner named hjindal:

$cmdr->changeOwner ({"newOwnerName" => "hjindal", "projectName" => "Q2Release"});
▼

ectool

syntax: ectool changeOwner [optionals]

Examples

The following example changes the owner of the default project to the current user:

ectool changeOwner –-projectName "Default"
▼

The following example changes the owner of a project named Q2Release to a new owner named hjindal:

ectool changeOwner --newOwnerName "hjindal" –-projectName "Q2Release"
▼

clone

Makes a copy of an existing CloudBees CD/RO object.

You cannot clone parameters, artifacts, or artifact versions.
To find the entity you want to clone, you must specify the following arguments: —A new name for the cloned object ( cloneName ) —Locator arguments for the objects that can be cloned For example, if you want to clone a project, you must specify the name of the project that you want to clone.
Arguments Descriptions

Naming

cloneName

(Optional) New name of the cloned copy of an object. The cloneName specifies the path to the new object, possibly in an alternate location. If no container path is specified, the new object is created inside the same container as the original. If no name is specified, the server will generate a name.

Argument type: String

Optionals

disableProjectTracking

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

If set to true, when copying a project, even if Change Tracking is enabled for the original project, Change Tracking is disabled for the new copy of the project from its creation.

If you do not need to track changes for the new copy, this avoids the Change Tracking overhead that would otherwise slow down the copying operation, and also saves having to subsequently disable Change Tracking for the new copy of the project.

Argument type: Boolean

reducedDetailChangeHistory

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

Use this argument for large projects containing over 20,000 audited objects with Change Tracking enabled.

When this argument is set to true or 1, CloudBees CD/RO automatically decreases the amount of Change History indexing information that it saves in a large project, which reduces the level of detail for Change Tracking-intensive operations in the change history. This can make it harder to revert an object to a specific state and to find information in the change history when you troubleshoot or debug an issue.

Set this argument to false or 0 to suppress this behavior so that CloudBees CD/RO does not change the amount of indexing information for a large project. This causes the operation to take longer and put more load on the database, but the change history will have the full details of the entities owned by objects in the project.

Argument type: Boolean

Locators

applicationName

(Optional) The name of the application that is unique among all projects.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

(Optional) The name of the artifact version.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration ( emailConfig ).

Argument type: String

credentialName

(Optional) The name of the credential that can be specified in one of these formats:

relative (for example, cred1 )—The credential is assumed to be in the project that contains the target object.

absolute (for example, /projects/BuildProject/credentials/cred1)—The credential can be from any specified project, regardless of the project with the target object.

Argument type: String

environmentName

(Optional) The name of the environment that must be unique among all projects.

Argument type: String

environmentTemplateName

(Optional) The name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) The name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

flowName

(Optional) Name of the flow that must be unique within the project.

Argument Type: String

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) Name of the flow state.

Argument Type: String

flowStateName

(Optional) Name of the flow state that must be unique within the flow.

Argument Type: String

flowTransitionName

Name of the flow transition that must be unique within the flow state.

Argument Type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of the group.

Argument type: String

jobId

(Optional) The unique CloudBees CD/RO -generated identifier (a UUID) for a job that is assigned automatically when the job is created. The system also accepts a job name assigned to the job by its name template.

Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

notifierName

(Optional) The name of the email notifier ( emailNotifier ).

Argument type: String

objectId

(Optional) The object id as returned by findObjects.

Argument type: String

path

(Optional) The property path for the object.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin.

Argument type: String

procedureName

(Optional) The name of the procedure that you want to clone. When using this argument, you must also enter the projectName.

Argument type: String

processName

(Optional) The name of the process.

Argument type: String

processStepName

(Optional) The name of the process step.

Argument type: String

projectName

(Optional) The name of the project that you want to clone.

When an application, a pipeline, or a release is cloned across different projects, you might need to fix the references after the objects are cloned. For example, if a pipeline with an application reference in the "default" project is cloned to a different project, the application reference needs to be fixed after the pipeline is cloned.

Argument type: String

propertySheetId

(Optional) The unique identifier for a property sheet that is assigned automatically when the property sheet is created.

providerName

(Optional) The unique name of the directory provider, such as the LDAP or Active Directory provider name.

Argument type: String

releaseName

(Optional) The name of the Release which owns the property.

Argument type: String

repositoryName

(Optional) The name of the repository used for artifact management.

Argument type: String

resourceName

(Optional) The name of the resource that you want to clone.

Argument type: String

resourcePoolName

(Optional) The name of a resource pool.

Argument type: String

resourceTemplateName

(Optional) The name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule that you want to clone. When using this argument, you must also enter projectName.

Argument type: String

snapshotName

(Optional) The name of the snapshot that you want to clone.

Argument type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) The name of the procedure step that you want to clone. When using this argument, you must also enter projectName and procedureName.

Argument type: String

systemObjectName

(Optional) System object names include:

admin|artifacts|directory|emailConfigs |forceAbort|licensing|log|plugins|priority |projects|repositories|resources|server |session|workspaces|zonesAndGateways

Argument type: SystemObjectName

taskName

(Optional) The name of the task.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

transitionName

(Optional) The name of the transition.

Argument type: String

userName

(Optional) The name of the user where you may need to expand the string.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

workspaceName

(Optional) The name of the workspace that you want to clone.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

None.

To clone an existing entity, you must specify the following arguments:

  • A new name for the cloned object ( cloneName )

  • Locator arguments for the objects that can be cloned