Parameter Management

attachParameter

Attaches a formal parameter to a step. Attaching a parameter allows a step to use the credential (passed in a parameter) as an actual parameter to a subprocedure call or directly in a getFullCredential call in a command step. For more information about parameters, go here .

You must specify projectName and formalParameterName.

The attachParameter command in CloudBees CD/RO 6.0 and newer releases is not compatible with previous CloudBees CD/RO releases.

Arguments	Descriptions
projectName	Name of the project. This name must be unique among all projects. Argument Type: String Argument Type: String
formalParameterName	Name of the parameter. Argument Type: String
procedureName	(Optional) Name of the procedure to which the parameter is attached. Argument Type: String
stepName	(Optional) Name of the procedure step to which the parameter is attached. Argument Type: String
applicationName	(Optional) Name of the application to which the parameter is attached. Argument Type: String
componentApplicationName	(Optional) Name of the component in the application to which the parameter is attached. Argument Type: String
componentName	(Optional) Name of the component to which the parameter is attached. Argument Type: String
gateType	(Optional) The type of the gate to which the parameter is attached: POST or PRE. Argument Type: GateType
pipelineName	(Optional) Name of the pipeline to which the parameter is attached. Argument Type: String
processName	(Optional) Name of the process to which the parameter is attached. Argument Type: String
processStepName	(Optional) Name of the process step to which the parameter is attached. Argument Type: String
releaseName	(Optional) Name of the release to which the parameter is attached. Argument Type: String
serviceName	(Optional) Name of the service. Argument type: String
stageName	(Optional) Name of the task to which the parameter is attached. Argument Type: String
stateDefinitionName	(Optional) Name of the workflow state definition to which the parameter is attached. Argument Type: String
taskName	(Optional) Name of the task to which the parameter is attached. Argument Type: String
workflowDefinitionName	(Optional) Name of the workflow state definition to which the parameter is attached. Argument Type: String

Arguments

Descriptions

projectName

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

Argument Type: String

formalParameterName

Name of the parameter.

Argument Type: String

procedureName

(Optional) Name of the procedure to which the parameter is attached.

Argument Type: String

stepName

(Optional) Name of the procedure step to which the parameter is attached.

Argument Type: String

applicationName

(Optional) Name of the application to which the parameter is attached.

Argument Type: String

componentApplicationName

(Optional) Name of the component in the application to which the parameter is attached.

Argument Type: String

componentName

(Optional) Name of the component to which the parameter is attached.

Argument Type: String

gateType

(Optional) The type of the gate to which the parameter is attached: POST or PRE.

Argument Type: GateType

pipelineName

(Optional) Name of the pipeline to which the parameter is attached.

Argument Type: String

processName

(Optional) Name of the process to which the parameter is attached.

Argument Type: String

processStepName

(Optional) Name of the process step to which the parameter is attached.

Argument Type: String

releaseName

(Optional) Name of the release to which the parameter is attached.

Argument Type: String

serviceName

(Optional) Name of the service.

Argument type: String

stageName

(Optional) Name of the task to which the parameter is attached.

Argument Type: String

stateDefinitionName

(Optional) Name of the workflow state definition to which the parameter is attached.

Argument Type: String

taskName

(Optional) Name of the task to which the parameter is attached.

Argument Type: String

workflowDefinitionName

(Optional) Name of the workflow state definition to which the parameter is attached.

Argument Type: String

Positional arguments

projectName, procedureName, stepName, formalParameterName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->attachParameter(<projectName>, <procedureName>, <stepName>, <formalParameterName>, {<optionals>});

Example

$cmdr->attachParameter("Default", "Daily Run", "Get Resources",
  "SCM Credential" {stageName => "PROD"}));

ectool

syntax: ectool attachParameter <projectName> <procedureName <stepName> <formalParameterName> [optionals]

Example

ectool attachParameter "Default" "Daily Run" "Get Resources"
  "SCM Credential" --stageName "PROD"

createActualParameter

Creates a new actual parameter for a step that calls a nested procedure. The parameter is passed to the nested procedure when the step runs. At runtime, the actual parameter name must match the name of a formal parameter in the nested procedure.

Passing Actual Parameters

You can use actual parameters in three types of API calls:

calling runProcedure to start a new job
setting up a schedule
creating or modifying a subprocedure step

For example, when you call runProcedure using ectool, set the actual parameters to the procedure on the command line using the optional argument --actualParameter, followed by a list of name/value pairs. The following is an example of calling a procedure named MasterBuild:

ectool runProcedure "project A" --procedureName "MasterBuild"` --actualParameter Branch=main Type=Debug`

To make this call using the Perl API, define a list. Each element of the list is an anonymous hash reference that specifies one of the actual parameters. Now you can pass a reference to the list as the value of the actualParameter argument.

Here is the same example called via the Perl API:

# Run the procedure
      $xPath = $cmdr\->runProcedure("project A",
               {procedureName => "MasterBuild",
              actualParameter => [
         {actualParameterName => 'Branch',
                        value => 'main'},
          actualParameterName => 'Type',
                        value => 'Debug'},
      ]});

Specifying most arguments to the createStep API in Perl is fairly intuitive; like any other API, you specify key-value pairs in a hash argument for all optional parameters. However, specifying actual parameters is more involved because actual parameters are not arbitrary key-values characterizing the step. Instead, they are key-values characterizing actual parameters to the step. See the following createStep request in XML:

<createStep>
   <projectName>MyProject</projectName>
   <procedureName>MyProcedure</procedureName>
   <stepName>Step1</stepName>
   <actualParameter>
      <actualParameterName>parm1</actualParameterName>
      <value>myval</value>
   </actualParameter>
   <actualParameter>
      <actualParameterName>parm2</actualParameterName>
      <value>val2</value>
   </actualParameter>
</createStep>

Each actual parameter key-value is under an <actualParameter> element. Code this in the optional arguments hash in the Perl API like this:

{ ..., => ..., actualParameter => [{actualParameterName => 'parm1',
                                      value => 'myval'},
                       {actualParameterName => 'parm2',
                                      value => 'val2'}],
                                        ... => ...}

In other words, the value of the actualParameter key in the optional arguments hash is a list of hashes, each representing one actual parameter. If the sub-procedure call takes only one actual parameter, the value of the actualParameter key can be specified as just the hash representing the one parameter:

actualParameter => {actualParameterName => 'parm1',
                    value => 'myval'}

You must specify projectName, procedureName, stepName, and actualParameterName.

Arguments	Descriptions
projectName	Name of the project containing the procedure. The project name must be unique among all projects. Argument type: String
procedureName	Name of the procedure containing the step. Argument type: String
stepName	Name of the step that calls a subprocedure. Argument type: String
actualParameterName	The name of the parameter. This name must be unique within the step, and at runtime, it must match the name of a formal parameter in the subprocedure. Argument type: String
applicationName	(Optional) Name of the application when the actual parameter is on an application process step. Argument type: String
componentName	(Optional) Name of the component when the actual parameter is on a component process step. Argument type: String
dashboardName	(Optional) Name of the dashboard. Argument type: String
flowName	(Optional) Name of the flow. Argument type: String
flowStateName	(Optional) Name of the flow state. Argument type: String
processName	(Optional) Name of the process when the actual parameter is on a process step. Argument type: String
processStepName	(Optional) Name of the process step when if the actual parameter is on a process step. Argument type: String
releaseName	(Optional) Name of the release if the actual parameter is on a release. Argument type: String
scheduleName	(Optional) Name of the schedule. Argument type: String
serviceName	(Optional) Name of the service, if the actual parameter is on a service process step. Argument type: String
stateDefinitionName	(Optional) Name of the state definition. Argument type: String
transitionDefinitionName	(Optional) Name of the transition definition. Argument type: String
value	(Optional) This value is passed to the subprocedure as the value of the matching formal parameter. Argument type: String
widgetName	(Optional) Name of the widget. Argument type: String
workflowDefinitionName	(Optional) Name of the workflow definition. Argument type: String

