Workflow Definition Management

10 minute readReference

createStateDefinition

Creates a new state definition for a workflow definition. Optionally, a state may launch either a procedure or a sub-workflow as its "process" when the state is entered.

You must specify projectName, workflowDefinitionName, and stateDefinitionName.

Arguments Descriptions

projectName

The name of the project.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

stateDefinitionName

Choose any unique name of your choice for the state definition. This name must be unique within the workflow definition.

Argument type: String

actualParameters

(Optional) Specifies the values to pass as parameters to the process. Each parameter value is specified with an actualParameterName and a value. The actualParameterName must match the name of a formal parameter on the process. For more information about parameters, click here .

Argument type: Map

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

startable

(Optional) < Boolean flag— 0|1|true|false > – A value of 1 or true means this state definition can be the initial state of an instantiated workflow.

Argument type: Boolean

subprocedure

(Optional) Name of the procedure launched when the state is entered. Also requires subproject.

Argument type: String

subproject

(Optional) Name of the project containing the procedure or workflow launched when the state is entered.

Argument type: String

substartingState

(Optional) Name of the starting state for the workflow launched when the state is entered. Also requires subproject and subworkflowDefinition.

Argument type: String

subworkflowDefinition

(Optional) Name of the workflow definition launched when the state is entered. Also requires subproject.

Argument type: String

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName

Response

One stateDefinition element.

ec-perl

syntax: $cmdr->createStateDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, {<optionals>});

Example

$cmdr->createStateDefinition ("Default", "BTD", "build", {startable => 1, subproject => "product", subprocedure => "Master", description => "Production"});

ectool

syntax: ectool createStateDefinition <projectName> <workflowDefinitionName> <stateDefinitionName> [optionals]

Example

ectool createStateDefinition "Default" "BTD" "build" --startable 1 --subproject "product" --subprocedure :Master" --description "Production"

createTransitionDefinition

Creates a new transition definition for workflow definition.

You must specify projectName, workflowDefinitionName, stateDefinitionName, transitionDefinitionName, and targetState.

Arguments Descriptions

projectName

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

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

transitionDefinitionName

The name of the transition that must be unique among all state definitions.

Argument type: String

targetState

Target state for the transition definition.

Argument type: String

actualParameters

(Optional) Specifies the values to pass as parameters to the target state. Each parameter value is specified with an actualParameterName and a value. The actualParameterName must match the name of a formal parameter on the target state. For more information about parameters, click here .

Argument type: Map

condition

(Optional) A fixed text or text embedding property references that are evaluated into a logical TRUE or FALSE. An empty string, a "0" or "false" is interpreted as FALSE. Any other result string is interpreted as TRUE. This field is ignored by the server if trigger is set to manual.

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

trigger

(Optional) Type of trigger for this transaction.

Possible values are: onEnter|onStart|onCompletion|manual

Argument type: TransitionTrigger

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName, transitionDefinitionName, targetState

Response

One transitionDefinition element.

ec-perl

syntax: $cmdr->createTransitionDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, <transitionDefinitionName>, <targetState>, {<optionals>});

Example

$cmdr->createTransitionDefinition ("Default", "BTD", "build", "build2test", "test", {trigger => "manual", description => "Production"});

ectool

syntax: ectool createTransitionDefinition <projectName> <workflowDefinitionName> <stateDefinitionName> <transitionDefinitionName> <targetState> [optionals]

Example

ectool createTransitionDefinition "Default" "BTD" "build" "build2test" "test" --trigger manual --description "Production"

createWorkflowDefinition

Creates a new workflow definition for a project.

You must enter a projectName and a workflowDefinitionName.

Arguments Descriptions

projectName

Name for the project; must be unique among all projects.

Argument type: String

workflowDefinitionName

Name of the workflow definition; must be unique within the 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

workflowNameTemplate

(Optional) The name of the workflow template that the system uses to name instances of this workflow definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName

Response

One workflowDefinition element.

ec-perl

syntax: $cmdr->createWorkflowDefinition (projectName>, <workflowDefinitionName>, {<optionals>});

Example

$cmdr->createWorkflowDefinition ("Default", "BTD", {description => "Production"});

ectool

syntax: ectool createWorkflowDefinition <projectName> <workflowDefinitionName> [<optionals>]

