Groovy API reference

Parameter

23 minute readReference

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.

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

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) The name of the procedure.

stepName

String

(Required) The name of the step in the procedure.

formalParameterName

String

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

applicationName

String

The name of the application.

componentApplicationName

String

The name of the component in the application.

componentName

String

The name of the component.

gateType

GateType

The type of the gate.

microserviceApplicationName

String

The name of the microservice application.

microserviceName

String

The name of the microservice.

pipelineName

String

The name of the pipeline.

processName

String

The name of the process.

processStepName

String

The name of the step in the process.

releaseName

String

The name of the release, if attaching a credential to a release pipeline.

stageName

String

Name of the stage to which this task belongs to.

stateDefinitionName

String

The name of the workflow state definition, if attaching a parameter to a state definition.

taskName

String

The name of the task.

workflowDefinitionName

String

The name of the workflow definition, if attaching a parameter to a workflow state definition.

Positional arguments

projectName, procedureName, stepName, formalParameterName

Usage

ec-perl

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

ectool

ectool attachParameter projectName,  procedureName,  stepName,  formalParameterName, [optionals]

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'}

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) The name of the procedure.

stepName

String

(Required) The name of the step.

actualParameterName

String

(Required) The name of the parameter to create/modify/delete.

applicationName

String

The name of the application, if the actual parameter is on an application process step.

archiveConnectorName

String

The name of the archive connector.

catalogItemName

String

The name of the catalog item.

catalogItemRunId

String

The ID of the catalog item run, if the actual parameter is on a catalog item run.

catalogName

String

The name of the catalog.

componentName

String

The name of the component, if the actual parameter is on a component process step.

dashboardName

String

The name of the dashboard.

flowName

String

The name of the flow to which the flow state belongs to.

flowStateName

String

The name of the flow state, if the formal parameter is on a flow state.

pipelineName

String

The name of the pipeline.

processName

String

The name of the process, if the actual parameter is on a process step.

processStepName

String

The name of the process step, if the actual parameter is on a process step.

releaseName

String

The name of the release, if the actual parameter is on a release.

scheduleName

String

The name of the schedule.

stateDefinitionName

String

The name of the state definition.

tierMapName

String

The name of the tier map.

transitionDefinitionName

String

The name of the state definition.

triggerName

String

The name of the trigger.

value

String

The value of the actual parameter, if creating or modifying.

widgetName

String

The name of the widget.

workflowDefinitionName

String

The name of the workflow definition.

Positional arguments

projectName, procedureName, stepName, actualParameterName

Usage

ec-perl

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

ectool

ectool createActualParameter projectName,  procedureName,  stepName,  actualParameterName, [optionals]

createFormalOutputParameter

Creates a new formal output parameter.

Arguments

Argument Name Type Description

projectName

String

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

formalOutputParameterName

String

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

applicationName

String

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

description

String

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

pipelineName

String

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

procedureName

String

The name of the procedure.

processName

String

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

releaseName

String

The name of the release, where pipeline is located.

Positional arguments

projectName, formalOutputParameterName

Usage

ec-perl

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

ectool

ectool createFormalOutputParameter projectName,  formalOutputParameterName, [optionals]

createFormalParameter

Creates a formal parameter.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) The name of the procedure.

formalParameterName

String

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

applicationName

String

The name of the application, if the formal parameter is on an application process.

archiveConnectorName

String

The name of the archive connector, if the formal parameter is on an archive connector.

catalogItemName

String

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

catalogName

String

The name of the catalog to which the catalog item belongs to.

checkedValue

String

Parameter value when the checkbox used to render the parameter is checked. Applicable only for checkbox type.

componentName

String

The name of the component, if the formal parameter is on a component process.

dashboardName

String

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

defaultValue

String

If no value is provided for the parameter when the procedure is invoked, this value will be used.

defaultValueDsl

String

DSL for default value.

dependsOn

String

Comma-separated list of formal parameters that this parameter depends on. Use with cascading drop-down (select) parameters to declare dependency on one or more parameters.

description

String

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

expansionDeferred

Boolean

True means expansion for this parameter should be deferred: the parameter value will not be expanded when the procedure call is expanded, but can be expanded from a command step instead.

flowName

String

The name of the flow to which the flow state belongs to.

flowStateName

String

The name of the flow state, if the formal parameter is on a flow state.

gateType

GateType

The type of the gate which contains the task, if the formal parameter is belongs to a task.

label

String

Specifies the display label.

microserviceName

String

The name of the microservice.

multiSelect

Boolean

Whether or not to use multiselect instead of select.

options

Collection

Ordered list of options.

optionsDsl

String