Arguments

Descriptions

projectName

Name of the project containing the procedure. The project name must be unique among all projects.

Argument type: String

procedureName

Name of the procedure containing the step.

Argument type: String

stepName

Name of the step that calls a subprocedure.

Argument type: String

actualParameterName

The name of the parameter. This name must be unique within the step, and at runtime, it must match the name of a formal parameter in the subprocedure.

Argument type: String

applicationName

(Optional) Name of the application when the actual parameter is on an application process step.

Argument type: String

componentName

(Optional) Name of the component when the actual parameter is on a component process step.

Argument type: String

dashboardName

(Optional) Name of the dashboard.

Argument type: String

flowName

(Optional) Name of the flow.

Argument type: String

flowStateName

(Optional) Name of the flow state.

Argument type: String

processName

(Optional) Name of the process when the actual parameter is on a process step.

Argument type: String

processStepName

(Optional) Name of the process step when if the actual parameter is on a process step.

Argument type: String

releaseName

(Optional) Name of the release if the actual parameter is on a release.

Argument type: String

scheduleName

(Optional) Name of the schedule.

Argument type: String

serviceName

(Optional) Name of the service, if the actual parameter is on a service process step.

Argument type: String

stateDefinitionName

(Optional) Name of the state definition.

Argument type: String

transitionDefinitionName

(Optional) Name of the transition definition.

Argument type: String

value

(Optional) This value is passed to the subprocedure as the value of the matching formal parameter.

Argument type: String

widgetName

(Optional) Name of the widget.

Argument type: String

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

Positional arguments

projectName, procedureName, stepName, actualParameterName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->createActualParameter(<projectName>, <procedureName>, <stepName>,<actualParameterName>, {<optionals>});

Example

$cmdr->createActualParameter("Default", "Take Snapshot", "Retrieve",
  "Source directory", {value => "local"});

ectool

syntax: ectool <projectName> <procedureName> <stepName> <actualParameterName> [optionals]

Example

ectool createActualParameter "Default" "Take Snapshot" "Retrieve"
 "Source directory" --value "local"

createFormalOutputParameter

Creates a new formal output parameter.

You must specify projectName, procedureName, and formalOutputParameterName.

Arguments	Descriptions
projectName	Name of the project. This name must be unique among all projects. Argument Type: String Argument Type: String
formalOutputParameterName	Name for this parameter; used when the procedure is invoked to specify a value for the parameter. Argument type: String
applicationName	(Optional) The name of the application, if the formal output parameter is on an application process. Argument type: String
description	(Optional) Comment text describing this object that is not interpreted at all by CloudBees CD/RO . Argument type: String
pipelineName	(Optional) The name of the pipeline, if the formal output parameter is on a pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. Argument type: String
processName	(Optional) The name of the process, if the formal output parameter is on a process. Argument type: String
releaseName	(Optional) The name of the release, where pipeline is located. Argument type: String
serviceName	(Optional) The name of the service, if the formal output parameter is on an service process. Argument type: String

Arguments

Descriptions

projectName

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

Argument Type: String

formalOutputParameterName

Name for this parameter; used when the procedure is invoked to specify a value for the parameter.

Argument type: String

applicationName

(Optional) The name of the application, if the formal output parameter is on an application process.

Argument type: String

description

(Optional) Comment text describing this object that is not interpreted at all by CloudBees CD/RO .

Argument type: String

pipelineName

(Optional) The name of the pipeline, if the formal output parameter is on a pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure.

Argument type: String

processName

(Optional) The name of the process, if the formal output parameter is on a process.

Argument type: String

releaseName

(Optional) The name of the release, where pipeline is located.

Argument type: String

serviceName

(Optional) The name of the service, if the formal output parameter is on an service process.

Argument type: String

Positional arguments

projectName and formalOutputParameterName.

Response

Returns a formalOutputParameter element.

ec-perl

syntax: $cmdr->createFormalOutputParameter(<projectName> <formalOutputParameterName>, {<optionals>});

Example

$cmdr->createFormalOutputParameter("Sample Project", "Branch Name",
  {procedureName => testProcedure });

ectool

syntax: ectool createFormalOutputParameter <projectName> <formalOutputParameterName> [optionals]

Example

ectool createFormalOutputParameter "Sample Project" "Branch Name"
  --procedureName testProcedure

createFormalParameter

Creates a formal parameter.

You must specify projectName and formalParameterName.

Arguments Descriptions

Arguments	Descriptions
projectName	Name of the project. The project name is unique among all projects. Argument type: String
formalParameterName	The name for the formal parameter. Argument type: String
applicationName	(Optional) Name of the application when the formal parameter is on an application process step. Argument type: String
catalogItemName	(Optional) The name of the catalog item, if the formal parameter is on a catalog item. Argument type: String
catalogName	(Optional) The name of the catalog to which the `catalogItemName` belongs to. Argument type: String
componentName	(Optional) Name of the component when the formal parameter is on a component process step. Argument type: String
dashboardName	(Optional) The name of the dashboard, if the formal parameter is on a dashboard. 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
flowName	(Optional) Name of the flow. Argument type: String
flowStateName	(Optional) Name of the flow state. Argument type: String
gateType	(Optional) The type of the gate: POST or PRE. Argument Type: GateType
orderIndex	(Optional) The display order index starting at 1. Argument type: Integer
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	(Optional) The name of the procedure when the formal parameter is on a procedure.
processName	(Optional) Name of the process when the formal parameter is on a process. Argument type: String
processStepName	(Optional) Name of the process step when the formal parameter is on a process step. Argument type: String
releaseName	(Optional) Name of the release, if the formal parameter is on a release-scoped pipeline. Argument type: String
serviceName	(Optional) Name of the service, if the formal parameter is on a service process.
stageName	(Optional) Name of the stage. Argument type: String
stateDefinitionName	(Optional) Name of the state definition. Argument type: String
stateName	(Optional) Name of a workflow state. Argument type: String
taskName	(Optional) Name of the task. Argument type: String
type	(Optional) For `procedure` and `workflow state definition ` containers: The type can be any string value. This argument is used primarily by the web interface to represent custom form elements. For example, when the type is the credential string value, the server expects a credential as the parameter value. For all other container types, possible types include: `release` —Creates an Release drop down to select an release object. You must also specify `projectFormalParameterName`. See Pipeline object example . `pipeline` —Creates an Pipeline drop down to select an pipeline object. You must also specify `projectFormalParameterName`. See Pipeline object example . `application` —Creates an Application drop down to select an application object. You must also specify `projectFormalParameterName`. See Pipeline object example . `environment` —Creates an Environment drop down to select an environment object. You must also specify `projectFormalParameterName`. See Pipeline object example . `service` —Creates an Microservice drop down to select an microservice object. You must also specify `projectFormalParameterName`. See Pipeline object example . `entry` `textarea` `select` —A dynamic dropdown list. See Dynamic drop-down examples for the ways to supply the list. `radio` `checkbox` `integer` —Specify as an integer value or with a property reference as `$[some-property-path]`. `date` —Rendered with a date chooser to allow the user to select a date value. Specify in ISO 8601 format `yyyy-MM-d` d or with a property reference as `$[some-property-path]`. `credential` `project` `header` —Used to render a heading before one or more parameters. There is no explicit association between the header parameter type and the parameters that it precedes other than relative positioning based on the order index. Argument type: String
workflowDefinitionName	(Optional) Name of the workflow definition. Argument type: String
workflowName	(Optional) Name of a workflow. Argument type: String
Common arguments for all parameter types.
defaultValue	(Optional) This value is used for the formal parameter when a value is not provided. Do not use if `type` = `header`. Argument type: String
dependsOn	Comma-separated list of formal parameters on which this parameter depends to be rendered. See Cascading drop-down with parameter dependencies for an example. Argument type: String, Max length: 255 characters
expansionDeferred	(Optional) < Boolean flag— `0\|1\|true\|false` > If `1` or `true` and the parameter value contains $[], CloudBees CD/RO interprets the parameter literally rather than as a parameter reference. The default is `false`, and the formal parameter is expanded immediately. Do not spsecify if `type` = `header`. Argument type: Boolean
label	(Optional) The display label. If not specified, the formal parameter name is used. Argument type: String
renderCondition	(Optional) Condition for rendering the formal parameter. If render conditions are defined, then `defaultValue` must be specified. Some examples include: `${param1} == 'value1'` `${param1} == 'value1' AND ${param2} == 1` `${param1} != 'value2' OR ${param3} == 'value1'` If left empty, the parameter renders by default. See Conditionally render parameters for an example. Type: String, Max length: 255 characters
required	(Optional) < Boolean flag— `0\|1\|true\|false` > If 1 or `true`, this parameter is required. The procedure will not execute unless a value is given for it. Do not use if `type` = `header`. Argument type: Boolean
validationDSL	(Optional) The DSL script for validating the formal parameter at runtime. This script must return an instance of String, `com.electriccloud.domain.FormalParameterValidationResult, or null.` Do not specify if `type` = `header`. See Validation DSL Examples for more details. Argument type: String, Max length: MAX_VALUE_LENGTH (4000 characters)
Specify the following when `type` = `radio.`
options	(Optional) Ordered list of options
simpleList	(Optional) Pipe-separated list of options. For example, `option1\|option2\|option3.`
optionsFromPropertySheet	(Optional) Path to the property sheet containing the options.
Specify one of the following when* `type` = `select.`
options	(Optional) Ordered list of options.
simpleList	(Optional) Pipe-separated list of options. For example, `option1\|option2\|option3.`
optionsFromPropertySheet	(Optional) Path to the property sheet containing the options.
propertyReference propertyReferenceType	(Optional) `propertyReferenceType` and `propertyReference` must be specified together. `propertyReference` —Type: String, max length is 255 chars `propertyReferenceType` —Type: String, possible values include: `property`, `propertySheet`. Default value is `propertySheet`.
optionsDsl	(Optional) Dsl script for populating drop-down options. The script must return an instance of `com.electriccloud.domain.FormalParameterOptionsResult.` Argument type: String, Max length: MAX_VALUE_LENGTH (4000 characters)
Specify the following when `type` = `checkbox.`
checkedValue uncheckedValue	Checked and unchecked values rendered for the checkbox parameter. These two parameters must be used together. Argument type: String
Specify the following when `type` = release, pipeline, application, environment, or service.
projectFormalParameterName	The `project` parameter used to specify the owning project for this parameter. Applicable only for `release`, `pipeline`, `application`, `service` or `environment` parameter type. See Pipeline object example Argument type: String