Example

ectool createWorkflowDefinition "Default" "BTD" --description "Production"

deleteStateDefinition

Deletes a state definition.

You must specify a projectName, workflowDefinitionName, and stateDefinitionName.

Arguments Descriptions

projectName

The name of the project containing the state definition.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName

Response

None or a status OK message.

None or a status OK message.

ec-perl

syntax: $cmdr->deleteStateDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>);

Example

$cmdr->deleteStateDefinition ("Default", "BTD", "build");

ectool

syntax: ectool deleteStateDefinition <projectName> <workflowDefinitionName> <stateDefinitionName>

Example

ectool deleteStateDefinition "Default" "BTD" "build"

deleteTransitionDefinition

Deletes a transition definition.

You must specify a projectName, workflowDefinitionName, stateDefinitionName, and transitionDefinitionName.

Arguments Descriptions

projectName

The name of the project containing the transition definition.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

transitionDefinitionName

The name of the transition definition.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName, transitionDefinitionName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteTransitionDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, <transitionDefinitionName>);

Example

$cmdr->deleteTransitionDefinition ("Default", "BTD", "build", "build2test");

ectool

syntax: ectool deleteTransitionDefinition <projectName> <workflowDefinitionName> <stateDefinitionName> <transitionDefinitionName>

Example

ectool deleteTransitionDefinition "Default" "BTD" "build" "build2test"

deleteWorkflowDefinition

Deletes a workflow definition, including all state and transition definitions.

You must specify a projectName and a workflowDefinitionName

Arguments Descriptions

projectName

The name of the project containing the workflow definition to delete.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteWorkflowDefinition (<projectName>, <workflowDefinitionName>);

Example

$cmdr->deleteWorkflowDefinition ("Default", "BTD");

ectool

syntax: ectool deleteWorkflowDefinition <projectName> <workflowDefinitionName>

Example

ectool deleteWorkflowDefinition "Default" "BTD"

getStateDefinition

Retrieves a state definition by its name.

You must specify projectName, workflowDefinitionName, and stateDefinitionName.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

workflowDefinitionName

Name of the workflow definition.

Argument type: String

stateDefinitionName

Name of the state definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName

Response

One stateDefinition element.

ec-perl

syntax: `$cmdr->getStateDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>); `

Example

$cmdr->getStateDefinition ("Default", "BTD", "build");

ectool

syntax: ectool getStateDefinition <projectName> <workflowDefinitionName> <stateDefinitionName>

Example

ectool getStateDefinition "Default" "BTD" "build"

getStateDefinitions

Retrieves all state definitions in a workflow definition.

You must specify projectName and workflowDefinitionName.

Arguments Descriptions

projectName

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

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

includeFormalParameters

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

If this argument is set to 1 or true, formal parameters will also be included in the response.

Argument type: Boolean

startableOnly

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

If this argument is set to 1 or true, only state definitions marked as startable will be included in the response.

Argument type: Boolean

Positional arguments

projectName, workflowDefinitionName

Response

One or more stateDefinition elements.

ec-perl

syntax: $cmdr->getStateDefinitions (<projectName>, <workflowDefinitionName>, {<optionals>});

Example

$cmdr->getStateDefinitions ("Default", "BTD", {startableOnly => 1});

ectool

syntax: ectool getStateDefinitions <projectName> <workflowDefinitionName> [optionals]

Example

ectool getStateDefinitions "Default" "BTD" --startableOnly 1

getTransitionDefinition

Finds a transition definition by its name.

You must specify projectName, workflowDefinitionName, stateDefinitionName, transitionDefinitionName.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

workflowDefinitionName

Name of the workflow definition.

Argument type: String

stateDefinitionName

Name of the state definition.

Argument type: String

transitionDefinitionName

Name of the transition definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName, transitionDefinitionName

Response

One transitionDefinition element.

ec-perl

syntax: $cmdr->getTransitionDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, <transitionDefinitionName>);

Example

$cmdr->getTransitionDefinition ("Default", "BTD", "build", "build2test");

ectool

syntax: ectool getTransitionDefinition <projectName> <workflowDefinitionName> <stateDefinitionName> <transitionDefinitionName>

Example