DSL for populating drop-down options for select formal parameter type.

optionsFromPropertySheet

String

Path to the property sheet containing the options.

orderIndex

Integer

Specifies the display order index (starts from 1).

pipelineName

String

The name of the pipeline, if the formal parameter is on a pipeline.

processName

String

The name of the process, if the formal parameter is on a process.

processStepName

String

The name of the process step, if the formal parameter is on a process step.

projectFormalParameterName

String

Used when rendering the formal parameter to identify the formal parameter to use in order to get the owning project name. Applicable only for release, pipeline, application, service or environment parameter type.

propertyReference

String

Property or property sheet to use for displaying options.

propertyReferenceType

PropertyReferenceType

Whether the propertyReference value is a property sheet (default) or a property. For property sheet, nested property names are used as options while for property, the property value is used as an option.

releaseName

String

The name of the release, if the formal parameter is on a release-scoped pipeline.

renderCondition

String

Condition for rendering the formal parameter.

reportName

String

The name of the report, if the formal parameter is on a report.

required

Boolean

True means this parameter is required: the procedure will not execute unless a value is given for the parameter.

simpleList

String

Pipe-separated list of options, e.g., option1

option2

option3.

stageName

String

The name of the stage which contains the task, if the formal parameter is belongs to a task.

stateDefinitionName

String

The name of the state definition.

stateName

String

The name of a workflow state.

taskName

String

The name of the task, if the formal parameter is belongs to a task.

type

String

The type of a formal parameter.

uncheckedValue

String

Parameter value when the checkbox used to render the parameter is unchecked. Applicable only for checkbox type.

updateFormXml

Boolean

Whether the parameter form XML stored in the procedure property ec_parameterForm should also be updated.

validationDsl

String

DSL for validating the formal parameter.

workflowDefinitionName

String

The name of the workflow definition.

workflowName

Positional arguments

projectName, procedureName, formalParameterName

Usage

ec-perl

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

ectool

ectool createFormalParameter projectName,  procedureName,  formalParameterName, [optionals]

deleteActualParameter

Deletes an actual parameter.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) The name of the procedure.

stepName

String

(Required) The name of the step.

actualParameterName

String

(Required) The name of the parameter to create/modify/delete.

applicationName

String

The name of the application, if the actual parameter is on an application process step.

archiveConnectorName

String

The name of the archive connector.

catalogItemName

String

The name of the catalog item.

catalogItemRunId

String

The ID of the catalog item run, if the actual parameter is on a catalog item run.

catalogName

String

The name of the catalog.

componentName

String

The name of the component, if the actual parameter is on a component process step.

dashboardName

String

The name of the dashboard.

flowName

String

The name of the flow to which the flow state belongs to.

flowStateName

String

The name of the flow state, if the formal parameter is on a flow state.

pipelineName

String

The name of the pipeline.

processName

String

The name of the process, if the actual parameter is on a process step.

processStepName

String

The name of the process step, if the actual parameter is on a process step.

releaseName

String

The name of the release, if the actual parameter is on a release.

scheduleName

String

The name of the schedule.

stateDefinitionName

String

The name of the state definition.

tierMapName

String

The name of the tier map.

transitionDefinitionName

String

The name of the state definition.

triggerName

String

The name of the trigger.

widgetName

String

The name of the widget.

workflowDefinitionName

String

The name of the workflow definition.

Positional arguments

projectName, procedureName, stepName, actualParameterName

Usage

ec-perl

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

ectool

ectool deleteActualParameter projectName,  procedureName,  stepName,  actualParameterName, [optionals]

deleteFormalOutputParameter

Deletes a formal output parameter.

Arguments

Argument Name Type Description

projectName

String

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

formalOutputParameterName

String

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

applicationName

String

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

pipelineName

String

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

procedureName

String

The name of the procedure.

processName

String

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

releaseName

String

The name of the release, where pipeline is located.

Positional arguments

projectName, formalOutputParameterName

Usage

ec-perl

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

ectool

ectool deleteFormalOutputParameter projectName,  formalOutputParameterName, [optionals]

deleteFormalParameter

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

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) The name of the procedure.

formalParameterName

String

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

applicationName

String

The name of the application, if the formal parameter is on an application process.

archiveConnectorName

String

The name of the archive connector, if the formal parameter is on an archive connector.

catalogItemName

String

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

catalogName

String

The name of the catalog to which the catalog item belongs to.

componentName

String

The name of the component, if the formal parameter is on a component process.

dashboardName

String

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

flowName

String

The name of the flow to which the flow state belongs to.

flowStateName

String

The name of the flow state, if the formal parameter is on a flow state.

gateType

GateType

