createFormalParameter

Back to index

Summary

Creates a formal parameter.
projectName
Stringrequired
The name for the project that must be unique among all projects.
procedureName
Stringrequired
The name of the procedure.
formalParameterName
Stringrequired
Name for this parameter; used when the procedure is invoked to specify a value for the parameter.
applicationName
Stringoptional
The name of the application, if the formal parameter is on an application process.
archiveConnectorName
Stringoptional
The name of the archive connector, if the formal parameter is on an archive connector.
catalogItemName
Stringoptional
The name of the catalog item, if the formal parameter is on a catalog item.
catalogName
Stringoptional
The name of the catalog to which the catalog item belongs to.
checkedValue
Stringoptional
Parameter value when the checkbox used to render the parameter is checked. Applicable only for checkbox type.
componentName
Stringoptional
The name of the component, if the formal parameter is on a component process.
dashboardName
Stringoptional
The name of the dashboard, if the formal parameter is on a dashboard.
defaultValue
Stringoptional
If no value is provided for the parameter when the procedure is invoked, this value will be used.
defaultValueDsl
Stringoptional
DSL for default value.
dependsOn
Stringoptional
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
Stringoptional
Comment text describing this object that is not interpreted at all by CloudBees CD/RO.
expansionDeferred
Booleanoptional
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
Stringoptional
The name of the flow to which the flow state belongs to.
flowStateName
Stringoptional
The name of the flow state, if the formal parameter is on a flow state.
gateType
Stringoptional
The type of the gate which contains the task, if the formal parameter is belongs to a task.
Possible values: "POST", "PRE"
label
Stringoptional
Specifies the display label.
microserviceName
Stringoptional
The name of the microservice.
multiSelect
Booleanoptional
Whether or not to use multiselect instead of select.
option
Arrayoptional
Ordered list of options.
optionsDsl
Stringoptional
DSL for populating drop-down options for select formal parameter type.
optionsFromPropertySheet
Stringoptional
Path to the property sheet containing the options.
orderIndex
Integeroptional
Specifies the display order index (starts from 1).
pipelineName
Stringoptional
The name of the pipeline, if the formal parameter is on a pipeline.
processName
Stringoptional
The name of the process, if the formal parameter is on a process.
processStepName
Stringoptional
The name of the process step, if the formal parameter is on a process step.
projectFormalParameterName
Stringoptional
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
Stringoptional
Property or property sheet to use for displaying options.
propertyReferenceType
Stringoptional
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.
Possible values: "plugin", "property", "propertySheet"
releaseName
Stringoptional
The name of the release, if the formal parameter is on a release-scoped pipeline.
renderCondition
Stringoptional
Condition for rendering the formal parameter.
reportName
Stringoptional
The name of the report, if the formal parameter is on a report.
required
Booleanoptional
True means this parameter is required: the procedure will not execute unless a value is given for the parameter.
simpleList
Stringoptional
Pipe-separated list of options, e.g., option1|option2|option3.
stageName
Stringoptional
The name of the stage which contains the task, if the formal parameter is belongs to a task.
stateDefinitionName
Stringoptional
The name of the state definition.
stateName
Stringoptional
The name of a workflow state.
taskName
Stringoptional
The name of the task, if the formal parameter is belongs to a task.
type
Stringoptional
The type of a formal parameter.
uncheckedValue
Stringoptional
Parameter value when the checkbox used to render the parameter is unchecked. Applicable only for checkbox type.
updateFormXml
Booleanoptional
Whether the parameter form XML stored in the procedure property ec_parameterForm should also be updated.
validate
Booleanoptional
If passed 0, then all validations check in the DSL arguments (validationDsl, optionsDsl, defaultValueDsl) are deactivated.
validationDsl
Stringoptional
DSL for validating the formal parameter.
workflowDefinitionName
Stringoptional
The name of the workflow definition.
workflowName
Stringoptional
The name of a workflow.

Usage

Perl

$cmdr->createFormalParameter( "test-projectName", # projectName "test-procedureName", # procedureName "test-formalParameterName" # formalParameterName # optionals );

ectool

ectool createFormalParameter \ "test-projectName" `# projectName` \ "test-procedureName" `# procedureName` \ "test-formalParameterName" `# formalParameterName` \ # optionals

Examples

Basic DSL 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 you to only enter test1 or test2 as a value in the text entry field for the paramName1 parameter.

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 }

DSL validation with parameter dependencies

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

For custom validation that depends on another parameter, you also need to declare a dependency on the formal parameter that the validation logic depends on. In this example, the state parameter must declare that it depends on the country parameter 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 you select Use Existing Project, you are expected to provide a value for Existing Project. You are not expected to provide a value for New Project Name as it is not relevant.

Conversely, if you do not select Use Existing Project, then you are expected to provide a value for New Project Name. You are 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 you select a parameter of type release, pipeline, application, environment, or service, you 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' } }

Simple dropdown

A parameter of type dropdown, 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 dropdown.

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 dropdown with parameter dependencies

Here is another example that builds on the previous example to create cascading dynamic dropdowns.

  1. Start by defining a dropdown select parameter named ProjectParam that displays dynamic options as described in the earlier example.

  2. Add a second dropdown select parameter type, called AppParam.

  3. Register the sample script below as the DSL to use for the dropdown options for this parameter.

    def options = [] // 'AppParam' parameter is dependent on 'ProjectParam' parameter. // Note that this dependency is declared in the form.xml (refer to 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

    The script returns the list of applications belonging to the selected project from the ProjectParam parameter. Any time the selected project is changed for the parameter ProjectParam, the available applications listed as options in AppParam also change based on the project.

    For cascading dropdowns, you also need to declare a dependency on the formal parameter that the second dropdown depends on. In this example, the AppParam parameter must declare that it depends on the ProjectParam parameter by adding it to its dependencies.

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. This is useful when the 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 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

Perl

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

ectool

For procedure parameters:

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

For pipeline parameters:

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

Use parameters to create a checkbox:

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

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