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

Workspace Management

4 minute readReference

createWorkspace

Creates a new workspace. A workspace definition consists of three paths to access the workspace in various ways:

agentDrivePath

agentUncPath —The agent uses agentUncPath and agentDrivePath to compute the drive mapping needed to make agentDrivePath valid in the step (see examples below).

agentUnixPath

Examples for agentDrivePath and agentUncPath :

agentDrivePath agentUncPath Result from running a step in "job123" that uses this workspace

N:\

\\server\share

The agent maps \\server\share to drive n: and runs the step in ` n:\job123`.

N:\sub1

\\server\share\dir1\sub1

The agent maps \\server\share\dir1 to drive n: and runs the step in ` n:\sub1\job123`.

N:\sub1

\\server\share\dir1

Invalid! No mapping can be deduced from this pair of values.

C:\ws

C:\ws

A local workspace on the agent. No drive mapping is needed. The job step runs in ` c:\ws\job123`.

C:\ws

Same as if agentUncPath were set identical to agentDrivePath.

You must specify a workspaceName.

Arguments Descriptions

workspaceName

The workspace name.

Argument type: String

agentDrivePath

(Optional) Drive-letter-based path used by Windows agents to access the workspace in steps.

Argument type: String

agentUncPath

(Optional) UNC path used by Windows CloudBees CD web servers to access the workspace. The agent uses agentUncPath and agentDrivePath to compute the drive mapping needed for making agentDrivePath valid in the step.

Argument type: String

agentUnixPath

(Optional) UNIX path used by UNIX agents and Linux CloudBees CD web servers to access the workspace.

Argument type: String

credentialName

(Optional) Credential to use when connecting to a network location. credentialName can be one of two forms: relative (for example, "cred1" ) —the credential is assumed to be in the project that contains the request target object 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

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

local

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

When the value is 1 or true, the workspace is local.

Argument type: String

workspaceDisabled

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

When the value is 1 or true, the workspace is disabled.

Argument type: String

zoneName

(Optional) The name of the zone where this workspace resides.

Argument type: String

Positional arguments

workspaceName

Response

Returns a workspace element.

ec-perl

syntax: $cmdr->createWorkspace(<workspaceName>, {<optionals>});

Example

$cmdr->createWorkspace('test', {agentDrivePath => 'c:/workspace', agentUncPath => 'c:/workspace', agentUnixPath => '/mnt/server/workspace'});

ectool

syntax: ectool createWorkspace <workspaceName> [optionals]

Example

ectool createWorkspace test --agentDrivePath c:/workspace --agentUncPath c:/workspace --agentUnixPath '/mnt/server/workspace'

Back to top

deleteWorkspace

Deletes a workspace.

You must specify the workspaceName.

Arguments Descriptions

workspaceName

The name of the workspace.

Argument type: String

Positional arguments

workspaceName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteWorkspace(<workspaceName>);

Example

$cmdr->deleteWorkspace("Test summaries");

ectool

syntax: ectool deleteWorkspace <workspaceName>

Example

ectool deleteWorkspace "Test summaries"

Back to top

getWorkspace

Retrieves a workspace by its name.

You must specify the workspaceName.

Arguments Descriptions

workspaceName

The name of the workspace.

Argument type: String

Positional arguments

workspaceName

Response

One workspace element.

ec-perl

syntax: $cmdr->getWorkspace(<workspaceName>);

Example

$cmdr->getWorkspace("Test results");

ectool

syntax: ectool getWorkspace <workspaceName>

Example

ectool getWorkspace "Test results"

Back to top

getWorkspaces

Retrieves all workspaces.

Arguments Descriptions

None

–

Positional arguments

None

Response

Zero or more workspace elements.

ec-perl

syntax: $cmdr->getWorkspaces();

Example

$cmdr->getWorkspaces();

ectool

syntax: ectool getWorkspaces

Example

ectool getWorkspaces

Back to top

modifyWorkspace

Modifies an existing workspace.

A workspace definition consists of three paths to access the workspace in various ways:

agentDrivePath

agentUncPath —The agent uses agentUncPath and agentDrivePath to compute the drive mapping needed to make agentDrivePath valid in the step (see examples below).

agentUnixPath

Examples for agentDrivePath and agentUncPath :

agentDrivePath agentUncPath Result from running a step in "job123" that uses this workspace

N:\

`\\server\share `

The agent maps \\server\share to drive n: and runs the step in n:\job123.

N:\sub1

\\server\share\dir1\sub1

The agent maps \\server\share\dir1 to drive n: and runs the step in n:\sub1\job123.

N:\sub1

`\\server\share\dir1 `

Invalid! No mapping can be deduced from this pair of values.

C:\ws

C:\ws

A local workspace on the agent. No drive mapping is needed. The job step runs in c:\ws\job123.

C:\ws

Same as if agentUncPath were set identical to agentDrivePath.

You must specify a workspaceName.

Arguments Descriptions

workspaceName

The name of the workspace to modify.

Argument type: String

agentDrivePath

(Optional) Drive-letter-based path used by Windows agents to access the workspace in steps.

Argument type: String

agentUncPath

(Optional) UNC path used by Windows CloudBees CD web servers to access the workspace. The agent uses agentUncPath and agentDrivePath to compute the drive mapping needed for making agentDrivePath valid in the step.

Argument type: String

agentUnixPath

(Optional) UNIX path used by UNIX agents and Linux CloudBees CD web servers to access the workspace.

Argument type: String

credentialName

(Optional) credentialName can be one of two forms: relative (for example, "cred1" ) —the credential is assumed to be in the project that contains the request target object. 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

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

local

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

If the value is 1 or true, the workspace is local.

Argument type: Boolean

newName

(Optional) Enter any name of your choice to rename the workspace.

Argument type: String

workspaceDisabled

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

If the value is 1 or true, the workspace is disabled.

Argument type: Boolean

zoneName

(Optional) The name of the zone where this workspace resides.

Argument type: String

Positional arguments

workspaceName

Response

Returns a workspace element.

ec-perl

syntax: $cmdr->modifyWorkspace(<workspaceName>, {<optionals>});

Example

$cmdr->modifyWorkspace("Test", {description => "QA test workspace"});

ectool

syntax: ectool modifyWorkspace <workspaceName> [optionals]

Example

ectool modifyWorkspace "Test" --description "QA test workspace"

Back to top

resolveFile

Resolves the path to a log file or artifact in a workspace.

You must specify fromAgentId and workspaceName.

Arguments Descriptions

fromAgentId

Identifier of the agent requesting the route to a destination agent or artifact repository.

Argument type: Long

workspaceName

Name of the workspace.

Argument type: String

jobId

(Optional)

The unique CloudBees CD -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, assigned automatically when the job is created. Also accepts a job name assigned to the job by its name template.

Argument type: UUID

resourceName

(Optional) Name of the resource.

Argument type: String

Positional arguments

fromAgentId, workspaceName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->resolveFile ( <fromAgentId>, <workspaceName>, {<optionals>});

Example

$cmdr->resolveFile ("Machine 2", "Dev shared workspace", {resourceName=> "Server 1"});

ectool

syntax: ectool resolveFile <fromAgentId> <workspaceName> [optionals]

Example

ectool resolveFile "Machine 2" "Dev shared workspace" --resourceName "Server 1"

Back to top

Work items
Miscellaneous management