projectName

Name of the project. The project name is unique among all projects.

Argument type: String

formalParameterName

The name for the formal parameter.

Argument type: String

applicationName

(Optional) Name of the application when the formal parameter is on an application process step.

Argument type: String

catalogItemName

(Optional) The name of the catalog item, if the formal parameter is on a catalog item.

Argument type: String

catalogName

(Optional) The name of the catalog to which the catalogItemName belongs to.

Argument type: String

componentName

(Optional) Name of the component when the formal parameter is on a component process step.

Argument type: String

dashboardName

(Optional) The name of the dashboard, if the formal parameter is on a dashboard.

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

flowName

(Optional) Name of the flow.

Argument type: String

flowStateName

(Optional) Name of the flow state.

Argument type: String

gateType

(Optional) The type of the gate: POST or PRE.

Argument Type: GateType

orderIndex

(Optional) The display order index starting at 1.

Argument type: Integer

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure when the formal parameter is on a procedure.

processName

(Optional) Name of the process when the formal parameter is on a process.

Argument type: String

processStepName

(Optional) Name of the process step when the formal parameter is on a process step.

Argument type: String

releaseName

(Optional) Name of the release, if the formal parameter is on a release-scoped pipeline.

Argument type: String

serviceName

(Optional) Name of the service, if the formal parameter is on a service process.

stageName

(Optional) Name of the stage.

Argument type: String

stateDefinitionName

(Optional) Name of the state definition.

Argument type: String

stateName

(Optional) Name of a workflow state.

Argument type: String

taskName

(Optional) Name of the task.

Argument type: String

type

(Optional) For procedure and `workflow state definition ` containers: The type can be any string value. This argument is used primarily by the web interface to represent custom form elements. For example, when the type is the credential string value, the server expects a credential as the parameter value.

For all other container types, possible types include:

release —Creates an Release drop down to select an release object. You must also specify projectFormalParameterName. See Pipeline object example .
pipeline —Creates an Pipeline drop down to select an pipeline object. You must also specify projectFormalParameterName. See Pipeline object example .
application —Creates an Application drop down to select an application object. You must also specify projectFormalParameterName. See Pipeline object example .
environment —Creates an Environment drop down to select an environment object. You must also specify projectFormalParameterName. See Pipeline object example .
service —Creates an Microservice drop down to select an microservice object. You must also specify projectFormalParameterName. See Pipeline object example .
entry
textarea
select —A dynamic dropdown list. See Dynamic drop-down examples for the ways to supply the list.
radio
checkbox
integer —Specify as an integer value or with a property reference as $[some-property-path].
date —Rendered with a date chooser to allow the user to select a date value. Specify in ISO 8601 format yyyy-MM-d d or with a property reference as $[some-property-path].
credential
project
header —Used to render a heading before one or more parameters. There is no explicit association between the header parameter type and the parameters that it precedes other than relative positioning based on the order index.

Argument type: String

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

workflowName

(Optional) Name of a workflow.

Argument type: String

Common arguments for all parameter types.

defaultValue

(Optional) This value is used for the formal parameter when a value is not provided.

Do not use if type = header.

Argument type: String

dependsOn

Comma-separated list of formal parameters on which this parameter depends to be rendered. See Cascading drop-down with parameter dependencies for an example.

Argument type: String, Max length: 255 characters

expansionDeferred

(Optional) < Boolean flag— 0|1|true|false > If 1 or true and the parameter value contains $[], CloudBees CD/RO interprets the parameter literally rather than as a parameter reference.

The default is false, and the formal parameter is expanded immediately.

Do not spsecify if type = header.

Argument type: Boolean

label

(Optional) The display label. If not specified, the formal parameter name is used.

Argument type: String

renderCondition

(Optional) Condition for rendering the formal parameter. If render conditions are defined, then defaultValue must be specified. Some examples include:

${param1} == 'value1' ${param1} == 'value1' AND ${param2} == 1 ${param1} != 'value2' OR ${param3} == 'value1'

If left empty, the parameter renders by default. See Conditionally render parameters for an example.

Type: String, Max length: 255 characters

required

(Optional) < Boolean flag— 0|1|true|false > If 1 or true, this parameter is required. The procedure will not execute unless a value is given for it.

Do not use if type = header.

Argument type: Boolean

validationDSL

(Optional) The DSL script for validating the formal parameter at runtime. This script must return an instance of String, com.electriccloud.domain.FormalParameterValidationResult, or null.

Do not specify if type = header. See Validation DSL Examples for more details.

Argument type: String, Max length: MAX_VALUE_LENGTH (4000 characters)

Specify the following when type = radio.

options

(Optional) Ordered list of options

simpleList

(Optional) Pipe-separated list of options. For example, option1|option2|option3.

optionsFromPropertySheet

(Optional) Path to the property sheet containing the options.

Specify one of the following when* type = select.

options

(Optional) Ordered list of options.

simpleList