ectool getTransitionDefinition "Default" "BTD" "build" "build2test"

getTransitionDefinitions

Retrieves all transition definitions in a workflow definition.

You must specify projectName, stateDefinitionName, workflowDefinitionName.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

targetState

(Optional) The name of the target state that limits results to transition definitions that have the specified state definition as a target.

Argument type: String

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName

Response

Zero or more transitionDefinition elements.

ec-perl

syntax: $cmdr->getTransitionDefinitions (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, {<optionals>});

Example

$cmdr->getTransitionDefinitions ("projectA", "BTD", "build");

ectool

syntax: ectool getTransitionDefinitions <projectName> <workflowDefinitionName> <stateDefinitionName> [optionals]

Example

ectool getTransitionDefinitions "projectA" "BTD" "build"

getWorkflowDefinition

Retrieves a workflow definition by its name.

You must specify a projectName and a workflowDefinitionName.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

workflowDefinitionName

Name of the workflow definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName

Response

One workflowDefinition element.

ec-perl

syntax: $cmdr->getWorkflowDefinition (<projectName>, <workflowDefinitionName>);

Example

$cmdr->getWorkflowDefinition ("Default", "BTD");

ectool

syntax: ectool getWorkflowDefinition <projectName> <workflowDefinitionName>

Example

ectool getWorkflowDefinition "Default" "BTD"

getWorkflowDefinitions

Retrieves all workflow definitions in a project.

You must specify a projectName.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

Positional arguments

projectName

Response

Zero or more workflowDefinition elements.

ec-perl

syntax: $cmdr->getWorkflowDefinitions (<projectName>);

Example

$cmdr->getWorkflowDefinitions ("Default");

ectool

syntax: ectool getWorkflowDefinitions <projectName>

Example

ectool getWorkflowDefinitions "Default"

modifyStateDefinition

Modifies an existing state definition.

You must specify projectName, workflowDefinitionName, and stateDefinitionName.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

stateDefinitionName

The name of the state definition to modify.

Argument type: String

actualParameter

(Optional) Specifies the values to pass as parameters to the process. Each parameter value is specified with an actualParameterName and a value. The actualParameterName must match the name of a formal parameter on the called process.

Argument type: Map

clearActualParameters

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

If set to true or 1, all the actual parameters are removed from the definition.

Argument type: Boolean

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

newName

(Optional) New name for the state definition.

Argument type: String

startable

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

If this argument is set to 1 ` or `true, the workflow can begin in the specified state.

Argument type: Boolean

subprocedure

(Optional) The name of the procedure launched when the state is entered. It also requires subproject.

Argument type: String

subproject

(Optional) The name of the project containing the subprocedure or workflow that is launched when the state is entered.

Argument type: String

substartingState

(Optional) The name of the workflow starting state that is launched when the state is entered. Using this argument also requires subproject and subworkflowDefinition.

Argument type: String

subworkflowDefinition

(Optional) The name of the workflow definition that is launched when the state is entered. It also requires subproject.

Argument type: String

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName

Response

One stateDefinition element.

ec-perl

syntax: $cmdr->modifyStateDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, {optionals});

Example

$cmdr->modifyStateDefinition ("Default", "BTD", "build",       {startable => 1, subproject => "factory", subprocedure => "Master", description => "Build to deploy"});

ectool

syntax: ectool modifyStateDefinition <projectName> <workflowDefinitionName> <stateDefinitionName> [optionals]

Example

ectool modifyStateDefinition "Default" "BTD" "build" --startable 1 --subproject factory --subprocedure Master --description "Build to deploy"

modifyTransitionDefinition

Modifies an existing transition definition.

You must specify projectName, workflowDefinitionName, stateDefinitionName, and transitionDefinitionName.

Arguments Descriptions

projectName

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

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

transitionDefinitionName

The name of the transition definition to modify.

Argument type: String

actualParameter

(Optional) Specifies the values to pass as parameters to the target state. Each parameter value is specified with an actualParameterName and a value. The actualParameterName must match the name of a formal parameter on the target state.

clearActualParameters

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

If set to true or 1, all the actual parameters are removed from the definition.

Argument type: Boolean

condition