The type of the gate which contains the task, if the formal parameter is belongs to a task.

microserviceName

String

The name of the microservice.

pipelineName

String

The name of the pipeline, if the formal parameter is on a pipeline.

processName

String

The name of the process, if the formal parameter is on a process.

processStepName

String

The name of the process step, if the formal parameter is on a process step.

releaseName

String

The name of the release, if the formal parameter is on a release-scoped pipeline.

reportName

String

The name of the report, if the formal parameter is on a report.

stageName

String

The name of the stage which contains the task, if the formal parameter is belongs to a task.

stateDefinitionName

String

The name of the state definition.

stateName

String

The name of a workflow state.

taskName

String

The name of the task, if the formal parameter is belongs to a task.

updateFormXml

Boolean

Whether the parameter form XML stored in the procedure property ec_parameterForm should also be updated.

workflowDefinitionName

String

The name of the workflow definition.

workflowName

String

The name of a workflow.

Positional arguments

projectName, procedureName, formalParameterName

Usage

ec-perl

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

ectool

ectool deleteFormalParameter projectName,  procedureName,  formalParameterName, [optionals]

detachParameter

Detaches a formal parameter from a step.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) The name of the procedure.

stepName

String

(Required) The name of the step in the procedure.

formalParameterName

String

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

applicationName

String

The name of the application.

componentApplicationName

String

The name of the component in the application.

componentName

String

The name of the component.

gateType

GateType

The type of the gate.

microserviceApplicationName

String

The name of the microservice application.

microserviceName

String

The name of the microservice.

pipelineName

String

The name of the pipeline.

processName

String

The name of the process.

processStepName

String

The name of the step in the process.

releaseName

String

The name of the release, if attaching a credential to a release pipeline.

stageName

String

Name of the stage to which this task belongs to.

stateDefinitionName

String

The name of the workflow state definition, if attaching a parameter to a state definition.

taskName

String

The name of the task.

workflowDefinitionName

String

The name of the workflow definition, if attaching a parameter to a workflow state definition.

Positional arguments

projectName, procedureName, stepName, formalParameterName

Usage

ec-perl

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

ectool

ectool detachParameter projectName,  procedureName,  stepName,  formalParameterName, [optionals]

getActualParameter

Retrieves an actual parameter by its name. For more information about parameters, refer to createActualParameter.

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

Arguments

Argument Name Type Description

actualParameterName

String

(Required) The name of the parameter.

applicationEntityRevisionId

UUID

The revision ID of the versioned object.

applicationName

String

The name of the application, if the actual parameter is on an application process step.

catalogItemName

String

The name of the catalog item.

catalogItemRunId

String

The ID of the catalog item run, if the actual parameter is on a catalog item run.

catalogName

String

The name of a catalog.

componentName

String

The name of the component, if the actual parameter is on a component process step.

dashboardName

String

The name of the dashboard.

flowName

String

The name of the flow to which the flow state belongs to.

flowRuntimeId

String

The ID of the flow runtime, to which flow runtime belongs.

flowRuntimeName

String

The name of the flow runtime, to which flow runtime belongs.

flowRuntimeStateId

UUID

The ID of the flow runtime state.

flowRuntimeStateName

String

The name of the flow runtime state.

flowStateName

String

The name of the flow state, if the actual parameter is on a flow state.

jobId

String

The primary key of the job, or the name of the job.

jobStepId

UUID

The primary key for a job step.

pipelineName

String

The name of a pipeline.

procedureName

String

The name of a procedure.

processName

String

The name of the process, if the actual parameter is on a process step.

processStepName

String

The name of the process step, if the actual parameter is on a process step.

projectName

String

The name of a project.

releaseName

String

The name of the release, if the actual parameter is on release.

scheduleName

String

The name of a schedule.

searchJobStepHierarchy

Boolean

Whether or not to search for the actual parameter in the job step hierarchy to find the specified actual parameter. Applicable only with jobStepId argument.

stateDefinitionName

String

The name of a workflow state definition.

stateName

String

The name of a workflow state.

stepName

String

The name of a procedure step.

tierMapName

String

The name of the tier map.

transitionDefinitionName

String

The name of a workflow transition definition.

transitionName

String

The name of a workflow transition.

triggerName

String

The name of the trigger.

widgetName

String

The name of a widget.

workflowDefinitionName

String

The name of a workflow definition.

workflowName

String

The name of a workflow.

Positional arguments

actualParameterName

Usage

ec-perl

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

ectool

ectool getActualParameter actualParameterName, [optionals]

getActualParameters

Retrieves all actual parameters from a job, step, schedule, state, or transition.

You must specify object locators to find the parameter.