(Optional) Pipe-separated list of options. For example, option1|option2|option3.

optionsFromPropertySheet

(Optional) Path to the property sheet containing the options.

propertyReference

propertyReferenceType

(Optional) propertyReferenceType and propertyReference must be specified together.

propertyReference —Type: String, max length is 255 chars
propertyReferenceType —Type: String, possible values include: property, propertySheet. Default value is propertySheet.

optionsDsl

(Optional) Dsl script for populating drop-down options. The script must return an instance of com.electriccloud.domain.FormalParameterOptionsResult.

Argument type: String, Max length: MAX_VALUE_LENGTH (4000 characters)

Specify the following when type = checkbox.

checkedValue

uncheckedValue

Checked and unchecked values rendered for the checkbox parameter. These two parameters must be used together.

Argument type: String

Specify the following when type = release, pipeline, application, environment, or service.

projectFormalParameterName

The project parameter used to specify the owning project for this parameter. Applicable only for release, pipeline, application, service or environment parameter type. See Pipeline object example

Argument type: String

Positional arguments

In CloudBees CD/RO 5.0 and later, projectName and formalParameterName.

In releases earlier tha CloudBees CD/RO 5.0, projectName, procedureName, and formalParameterName.

For workflow state parameters: projectName, formalParameterName, workflowDefinitionName and stateDefinitionName

Response

Returns a formalParameter object with contents of the newly created formal parameter.

=== Validation DSL Examples

Basic validation

Custom validation logic can be applied to a parameter using a DSL script that is registered with the parameter. Here is a basic example of a DSL script that allows the user to only enter test1 ` or `test2 ` as a value in the text entry field for the parameter `paramName1.

if (args.parameters['paramName1'] != 'test1' && args.parameters['paramName1'] != 'test2') {
  // return an appropriate error message in case the validation failed
  return "'paramName1' parameter value is not valid"

} else {
  // an empty or null response is construed as a validation success
  return null
}

Validation with parameter dependencies

Here is another example where the validation for the parameter state depends on another parameter country. In the sample script below, that is registered with parameter state if the parameter country has value US, then the user is allowed to only enter either CA or CO as a value for the state parameter. If the parameter country has value Canada, then the user is allowed to only enter either ON or BC as a value for the state parameter.

Note: for custom validation that depends on another parameter, you also need to declare a dependency on the formal parameter on which the validation logic depends. So in this example, parameter state must declare that it depends on parameter country by adding it to its dependencies with the dependsOn argument.

// Get the formal parameter that the validation logic
// for the parameter 'state' depends on.
def selectedCountry = args.parameters['country']

def valid = true
if (selectedCountry == 'US') {
  if (args.parameters['state'] != 'CA' &&
      args.parameters['state'] != 'CO') {

    valid = false

  }
} else if (selectedCountry == 'Canada') {
  if (args.parameters['state'] != 'BC' &&
      args.parameters['state'] != 'ON') {

    valid = false
  }
}

if (!valid) {
  // Return an appropriate error message since
  // the validation failed
  return "'state' parameter value is not valid"
}

=== Conditionally render parameters

In this example, if the user checks the Use Existing Project checkbox, then the user is expected to provide a value for Existing Project. The user is not expected to provide a value for New Project Name as it would not be relevant.

Conversely if the user leaves the checkbox unchecked, then the user is expected to provide a value for New Project Name. The user is not expected to provide a value for Existing Project in this case.

pipeline 'Test', {
  projectName = 'Default'

  formalParameter 'Use Existing Project', {
    type = 'checkbox'
    checkedValue = 'true'
    uncheckedValue = 'false'
  }

  formalParameter 'Existing Project', {
    type = 'project'
    renderCondition = '${Use Existing Project} == \'true\''
  }

  formalParameter 'New Project Name', {
    type = 'entry'
    renderCondition = '${Use Existing Project} == \'false\''
  }
}

=== Pipeline object example

If the user selects a parameter of type release, pipeline, application, environment, or service the user must also specify the owning project for the object. The example below shows how to define a parameter of type application along with its prerequisite owning project parameter.

pipeline 'Test', {

  projectName = 'Default'
  formalParameter 'projectParam', defaultValue: null, {
    expansionDeferred = '0'
    label = 'Project to Use'
    orderIndex = '1'
    required = '0'
    type = 'project'
  }
  formalParameter 'appParam', defaultValue: null, {
    expansionDeferred = '0'
    label = 'Select Application'
    orderIndex = '2'
    projectFormalParameterName = 'projectParam'
    required = '0'
    type = 'application'
  }
}

=== Dynamic drop-down examples

Simple drop-down

A parameter of type drop-down, for example select, can display dynamic options using a DSL script registered with the parameter. Here is an example of a DSL script that displays a filtered list of CloudBees CD/RO projects that have a property customFlagÏ set to 5 as options in the drop-down.

def options = []

// The parameter and the procedure for which we are retrieving the options
// may be accessed as follows if needed:
def parameterName = args.formalParameterName
def procedureName = args.procedureName

// Get all projects and loop over the list considering only those that
// have the property 'customFlag' defined and set to '5'.

def projects = getProjects()

projects.each { p ->
  // Check if the custom property is set on the project
  // and that its value is equal to '5'. If so, add the
  // project as the options result.
  // DSL tip: The groovy Elvis operator can be used
  // to do an existence check and then get a property
  // value if the property exists like this.
  if(p.customFlag?.value == '5') {

      // Add the project name to the options list.
      // The projects will be displayed in the order
      // in which they are added to the list.
      // Sort the options list before returning to
      // display them in a sorted order.
    options<< p.projectName
  }
}

// Finally return the options list
// 'return' is not needed in groovy. The response of the last
// statement is returned automatically
options.sort()

Cascading drop-down with parameter dependencies

Here is another example that builds on our previous example to create cascading dynamic drop-downs.

Start by defining a drop-down select parameter named ProjectParam that displays dynamic options as described in the earlier example.

Add a second drop-down select parameter type called AppParam. Register the sample script below as the DSL to use for the drop-down options for this parameter. The script returns the list of applications belonging to the selected project from the ProjectParam parameter. So, anytime the selected project is changed for the parameter ProjectParam by the user, the available applications listed as options in AppParam also change based on the project.

Note: for cascading drop-downs, you also need to declare a dependency on the formal parameter that the second drop-down depends on. So in this example, parameter AppParam must declare that it depends on parameter ProjectParam by adding it to its dependencies.

def options = []

// 'AppParam' parameter is dependent on 'ProjectParam' parameter.
// Note that this dependency is declared in the form.xml (see the subsequent steps for details)

// The parameter that this DSL script's parameter ('AppParam') is dependent on
// can be accessed like this:
def selectedProjectName = args.parameters['ProjectParam']

// If no project is selected then no apps to get
if (selectedProjectName) {
    def applications = getApplications(projectName: selectedProjectName)
    applications.each {
       options << it.applicationName
    }
}

// Finally return the options list
// 'return' is not needed in groovy. The response of the last
// statement is returned automatically
options

Returning the options to display

The DSL script can return the options to display as either an ordered list (as shown in the examples above), a map, or as a custom list using an instance of type FormalParameterOptionsResult.

Ordered list : The values in the list are used as display text as well as the actual parameter value to return for the option if selected. The options are displayed in the order of the values present in the list.

Map : The key in the map entry is used as the actual parameter value while the value in the map entry is used as the display text for the option. Here is a DSL script sample that returns options as a map. The options are displayed alphabetically based on the display text.

//Initialize options as a map
def options = [:]

def projects = getProjects()

projects.each { p ->
  if(p.customFlag?.value == '5') {

    options << [/*value*/(p.projectName): /*display text*/ p.projectName]
  }
}

options