(Optional) A fixed text or text embedded property references that are evaluated into a logical "true" or "false". An empty string, a "0" or "false" is interpreted as "false". Any other result string is interpreted as "true". This field is ignored by the server if trigger is set to manual.

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

newName

(Optional) New name of the transition definition that must be a unique name within the workflow.

Argument type: String

targetState

(Optional) The target state for the transition definition.

Argument type: String

trigger

(Optional) Possible values are: onEnter|onStart|onCompletion|manual.

Argument type: TransitionTrigger

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName, transitionDefinitionName

Response

One transitionDefinition element.

ec-perl

syntax: $cmdr->modifyTransitionDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, <transitionDefinitionName>, {<optionals>});

Example

$cmdr->modifyTransitionDefinition ("Default", "BTD", "build", "build2test", {targetState => "Deploy", trigger => "onCompletion", description => "bypass all tests"});

ectool

syntax: ectool modifyTransitionDefinition <projectName> <workflowDefinitionName> <stateDefinitionName> <transitionDefinitionName> [optionals]

Example

ectool modifyTransitionDefinition "Default" "BTD" "build" "build2test" --targetState "Deploy" --trigger "onCompletion" –-description "bypass all tests"

modifyWorkflowDefinition

Modifies an existing workflow definition.

You must specify projectName and workflowDefinitionName.

Arguments Descriptions

projectName

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

Argument Type: String

Argument type: String

workflowDefinitionName

The name of the workflow definition to modify.

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

newName

(Optional) The new name for the workflow definition. It must be a unique name within the workflow.

Argument type: String

workflowNameTemplate

(Optional) The template used to determine default names for workflows launched from a workflow definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName

Response

One workflowDefinition element.

ec-perl

syntax: $cmdr->modifyWorkflowDefinition (<projectName>, <workflowDefinitionName>, {<optionals>});

Example

$cmdr->modifyWorkflowDefinition ("Default", "BTD", {newName => "Build Test Deploy", description => "changed name"});

ectool

syntax: ectool modifyWorkflowDefinition <projectName> <workflowDefinitionName> [optionals]

Example

ectool modifyWorkflowDefinition "Default" "BTD" --newName "Build Test Deploy" --description "changed name"

moveStateDefinition

Moves a state definition within a workflow definition.

You must specify projectName, workflowDefinitionName, and stateDefinitionName.

Arguments Descriptions

projectName

The name of the project containing the state definition.

Argument type: String

stateDefinitionName

The name of the state definition to move.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

beforeStateDefinition

(Optional) Use this option to reorder state definitions in a workflow definition. The state definition ( stateDefinitionName ) will be moved to a position just before the state definition "named" by this option. If omitted, the state definition is moved to the end of the workflow definition.

Argument type: String

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->moveStateDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, {<optionals>});

Example

$cmdr->moveStateDefinition ("Default", "BTD", "Unit test", {beforeStateDefinition => "Build"});

ectool

syntax: ectool moveStateDefinition <projectName> <workflowDefinitionName> <stateDefinitionName> [optionals]

Example

ectool moveStateDefinition "Default" "BTD" "Unit test" --beforeStateDefinition "Build"

moveTransitionDefinition

Moves a transition definition within a workflow definition.

You must specify projectName, workflowDefinitionName, stateDefinitionName, and transitionDefinitionName.

Arguments Descriptions

projectName

The name of the project containing the transition definition.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

transitionDefinitionName

The name of the transition definition to move.

Argument type: String

beforeTransitionDefinition

Use this option to move a transition definition in a workflow definition. The transition definition is moved to a position just before the transition definition named by this option. If omitted, the transition definition is moved to the end of the workflow definition.

Positional arguments

projectName, workflowDefinitionName, stateDefinitionName, transitionDefinitionName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->moveTransitionDefinition (<projectName>, <workflowDefinitionName>, <stateDefinitionName>, <transitionDefinitionName>, {<optionals>});

Example

$cmdr->moveTransitionDefinition ("Default", "BTD", "Build", "in", {beforeTransitionDefinition => "out"});

ectool

syntax: ectool moveTransitionDefinition <projectName> <workflowDefinitionName> <stateDefinitionName> <transitionDefinitionName> [optionals]

Example

ectool moveTransitionDefinition "Default" "BTD" "Build" "in" --beforeTransitionDefinition "out"