Arguments

Argument Name Type Description

applicationEntityRevisionId

UUID

The revision ID of the versioned object.

applicationName

String

The name of the application, if the actual parameter is on an application process step.

catalogItemName

String

The name of the catalog item.

catalogItemRunId

String

The ID of the catalog item run, if the actual parameter is on a catalog item run.

catalogName

String

The name of a catalog.

componentName

String

The name of the component, if the actual parameter is on a component process step.

dashboardName

String

The name of the dashboard.

flowName

String

The name of the flow to which the flow state belongs to.

flowRuntimeId

String

The ID of the flow runtime, to which flow runtime belongs.

flowRuntimeName

String

The name of the flow runtime, to which flow runtime belongs.

flowRuntimeStateId

UUID

The ID of the flow runtime state.

flowRuntimeStateName

String

The name of the flow runtime state.

flowStateName

String

The name of the flow state, if the actual parameter is on a flow state.

jobId

String

The primary key of the job, or the name of the job.

jobStepId

UUID

The primary key for a job step.

pipelineName

String

The name of a pipeline.

procedureName

String

The name of a procedure.

processName

String

The name of the process, if the actual parameter is on a process step.

processStepName

String

The name of the process step, if the actual parameter is on a process step.

projectName

String

The name of a project.

releaseName

String

The name of the release, if the actual parameter is on release.

scheduleName

String

The name of a schedule.

stateDefinitionName

String

The name of a workflow state definition.

stateName

String

The name of a workflow state.

stepName

String

The name of a procedure step.

tierMapName

String

The name of the tier map.

transitionDefinitionName

String

The name of a workflow transition definition.

transitionName

String

The name of a workflow transition.

triggerName

String

The name of the trigger.

widgetName

String

The name of a widget.

workflowDefinitionName

String

The name of a workflow definition.

workflowName

String

The name of a workflow.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool getActualParameters [optionals]

getFormalOutputParameter

Retrieves a formal output parameter by name.

Arguments

Argument Name Type Description

projectName

String

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

formalOutputParameterName

String

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

applicationName

String

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

pipelineName

String

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

procedureName

String

The name of the procedure.

processName

String

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

releaseName

String

The name of the release, where pipeline is located.

Positional arguments

projectName, formalOutputParameterName

Usage

ec-perl

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

ectool

ectool getFormalOutputParameter projectName,  formalOutputParameterName, [optionals]

getFormalOutputParameters

Retrieves all formal output parameters from an output parameter container.

Arguments

Argument Name Type Description

projectName

String

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

applicationName

String

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

pipelineName

String

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

procedureName

String

The name of the procedure.

processName

String

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

releaseName

String

The name of the release, where pipeline is located.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool getFormalOutputParameters projectName, [optionals]

getFormalParameter

Retrieves a formal parameter by its name.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) The name of the procedure.

formalParameterName

String

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

applicationEntityRevisionId

UUID

The revision ID of the versioned object.

applicationName

String

The name of the application, if the formal parameter is on an application process.

archiveConnectorName

String

The name of the archive connector, if the formal parameter is on an archive connector.

catalogItemName

String

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

catalogName

String

The name of the catalog to which the catalog item belongs to.

componentName

String

The name of the component, if the formal parameter is on a component process.

dashboardName

String

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

flowName

String

The name of the flow to which the flow state belongs to.

flowRuntimeStateId

UUID

The ID of the flow runtime state.

flowStateName

String

The name of the flow state, if the formal parameter is on a flow state.

gateType

GateType

The type of the gate which contains the task, if the formal parameter is belongs to a task.

includeDetails

Boolean

True to include details such as corresponding properties in the ec_customEditorData property sheet (default is false).

microserviceName

String

The name of the microservice.

pipelineName

String

The name of the pipeline, if the formal parameter is on a pipeline.

processName

String

The name of the process, if the formal parameter is on a process.

processStepName

String

The name of the process step, if the formal parameter is on a process step.

releaseName

String

The name of the release, if the formal parameter is on a release-scoped pipeline.

reportName

String

The name of the report, if the formal parameter is on a report.

stageName

String

The name of the stage which contains the task, if the formal parameter is belongs to a task.

stateDefinitionName

String

The name of the state definition.

stateName

String

The name of a workflow state.

taskName

String

The name of the task, if the formal parameter is belongs to a task.

workflowDefinitionName

String

The name of the workflow definition.

workflowName

String

The name of a workflow.

Positional arguments

projectName, procedureName, formalParameterName

Usage

ec-perl

$cmdr->getFormalParameter(<projectName>, <procedureName>, <formalParameterName>, {<optionals>});