Custom list: FormalParameterOptionsResult is used to customize both the display text and order of the options: used when options need to be displayed in a particular order and the display text and value for the options are different. Here is a DSL script sample that returns options as an instance of FormalParameterOptionsResult. The options are displayed in the order in which they were added.

def options = new FormalParameterOptionsResult()

def projects = getProjects()

projects.each { p ->
  if(p.customFlag?.value == '5') {

    // The first argument is
    // value: the actual parameter value to return
    //        for the option if selected
      // The second argument is
    // text: the text to display in the drop-down
    //        for the option

    options.add(p.projectName, p.projectName)
  }
}

options

ec-perl

syntax: $cmdr->createFormalParameter(<projectName>, <formalParameterName>, {<optionals>});

The following syntax is still supported for backward compatibility with releases earlier tha CloudBees CD/RO 5.0, you can also enter:

syntax: $cmdr->createFormalParameter(<projectName>, <procedureName>, <formalParameterName>, {<optionals>});

Example

$cmdr->createFormalParameter("Sample Project", "Branch Name",
  {required => 1 });

ectool

For procedure parameters:

syntax: ectool createFormalParameter <projectName> <formalParameterName> [optionals]

For backward compatibility with releases earlier tha CloudBees CD/RO 5.0, you can also enter:

syntax: ectool createFormalParameter <projectName> <procedureName> <formalParameterName> [optionals]

Example

ectool createFormalParameter "Sample Project" "Branch Name" --required 1

For pipeline parameters:

syntax: ectool createFormalParameter --formalParameterName <name> --projectName <name> --pipelineName <name>

Example

ectool createFormalParameter --formalParameterName "Active users"
  --projectName "CD" --pipelineName "CD Ppieline"

Example using parameters to create a check box

ectool createFormalParameter --projectName $projectName
  --pipelineName $pipelineName
  --formalParameterName $parameter_name
  --type "checkbox" --defaultValue "true" --checkedValue true
  --uncheckedValue false

Example using parameters for conditional rendering

ectool createPipeline 'Default' 'Test'

ectool createFormalParameter 'Default' 'Use Existing Project' --pipelineName Test --type checkbox
                              --checkedValue 'true' --uncheckedValue = 'false'

ectool createFormalParameter 'Default' 'Existing Project' --pipelineName Test --type project
                              --renderCondition "${Use Existing Project} == 'true'"

ectool createFormalParameter 'Default' 'New Project Name' --pipelineName Test --type project
                              --renderCondition "${Use Existing Project} == 'false'"

deleteActualParameter

Deletes an actual parameter.

You must specify a projectName, procedureName, stepName, and actualParameterName.

Arguments	Descriptions
projectName	Name of the project that contains this actual parameter. The name must be unique among all projects. Argument type: String
procedureName	Name of the procedure that contains the step with this parameter. Argument type: String
stepName	Name of the step that contains the actual parameter. Argument type: String
actualParameterName	Name of the actual parameter to delete. Argument type: String
applicationName	(Optional) Name of the application when the actual parameter is on an application process step. Argument type: String
componentName	(Optional) Name of the component when the actual parameter is on a component process step. Argument type: String
dashboardName	(Optional) The name of the dashboard. Argument type: String
processName	(Optional) Name of the process when the actual parameter is on a process step. Argument type: String
processStepName	(Optional) Name of the process step when the actual parameter is on a process step. Argument type: String
releaseName	(Optional) Name of the release if the actual parameter is used in a release. Argument type: String
scheduleName	(Optional) Name of the schedule containing the actual parameter. Argument type: String
serviceName	Name of the service, if the actual parameter is on a service process step.
stateDefinitionName	(Optional) Name of the state definition. Argument type: String
transitionDefinitionName	(Optional) Name of the transition definition. Argument type: String
widgetName	(Optional) The name of the widget. Argument type: String
workflowDefinitionName	(Optional) Name of the workflow definition. Argument type: String

Arguments

Descriptions

projectName

Name of the project that contains this actual parameter. The name must be unique among all projects.

Argument type: String

procedureName

Name of the procedure that contains the step with this parameter.

Argument type: String

stepName

Name of the step that contains the actual parameter.

Argument type: String

actualParameterName

Name of the actual parameter to delete.

Argument type: String

applicationName

(Optional) Name of the application when the actual parameter is on an application process step.

Argument type: String

componentName

(Optional) Name of the component when the actual parameter is on a component process step.

Argument type: String

dashboardName

(Optional) The name of the dashboard.

Argument type: String

processName

(Optional) Name of the process when the actual parameter is on a process step.

Argument type: String

processStepName

(Optional) Name of the process step when the actual parameter is on a process step.

Argument type: String

releaseName

(Optional) Name of the release if the actual parameter is used in a release.

Argument type: String

scheduleName

(Optional) Name of the schedule containing the actual parameter.

Argument type: String

serviceName

Name of the service, if the actual parameter is on a service process step.

stateDefinitionName

(Optional) Name of the state definition.

Argument type: String

transitionDefinitionName

(Optional) Name of the transition definition.

Argument type: String

widgetName

(Optional) The name of the widget.

Argument type: String

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

Positional arguments

projectName, procedureName, stepName, actualParameterName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteActualParameter(<projectName>, <procedureName>, <stepName>, <actualParameterName> , {<optionals>});

Example

$cmdr->deleteActualParameter('Default', 'CallSub', 'Take snapshot',
  'Snapshot Version');

ectool

syntax: ectool deleteActualParameter <projectName> <procedureName> <stepName> <actualParameterName> [optionals]

Example

ectool deleteActualParameter "Default" "CallSub" "Take snapshot"
  "Snapshot Version"

deleteFormalOutputParameter

Deletes a formal output parameter.

You must specify projectName, procedureName, and formalOutputParameterName.

Arguments	Descriptions
projectName	Name of the project. This name must be unique among all projects. Argument Type: String Argument Type: String
formalOutputParameterName	Name for this parameter; used when the procedure is invoked to specify a value for the parameter. Argument type: String
applicationName	(Optional) The name of the application, if the formal output parameter is on an application process. Argument type: String
pipelineName	(Optional) The name of the pipeline, if the formal output parameter is on a pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. Argument type: String
processName	(Optional) The name of the process, if the formal output parameter is on a process. Argument type: String
releaseName	(Optional) The name of the release, where pipeline is located. Argument type: String
serviceName	(Optional) The name of the service, if the formal output parameter is on an service process. Argument type: String

Arguments

Descriptions

projectName

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

Argument Type: String

formalOutputParameterName

Name for this parameter; used when the procedure is invoked to specify a value for the parameter.

Argument type: String

applicationName

(Optional) The name of the application, if the formal output parameter is on an application process.

Argument type: String

pipelineName

(Optional) The name of the pipeline, if the formal output parameter is on a pipeline. Argument type: String

procedureName

(Optional) The name of the procedure.

Argument type: String

processName

(Optional) The name of the process, if the formal output parameter is on a process.

Argument type: String

releaseName

(Optional) The name of the release, where pipeline is located.

Argument type: String

serviceName

(Optional) The name of the service, if the formal output parameter is on an service process.

Argument type: String

Positional arguments

projectName and formalOutputParameterName.

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteFormalOutputParameter(<projectName>, <formalOutputParameterName>, {<optionals>});

Example

$cmdr->deleteFormalOutputParameter("Default", "Build Version",
  {pipelineName => "Q1 summary"});

ectool

syntax: ectool deleteFormalOutputParameter <projectName> <formalOutputParameterName> [optionals]

Example

ectool deleteFormalOutputParameter "Default" "Build Version"
  --pipelineName "Q1 summary"

deleteFormalParameter

Deletes a formal parameter and any addition property that was created by createFormalParameter or modifyFormalParameter.

You must specify projectName and formalParameterName.

