Using the Perl API
IntroductionAccess tokensACL managementApplication dependencyApplicationsApplication tier Artifact managementCatalogsChange historyCI build detailCI configurationCI jobsComponentsCredential managementCustom filtersDatabase configurationData retentionCloudBees AnalyticsDirectory provider managementDynamic environmentsEmail configuration managementEmail notifier managementEnvironmentEnvironment tierGateway and zone managementInstalling or upgrading remote agentsJob managementMicroservicesObject tagsParameter managementPersonasPipelines and releasesPlugin managementPlugin configuration managementProcedure managementProcessProcess dependencyProcess stepProject managementProperty managementResource managementRolling deploySchedule managementService accounts for webhooksServer managementSingle sign on for SAMLSnapshotsTier mapTrigger managementUser and group managementUser profile email managementWait dependenciesWorkflow definition managementWorkflow managementWork itemsWorkspace managementMiscellaneous management
Perl API response and element glossary
IntroductionExamplesTroubleshooting
IntroductionaccesstokenaclaclentryactualparameteractualparametersapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitiontagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

Parameter Management

33 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. 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

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

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

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

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
}