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/RO 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/RO 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'

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"

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"

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

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/RO 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/RO 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"

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/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, 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"