Arguments	Descriptions
projectName	Name of the project that contains the procedure or parameter to delete. The name must be unique among all projects. Argument type: String
formalParameterName	Name of the formal parameter to delete. Argument type: String
applicationName	(Optional) Name of the application when the formal parameter is on an application process step. Argument type: String
catalogName	(Optional) The name of the catalog to which the catalog item belongs to. Argument type: String
catalogItemName	(Optional) The name of the catalog item, if the formal parameter is on a catalog item. Argument type: String
componentName	(Optional) Name of the component when the formal parameter is on a component process step. Argument type: String
dashboardName	(Optional) The name of the dashboard, if the formal parameter is on a dashboard. Argument type: String
flowName	(Optional) Name of the flow. Argument type: String
flowStateName	(Optional) Name of the flow state. Argument type: String
gateType	(Optional) The type of the gate: POST or PRE. Argument Type: GateType
pipelineName	(Optional) The name of the pipeline. Argument type: String
processName	(Optional) Name of the process when the formal parameter is on a process. Argument type: String
processStepName	(Optional) Name of the process step when the formal parameter is on a process step. Argument type: String
releaseName	(Optional) Name of the release, if the formal parameter is on a release-scoped pipeline. Argument type: String
serviceName	(Optional) Name of the service, if the formal parameter is on a service process.
stageName	(Optional) Name of the stage. Argument type: String
stateDefinitionName	(Optional) Name of the state definition. Argument type: String
stateName	(Optional) Name of the workflow state. Argument type: String
taskName	(Optional) Name of the task. Argument type: String
workflowDefinitionName	(Optional) Name of the workflow definition. Argument type: String
workflowName	(Optional) Name of a workflow. Argument type: String

Arguments

Descriptions

projectName

Name of the project that contains the procedure or parameter to delete. The name must be unique among all projects.

Argument type: String

formalParameterName

Name of the formal parameter to delete.

Argument type: String

applicationName

(Optional) Name of the application when the formal parameter is on an application process step.

Argument type: String

catalogName

(Optional) The name of the catalog to which the catalog item belongs to.

Argument type: String

catalogItemName

(Optional) The name of the catalog item, if the formal parameter is on a catalog item.

Argument type: String

componentName

(Optional) Name of the component when the formal parameter is on a component process step.

Argument type: String

dashboardName

(Optional) The name of the dashboard, if the formal parameter is on a dashboard.

Argument type: String

flowName

(Optional) Name of the flow.

Argument type: String

flowStateName

(Optional) Name of the flow state.

Argument type: String

gateType

(Optional) The type of the gate: POST or PRE.

Argument Type: GateType

pipelineName

(Optional) The name of the pipeline.

Argument type: String

processName

(Optional) Name of the process when the formal parameter is on a process.

Argument type: String

processStepName

(Optional) Name of the process step when the formal parameter is on a process step.

Argument type: String

releaseName

(Optional) Name of the release, if the formal parameter is on a release-scoped pipeline.

Argument type: String

serviceName

(Optional) Name of the service, if the formal parameter is on a service process.

stageName

(Optional) Name of the stage.

Argument type: String

stateDefinitionName

(Optional) Name of the state definition.

Argument type: String

stateName

(Optional) Name of the workflow state.

Argument type: String

taskName

(Optional) Name of the task.

Argument type: String

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

workflowName

(Optional) Name of a workflow.

Argument type: String

Positional arguments

In CloudBees CD/RO 5.0 and later, projectName and formalParameterName. In releases earlier tha CloudBees CD/RO 5.0, projectName, procedureName, and formalParameterName.

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteFormalParameter(<projectName>, <formalParameterName>, {<optionals>});

Example

$cmdr->deleteFormalParameter("Default", "Build Version",
  {pipelineName => "Q1 summary"});

Example

$cmdr->deleteFormalParameter("Default", "QE testing", "Build Version");

ectool

syntax: ectool deleteFormalParameter <projectName> <formalParameterName> [optionals]

Example

ectool deleteFormalParameter "Default" "Build Version" --pipelineName
 "Q1 summary"

Example

ectool deleteFormalParameter "Default" "QE testing" "Build Version"

detachParameter

Detaches a formal parameter from a step.

You must specify projectName and formalParameterName.

Arguments	Descriptions
projectName	Name of the project that contains this parameter. The name must be unique among all projects. Argument type: String
formalParameterName	Name of the formal parameter to detach. Argument type: String
stepName	(Optional) Name of the step where this parameter is currently attached. Argument type: String
applicationName	(Optional) Name of the application. Argument type: String
componentApplicationName	(Optional) Name of the component in the application. Argument type: String
componentName	(Optional) Name of the component. Argument type: String
gateType	(Optional) The type of the gate. Argument type: GateType
pipelineName	(Optional) Name of the pipeline. Argument type: String
processName	(Optional) Name of the process that contains this parameter. Argument type: String
processStepName	(Optional) Name of the step in the process.. Argument type: String
releaseName	(Optional) Name of the release. Argument Type: String
serviceName	(Optional) The name of the service. Argument type: String
stageName	(Optional) Name of the stage. Argument type: String
stateDefinitionName	(Optional)Name of the state definition. Argument type: String
taskName	(Optional) Name of the task. Argument type: String
workflowDefinitionName	(Optional) Name of the workflow definition. Argument type: String

Arguments

Descriptions

projectName

Name of the project that contains this parameter. The name must be unique among all projects.

Argument type: String

formalParameterName

Name of the formal parameter to detach.

Argument type: String

stepName

(Optional) Name of the step where this parameter is currently attached.

Argument type: String

applicationName

(Optional) Name of the application.

Argument type: String

componentApplicationName

(Optional) Name of the component in the application.

Argument type: String

componentName

(Optional) Name of the component.

Argument type: String

gateType

(Optional) The type of the gate.

Argument type: GateType

pipelineName

(Optional) Name of the pipeline.

Argument type: String

processName

(Optional) Name of the process that contains this parameter.

Argument type: String

processStepName

(Optional) Name of the step in the process..

Argument type: String

releaseName

(Optional) Name of the release.

Argument Type: String

serviceName

(Optional) The name of the service.

Argument type: String

stageName

(Optional) Name of the stage.

Argument type: String

stateDefinitionName

(Optional)Name of the state definition.

Argument type: String

taskName

(Optional) Name of the task.

Argument type: String

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

Positional arguments

projectName, procedureName, stepName, formalParameterName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->detachParameter(<projectName>, <procedureName>, <stepName>, <formalParameterName>, {<optionals>});

Example

$cmdr-> detachParameter("Default", "Run Build", "Get Sources",
  "SCM Credential");

ectool

syntax: ectool detachParameter <projectName> <procedureName> <stepName> <formalParameterName> [optionals]

Example

ectool detachParameter "Default" "Run Build" "Get Sources"
  "SCM Credential"

getActualParameter

Retrieves an actual parameter by its name. For more information about parameters, click here .

You must specify an actualParameterName. include::partial$get-actual-parameter-syntax.adoc[]

Arguments Descriptions

