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'

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

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"