Arguments	Descriptions
actualParameterName	Name of the actual parameter. Argument type: String
applicationEntityRevisionId	(Optional) The revision ID of the versioned object. Argument type: UUID
applicationName	(Optional)Name of the application when the actual parameter is on an application process step. The name must be unique among all projects. Argument type: String
componentName	(Optional)Name of the component when the actual parameter is on a component process step. 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
flowRuntimeStateId	(Optional) The ID of the flow runtime state. Argument Type: UUID
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	(Optional) Name of the flow transition that must be unique within the flow state. Argument Type: String
jobId	(Optional) include::partial$job-id.adoc[] Argument type: UUID
jobStepId	(Optional) The unique identifier for a job step that is assigned automatically when the job step is created. You enter this argument to query a subprocedure call to the job step’s parameter. Argument type: UUID
procedureName	(Optional) Name of the procedure when the actual parameter is on a procedure step. If you need actual parameters on a step, the `projectName`, `procedureName`, and `stepName` arguments must be used together to specify the step. Argument type: String
processName	(Optional) Name of the process when the actual parameter is on a process step. Argument type: String
processStepName	(Optional) Name of the process step when the actual parameter is on a process step. Argument type: String
projectName	(Optional) Name of the project to query for the parameter on a schedule or procedure step. If you need actual parameters on a step, the `projectName`, `procedureName`, and `stepName` arguments must be used together to specify the step. Argument type: String
releaseName	(Optional) Name of the release if the actual parameter is on it. Argument type: String
scheduleName	(Optional) Name of the schedule to query for the parameter on a schedule. Argument type: String
serviceClusterMappingName	(Optional) Name of the service cluster mapping. Argument type: String
serviceName	(Optional) Name of the service, if the actual parameter is on a service process step. Argument type: String
stateDefinitionName	(Optional) Name of the workflow state definition. Argument type: String
stateName	(Optional) Name of the workflow state. Argument type: String
stepName	(Optional) Name of the step to query for the parameter on the step. Argument type: String
transitionDefinitionName	(Optional) Name of the workflow transition definition. Argument type: String
transitionName	(Optional) Name of the workflow transition. Argument type: String
workflowDefinitionName	(Optional) Name of the workflow definition. Argument type: String
workflowName	(Optional) Name of the workflow. Argument type: String

actualParameterName

Name of the actual parameter.

Argument type: String

applicationEntityRevisionId

(Optional) The revision ID of the versioned object.

Argument type: UUID

applicationName

(Optional)Name of the application when the actual parameter is on an application process step. The name must be unique among all projects.

Argument type: String

componentName

(Optional)Name of the component when the actual parameter is on a component process step.

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

flowRuntimeStateId

(Optional) The ID of the flow runtime state.

Argument Type: UUID

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

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

Argument Type: String

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

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

You enter this argument to query a subprocedure call to the job step’s parameter.

Argument type: UUID

procedureName

(Optional) Name of the procedure when the actual parameter is on a procedure step.

If you need actual parameters on a step, the projectName, procedureName, and stepName arguments must be used together to specify the step.

Argument type: String

processName

(Optional) Name of the process when the actual parameter is on a process step.

Argument type: String

processStepName

(Optional) Name of the process step when the actual parameter is on a process step.

Argument type: String

projectName

(Optional) Name of the project to query for the parameter on a schedule or procedure step.

If you need actual parameters on a step, the projectName, procedureName, and stepName arguments must be used together to specify the step.

Argument type: String

releaseName

(Optional) Name of the release if the actual parameter is on it.

Argument type: String

scheduleName

(Optional) Name of the schedule to query for the parameter on a schedule.

Argument type: String

serviceClusterMappingName

(Optional) Name of the service cluster mapping.

Argument type: String

serviceName

(Optional) Name of the service, if the actual parameter is on a service process step.

Argument type: String

stateDefinitionName

(Optional) Name of the workflow state definition.

Argument type: String

stateName

(Optional) Name of the workflow state.

Argument type: String

stepName

(Optional) Name of the step to query for the parameter on the step.

Argument type: String

transitionDefinitionName

(Optional) Name of the workflow transition definition.

Argument type: String

transitionName

(Optional) Name of the workflow transition.

Argument type: String

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

workflowName

(Optional) Name of the workflow.

Argument type: String

Positional arguments

actualParameterName

Response

One actualParameter element.

ec-perl

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

Example

$cmdr->getActualParameter("Extra Parameter",
    {"projectName" => "Sample Project",
   "procedureName" => "CallSub",
        "stepName" => "Step1"});

ectool

syntax: ectool getActualParameter <actualParameterName> [optionals]

Example

getActualParameter "Extra Parameter" --projectName "Sample Project"
  --procedureName "CallSub" --stepName "Step1"

getActualParameters

Retrieves all actual parameters from a job, step, schedule, state, or transition. For more information about parameters, click here .

You must specify object locators to find the parameter. include::partial$get-actual-parameters-syntax.adoc[]

Arguments Descriptions

Arguments	Descriptions
applicationEntityRevisionId	(Optional) The revision ID of the versioned object. Argument type: UUID
applicationName	(Optional) Name of the application when the actual parameters are on an application process step. The name must be unique among all projects. Argument type: String
componentName	(Optional) Name of the component when the actual parameters are on a component process step. Argument type: String
dashboardName	(Optional) The name of the dashboard. 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
flowRuntimeStateId	(Optional) The ID of the flow runtime state. Argument Type: UUID
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
jobId	(Optional) include::partial$job-id.adoc[] 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
procedureName	(Optional) Name of the procedure containing the parameters. To find parameters on a step, you must use `projectName`, `procedureName`, and `stepName` to specify the step. Argument type: String
processName	(Optional) Name of the process when the actual parameters are on a process step. Argument type: String
processStepName	(Optional) Name of the process step when the actual parameters are on a process step. Argument type: String
projectName	(Optional) Name of the project containing the parameters. To find parameters on a step, you must use `projectName`, `procedureName`, and `stepName` to specify the step. Argument type: String
releaseName	(Optional) Name of the release if the actual parameter is on it. Argument type: String
scheduleName	(Optional) Name of the schedule containing parameters. Argument type: String
serviceName	Name of the service, if the actual parameter is on a service process step.
stateDefinitionName	(Optional) Name of the workflow state definition. Argument type: String
stateName	(Optional) Name of the workflow state. Argument type: String
stepName	(Optional) Name of the step containing parameters. To find parameters on a step, you must use `projectName`, `procedureName`, and `stepName` to specify the step. Argument type: String
transitionDefinitionName	(Optional) Name of the workflow transition definition. Argument type: String
transitionName	(Optional) Name of the workflow transition. Argument type: String
widgetName	(Optional) The name of a widget. Argument type: String
workflowDefinitionName	(Optional) Name of the workflow definition. Argument type: String
workflowName	(Optional) Name of the workflow. Argument type: String

applicationEntityRevisionId

(Optional) The revision ID of the versioned object.

Argument type: UUID

applicationName

(Optional) Name of the application when the actual parameters are on an application process step. The name must be unique among all projects.

Argument type: String

componentName

(Optional) Name of the component when the actual parameters are on a component process step.

Argument type: String

dashboardName

(Optional) The name of the dashboard.

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

flowRuntimeStateId

(Optional) The ID of the flow runtime state.

Argument Type: UUID

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

jobId

(Optional) include::partial$job-id.adoc[]

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

procedureName

(Optional) Name of the procedure containing the parameters.

To find parameters on a step, you must use projectName, procedureName, and stepName to specify the step.

Argument type: String

processName

(Optional) Name of the process when the actual parameters are on a process step.

Argument type: String

processStepName

(Optional) Name of the process step when the actual parameters are on a process step.

Argument type: String

projectName

(Optional) Name of the project containing the parameters.

To find parameters on a step, you must use projectName, procedureName, and stepName to specify the step.

Argument type: String

releaseName

(Optional) Name of the release if the actual parameter is on it.

Argument type: String

scheduleName

(Optional) Name of the schedule containing parameters.

Argument type: String

serviceName

Name of the service, if the actual parameter is on a service process step.

stateDefinitionName

(Optional) Name of the workflow state definition.

Argument type: String

stateName

(Optional) Name of the workflow state.

Argument type: String

stepName

(Optional) Name of the step containing parameters.

To find parameters on a step, you must use projectName, procedureName, and stepName to specify the step.

Argument type: String

transitionDefinitionName

(Optional) Name of the workflow transition definition.

Argument type: String

transitionName

(Optional) Name of the workflow transition.

Argument type: String

widgetName

(Optional) The name of a widget.

Argument type: String

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

workflowName

(Optional) Name of the workflow.

Argument type: String

Positional arguments

Arguments to locate the parameter, beginning with the top-level object locator.

Response

Zero or more actualParameter elements.

ec-perl

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

Example

$cmdr-> getActualParameters({"projectName" => "Sample Project",
  "procedureName" => "CallSub",
       "stepName" => "Step1"});

ectool

syntax: ectool getActualParameters [optionals]

Example

ectool getActualParameters --projectName "Sample Project"
  --procedureName "CallSub" --stepName "Step1"

getFormalOutputParameter

Gets a formal output parameter by name.

You must specify projectName and formalOutputParameterName.

Arguments	Descriptions
projectName	Name of the project. This name must be unique among all projects. Argument Type: String Argument Type: String
formalOutputParameterName	Name for this parameter; used when the procedure is invoked to specify a value for the parameter. Argument type: String
applicationName	(Optional) The name of the application, if the formal output parameter is on an application process. Argument type: String
pipelineName	(Optional) The name of the pipeline, if the formal output parameter is on a pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. Argument type: String
processName	(Optional) The name of the process, if the formal output parameter is on a process. Argument type: String
releaseName	(Optional) The name of the release, where pipeline is located. Argument type: String
serviceName	(Optional) The name of the service, if the formal output parameter is on an service process. Argument type: String

Arguments

Descriptions

projectName

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

Argument Type: String

formalOutputParameterName

Name for this parameter; used when the procedure is invoked to specify a value for the parameter.

Argument type: String

applicationName

(Optional) The name of the application, if the formal output parameter is on an application process.

Argument type: String

pipelineName

(Optional) The name of the pipeline, if the formal output parameter is on a pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure.

Argument type: String

processName

(Optional) The name of the process, if the formal output parameter is on a process.

Argument type: String

releaseName

(Optional) The name of the release, where pipeline is located.

Argument type: String

serviceName

(Optional) The name of the service, if the formal output parameter is on an service process.

Argument type: String

Positional arguments

projectName and formalOutputParameterName.

Response

One formalOutputParameter element.

ec-perl

            syntax:
            $cmdr\->getFormalOutputParameter(<projectName>,
  <formalOutputParameterName>, {<optionals>});

[source,shell]

Example

$cmdr->getFormalOutputParameter("Default", "Test Case");

ectool

syntax: ectool getFormalOutputParameter <projectName> <formalOutputParameterName> [optionals]

Example

ectool getFormalOutputParameter "Default" "Test Case"

getFormalOutputParameters

Gets all formal output parameters from an output parameter container.

You must specify locator arguments to identify a procedure, schedule, or subprocedure step.

Arguments	Descriptions
projectName	Name of the project. This name must be unique among all projects. Argument Type: String Argument Type: String
applicationName	(Optional) The name of the application, if the formal output parameter is on an application process. Argument type: String
pipelineName	(Optional) The name of the pipeline, if the formal output parameter is on a pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. Argument type: String
processName	(Optional) The name of the process, if the formal output parameter is on a process. Argument type: String
releaseName	(Optional) The name of the release, where pipeline is located. Argument type: String
serviceName	(Optional) The name of the service, if the formal output parameter is on an service process. Argument type: String

Arguments

Descriptions

projectName

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

Argument Type: String

applicationName

(Optional) The name of the application, if the formal output parameter is on an application process.

Argument type: String

pipelineName

(Optional) The name of the pipeline, if the formal output parameter is on a pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure.

Argument type: String

processName

(Optional) The name of the process, if the formal output parameter is on a process.

Argument type: String

releaseName

(Optional) The name of the release, where pipeline is located.

Argument type: String

serviceName

(Optional) The name of the service, if the formal output parameter is on an service process.

Argument type: String

Positional arguments

projectName and arguments to locate the formal output parameter, beginning with the top-level object locator.

Response

An XML stream containing zero or more formalOutputParameter elements.

ec-perl

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

Example

$cmdr->getFormalOutputParameters("QA Test", {procedureName => "Build"});

ectool

syntax: ectool getFormalOutputParameters <projectName> [optionals]

Example

getFormalOutputParameters "QA Test" --procedureName "Build"

getFormalParameter

Retrieves a formal parameter by its name.

You must specify projectName and formalParameterName.

Arguments Descriptions

Arguments	Descriptions
projectName	Name of the project containing the procedure. The name must be unique among all projects. Argument type: String
formalParameterName	The name for the formal parameter that is used when the procedure is invoked to specify a value for the parameter. Argument type: String
In addition to the above required arguments, specify one or more of the following to locate the formal parameter container, beginning with the top-level object locator.
applicationEntityRevisionId	(Optional) The revision ID of the versioned object. Argument type: UUID
applicationName	(Optional) Name of the application when the formal parameter is on an application process step. Argument type: String
catalogName	(Optional) Name of the catalog when the formal parameter is on a catalog item. Argument type: String
componentName	(Optional) Name of the component when the formal parameter is on a component process step. Argument type: String
dashboardName	(Optional) The name of the dashboard, if the formal parameter is on a dashboard. Argument Type: String
flowName	(Optional) Name of the flow that must be unique within the project. Argument Type: String
flowStateName	(Optional) Name of the flow state that must be unique within the flow. Argument Type: String
gateType	(Optional) The type of the gate: POST or PRE. Argument Type: String
includeDetails	(Optional)< Boolean flag— `0\|1\|true\|false` > If `1` or `true`, return additional details in the `ec_customeEditorData` property sheet associated with the requested formal parameter. Default is `false`. Argument type: boolean
pipelineName	(Optional) Name of the pipeline when the formal parameter is on a pipeline. Argument type: String
processName	(Optional) Name of the process when the formal parameter is on a process step. Argument type: String
processStepName	(Optional) Name of the process step when the formal parameter is on a process step. Argument type: String
procedureName	(Optional) Name of the procedure containing the formal parameter. In CloudBees CD/RO 5.0 and later, this argument is optional. Argument type: String
releaseName	(Optional) Name of the release, if the formal parameter is on a release-scoped pipeline. Argument type: String
serviceName	(Optional) Name of the service, if the formal parameter is on a service process. Argument type: S

projectName

Name of the project containing the procedure. The name must be unique among all projects.

Argument type: String

formalParameterName

The name for the formal parameter that is used when the procedure is invoked to specify a value for the parameter.

Argument type: String

In addition to the above required arguments, specify one or more of the following to locate the formal parameter container, beginning with the top-level object locator.

applicationEntityRevisionId

(Optional) The revision ID of the versioned object.

Argument type: UUID

applicationName

(Optional) Name of the application when the formal parameter is on an application process step.

Argument type: String

catalogName

(Optional) Name of the catalog when the formal parameter is on a catalog item.

Argument type: String

componentName

(Optional) Name of the component when the formal parameter is on a component process step.

Argument type: String

dashboardName

(Optional) The name of the dashboard, if the formal parameter is on a dashboard.

Argument Type: String

flowName

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

Argument Type: String

flowStateName

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

Argument Type: String

gateType

(Optional) The type of the gate: POST or PRE.

Argument Type: String

includeDetails

(Optional)< Boolean flag— 0|1|true|false > If 1 or true, return additional details in the ec_customeEditorData property sheet associated with the requested formal parameter. Default is false.

Argument type: boolean

pipelineName

(Optional) Name of the pipeline when the formal parameter is on a pipeline.

Argument type: String

processName

(Optional) Name of the process when the formal parameter is on a process step.

Argument type: String

processStepName

(Optional) Name of the process step when the formal parameter is on a process step.

Argument type: String

procedureName

(Optional) Name of the procedure containing the formal parameter.

In CloudBees CD/RO 5.0 and later, this argument is optional.

Argument type: String

releaseName

(Optional) Name of the release, if the formal parameter is on a release-scoped pipeline.

Argument type: String

serviceName

(Optional) Name of the service, if the formal parameter is on a service process.

Argument type: S