Define parameters

Parameters are user-defined and used throughout the deployment planning and management process. You can define both input and output parameters in place of predefined credentials, property paths, user or group names for notifications, runtime conditions.

These objects support parameters:

Pipelines (standalone and release)
Pipeline manual tasks
Traditional application processes and components
Microservice application processes
Master Components
Procedures
Service catalog items
Dashboards
Reports

Configure Parameters

Access parameter management features:

Navigate to an object editor.
Select Parameters from the object three-dots menu. The Parameters screen displays.

Figure 1. Parameters

Manage input and output parameters.
- Remove parameters.
  1. Select the row of parameters to be deleted.
  2. Select the icon.
- Add or edit output parameters by selecting the Output Parameters tab.
  - Create a new output parameter.
    
    Select either icon or There are no parameters yet. Add one +. The New Output Parameter screen displays.
    
    Complete the Name and Description fields.
    
    Select OK.
  - Modify existing output parameter.
    
    Select the edit icon for the parameter to be altered. The Edit Output Parameter screen displays.
    
    Modify the Name and Description fields.
    
    Select OK.
- Sort the input parameter list using the Type or Required filters.
- Create a new input parameter.
  1. Select either icon or There are no parameters yet. Add one +. The New parameter screen displays.
  2. Complete the parameter fields. Refer to Parameters input fields, for details.
  3. Select OK.
Configure Input parameters
- Move a parameter to a different list position.
  1. Select the move arrow.
  2. Drag and drop the parameter into the new position.
- Modify an existing input parameter.
  1. Select the parameter edit icon. The Edit Input Parameter screen displays.
  2. Modify the parameter fields. Refer to Parameters input fields for details.
  3. Select OK.

Parameters input fields

Name

A unique name for the parameter.

Description

(Optional) Plain text or HTML description for this object. This description renders as a tool tip for the parameter at object runtime.

If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

You can include hyperlinks as part of an object description for any CloudBees CD/RO object.

View HTML example

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

<i>Note</i>: For more information about the <b>abc</b> object, see \https://www.google.com.▼

Label

(Optional) The label for this parameter as it appears on the parameters panel at object runtime.

Application - Parameter type

Creates an Application dropdown to select an application object. To use this parameter type, you must provide a method for users to select an application project via a Project, Dropdown Menu, or Text Entry parameter.

Not available for Dashboard or Report objects.

Checkbox - Parameter type

Creates a checkbox for a value to select (or not) when the parameter is presented.

Value when unchecked — The value of the parameter when the checkbox is not selected.
Value when checked — The value of the checkbox when the checkbox is selected.

Credential - Parameter type

Selecting this option requires the user to specify a username and password to use this parameter at runtime.

Not available for Dashboard or Report objects.

Date - Parameter type

Allows users to select a date value using a date picker. The selected date value is in ISO 8601 yyyy-MM-dd.

Dropdown Menu - Parameter type

Creates a dropdown menu to select values from when the parameter is presented.

Dynamic Default Value - Select this option to specify the default parameter value based upon other parameters that were added to dependencies. The Dynamic Default Value option is only available for parameters that have dependencies.

View an example of a selected value for a formal country parameter.

// Retrieve a default value to display for the parameter based on the value of
// another dependent parameter, for example 'country'.
def selectedValue = args.parameters['country']
// Note: You also need to declare a dependency on the 'country' formal parameter
// from this formal parameter to enable the UI to trigger a retrieval of a default value
// for this formal parameter whenever the user changes the 'country' formal parameter value.
if (selectedValue == 'US') {
  return 'Washington'
} else if (selectedValue == 'Ukraine') {
  return 'Kyiv'
}
return ''▼

Multi Select - Select this option to allow users to select more than one option from dropdown menus. Multiple values are passed to the parameter as a newline-separated list.
View an example of multi select access to a value of the parameter p_multiSelect.
def paramValue = args['p_multiSelect'] if (paramValue) { def list = paramValue.split("\n") def projName = getProperty("/myProject/name").value list.each{ value -> createPipeline(projectName: projName, pipelineName: value) } }
▼
Enter options - Select Add Option + to add a new row. Type in the text and value for each option. The text will be displayed in the menu, and the value is the parameter value if that option is selected.
Load options from list - Enter a pipe-separated list of options (for example, foo\|bar\|baz ). The text and value for the options will be the same.

Load Options from Properties - Enter the path to the property sheet that contains options for the parameter. This selection has two choices:

Load options using fixed structure:

The options to display for the parameter are determined using the following properties that must exist within the property sheet.

View fixed structure example.

optionCount=<Number of available options, for example, 3>
option1/
   text=<Text to display>
   value=<Parameter value to use>
option2/
   text=<Text to display>
   value=<Parameter value to use>

 ...and so on till
optionN/
   text=<Text to display>
   value=<Parameter value to use>▼

Options from a property sheet:

View example 1: If the Property Sheet contains the following Properties.

Version7=7.0
Version8=8.0
Version9=9.2

...then the following options will automatically be displayed using the Property name as the text to
display and the Property value as the Parametervalue to use.

Version7
Version8
Version9▼

View example 2: If the Property Sheet contains the following nested Property Sheets.

Version7/
Version8/
Version9/

...then the following options will automatically be displayed using the Property Sheet name as both the
text to display as well as the Parameter value to use.

Version7
Version8
Version9▼

Load options using DSL — Enter a DSL script that allows for dynamically populating the dropdown menu. Select the tooltip icon Tool tip for this option to see an example script. For additional examples, refer to Use the CloudBees CD/RO domain-specific language (DSL).

View example 1: DSL script for returning dynamic dropdown options.

import com.electriccloud.domain.FormalParameterOptionsResult

def options = new FormalParameterOptionsResult()

// Apply your custom logic to build the list of options to display.

options.add(/*value*/ 'value1', /*displayString*/ 'Value One')
options.add(/*value*/ 'value2', /*displayString*/ 'Value Two')
options.add(/*value*/ 'value3', /*displayString*/ 'Value Three')

return options
}▼

View example 2: DSL script for cascading dropdown options.

For cascading dropdowns, you must declare a dependency for the formal parameter the dropdown options depend on.

import com.electriccloud.domain.FormalParameterOptionsResult

def options = new FormalParameterOptionsResult()

// Retrieve options to display for the parameter based on the value of
// another dependent parameter say 'country'.

def selectedValue = args.parameters['country']

// Note: You also need to declare a dependency on 'country' formal parameter
// from this formal parameter to enable the UI to trigger a retrieval of
// dynamic drop-down options for this formal parameter whenever the
// 'country' formal parameter value is changed by the user.

if (selectedValue == 'US') {
  options.add( /*value*/ 'CA', /*displayString*/ 'California')
  options.add( /*value*/ 'CO', /*displayString*/ 'Colorado')

} else if (selectedValue == 'Canada') {
  options.add( /*value*/ 'BC', /*displayString*/ 'British Columbia')
  options.add( /*value*/ 'ON', /*displayString*/ 'Ontario')
}

return options
}▼

View example 3: Handling DSL property reference errors.

When you save DSL dropdown menu code, the code is evaluated to catch syntax and runtime errors. A property reference error occurs if the property is not available when the parameter is being set. Use this try-catch pattern to avoid this error.

def value
try {
  value = getProperty(propertyName: 'property path').value
} catch (e) {
  return []
}▼

View example 4: DSL script for using a dependent parameter value.

In this example, a pull down parameter is created to select releases from a given project. The project identified using the relProject parameter must be identified as a dependent parameter to this release name parameter. The release name list can be generated using the following DSL:

import com.electriccloud.domain.FormalParameterOptionsResult
def options = new FormalParameterOptionsResult()
def proj=args.parameters['relProject']
if (proj) {
  getReleases(projectName: proj).each { rel ->
    options.add(rel.releaseName,rel.releaseName)
  }
}
return options▼

View example 5: A dropdown list with values from a URL.

project "DSL-Samples",{
	procedure 'Parameter Dropdown from URL', {
		formalParameter 'org',
			defaultValue: 'cloudbees',
			orderIndex: 1,
			type: 'entry'
		formalParameter 'repo',
			orderIndex: 2,
			required: true,
			type='select',
			dependsOn: 'org',
			optionsDsl: '''\
				import com.electriccloud.domain.FormalParameterOptionsResult
				def org = args.parameters['org']
				import groovy.json.JsonSlurper
				def options = new FormalParameterOptionsResult()
				def response = '[{"name":"empty"}]'
				try {
					response = (new URL("https://api.github.com/orgs/${org}/repos").text)
				} catch(e) {}
				def Slurper = new JsonSlurper()
				def repos = Slurper.parseText(response)
				repos.each {
					options.add( it.name, it.name)
				}
				return options
			'''.stripIndent()
	}
}▼

Environment - Parameter type

Creates an Environment dropdown to select an environment object. To use this parameter type, you must first provide a way for users to select the object project via a Project, Dropdown Menu, or Text Entry parameter.

Not available for Dashboard or Report objects.

Header - Parameter type

Used to render a heading. When rendered, this header is positioned before one or more parameters based on its position in the parameter list. There is no other explicit association with other parameters.

Integer - Parameter type

Allows for an integer value entry.

Microservice - Parameter type

Creates a Microservice dropdown to select a microservice object. To use this parameter type, you must first provide a way for users to select the object’s project via a Project, Dropdown Menu, or Text Entry parameter.

Not available for Dashboard or Report objects.

Pipeline - Parameter type

Creates a Pipeline dropdown to select a pipeline object. To use this parameter type, you must first provide a way for the user to select the object’s project via a Project, Dropdown Menu, or Text Entry parameter.

Not available for Dashboard or Report objects.

Plugin configuration - Parameter type

Creates a dropdown menu to select an existing plugin configuration or creates a new one. Allows for the expansion of a property based on the dependent parameter or full property path. The dependent parameter is set in the depends on field.

View example 1: Catalog item with pluginConfiguration parameter in XML form.

catalog 'CD 10.7 SSC Parameter Enhancements', {
    projectName = 'Default'

    catalogItem 'PluginConfiguration in XML', {
      allowScheduling = '0'
      buttonLabel = 'Create'
      catalogName = 'test'
      dslParamForm = '''{
    "sections": {
      "section": [{
        "name": "Configuration",
        "instruction": "Plugin Configuration",
        "ec_parameterForm": "<editor><formElement><label>Git Plugin Configuration</label> <property>config</property><type>pluginConfiguration</type><config>1</config><propertyReference>EC-GitHub</propertyReference><required>1</required></formElement> </editor>"
      }]
    }
  }'''
      dslString = '// PUT YOUR DSL HERE'
      endTargetJson = null
      iconUrl = 'icon-catalog-item.svg'
      subpluginKey = null
      subprocedure = null
      subproject = null
      useFormalParameter = '0'
  }
}▼

View Example 2: pluginConfiguration catalog item containing a dynamic pluginKey referring to the catalog project property test-pluginKey.

catalog 'CD 10.7 SSC Parameter Enhancements', {
    projectName = 'Default'

    catalogItem 'Property Ref in PluginConfiguration', {
        dslString = '// PUT YOUR DSL HERE'
        endTargetJson = null
        iconUrl = 'icon-catalog-item.svg'
        subpluginKey = null
        subprocedure = null
        subproject = null
        useFormalParameter = '1'

        formalParameter 'pluginConfig', defaultValue: null, {
          expansionDeferred = '0'
          label = 'Plugin Configuration'
          orderIndex = '1'
          propertyReference = '$[/myProject/test-pluginKey]'
          required = '1'
          type = 'pluginConfiguration'
        }
    }
}▼

View example 3: pluginConfiguration catalog item parameter containing a dynamic pluginKey referring to the dependsOn parameter.

catalog 'CD 10.7 SSC Parameter Enhancements', {
    projectName = 'Default'

    catalogItem 'DependsOn Plugin Configuration', {
        dslString = '//PUT YOUR DSL HERE'
        useFormalParameter = '1'

        formalParameter 'pluginKey', defaultValue: null, {
          description = 'Plugin Key'
          expansionDeferred = '0'
          label = 'Plugin Key'
          optionsDsl = '''import com.electriccloud.domain.FormalParameterOptionsResult

    def plugins = getPlugins()
    def options = new FormalParameterOptionsResult()
    plugins.each{ plugin ->
        options.add(plugin.pluginKey, plugin.pluginKey)
    }
    options'''
          orderIndex = '1'
          required = '1'
          type = 'select'
        }

        formalParameter 'pluginConfig', defaultValue: null, {
          description = 'Plugin Configuration'
          dependsOn = 'pluginKey'
          expansionDeferred = '0'
          label = 'Plugin Configuration'
          orderIndex = '2'
          propertyReference = '$[pluginKey]'
          required = '1'
          type = 'pluginConfiguration'
        }
    }
}▼

Procedure - Parameter type

Creates a Procedure dropdown to select an existing procedure object. To use this parameter type, you must first provide a way for users to select the object project via a Project, Dropdown Menu, or Text Entry parameter.

Not available for Dashboard or Report objects.

Project - Parameter type

Creates a Project dropdown to select a project name.

Radio Selector - Parameter type

Creates radio buttons to select an entry when the parameter is presented.

View example of setting default value for the country formal parameter.

In the following example, the values for the formal country parameter is set to automatically fill in the default value for that parameter.

// Retrieve a default value to display for the parameter based on the value of
// another dependent parameter, for example 'country'.
def selectedValue = args.parameters['country']
// Note: You also need to declare a dependency on the 'country' formal parameter
// from this formal parameter to enable the UI to trigger a retrieval of a default value
// for this formal parameter whenever the user changes the 'country' formal parameter value.
if (selectedValue == 'US') {
  return 'Washington'
} else if (selectedValue == 'Ukraine') {
  return 'Kyiv'
}
return ''▼

Enter options — Select + Add Option to add a new row. Type in the text and value for each option. The text is what will be displayed in the menu, and the value is the parameter value if that option is selected.
Load options from list — Enter a pipe-separated list of options (for example, foo\|bar\|baz ). The text and value for the options will be the same.
Load options from properties — Enter the path to the property sheet that contains options for the parameter. You must create the property sheet in a specific format:
- An optionCount property must exist whose value is the number of options.
- For each option, create a nested property sheet called option N, where N is the option number, starting with 1.
- In each nested sheet, create two properties — text and value. The value of the property text is displayed in the menu. The value of the property value is the parameter value if that option is selected.
- If optionCount is set to 3, you must create three nested sheets — option1, option2, and option3.

Load options using DSL — Enter a DSL script that creates radio buttons. You can use DSL to populate values from a URL. Refer to the dropdown parameter type for similar example.

View example 1: DSL script example for retuning parameter options.

import com.electriccloud.domain.FormalParameterOptionsResult

def options = new FormalParameterOptionsResult()

// Apply your custom logic to build the list of options to display

options.add(/*value*/ 'value1', /*displayString*/ 'Value One')
options.add(/*value*/ 'value2', /*displayString*/ 'Value Two')
options.add(/*value*/ 'value3', /*displayString*/ 'Value Three')

return options
}▼

View example 2: DSL script example for cascading parameter options.

For cascading parameter, you must declare a dependency for the formal parameter that the parameter options depend on.

import com.electriccloud.domain.FormalParameterOptionsResult

def options = new FormalParameterOptionsResult()

// Retrieve options to display for the parameter based on the value of
// another dependent parameter say 'country'.

def selectedValue = args.parameters['country']

// Note: You also need to declare a dependency on 'country' formal parameter
// from this formal parameter to enable the UI to trigger a retrieval of
// dynamic drop-down options for this formal parameter whenever the
// 'country' formal parameter value is changed by the user.

if (selectedValue == 'US') {
  options.add( /*value*/ 'CA', /*displayString*/ 'California')
  options.add( /*value*/ 'CO', /*displayString*/ 'Colorado')

} else if (selectedValue == 'Canada') {
  options.add( /*value*/ 'BC', /*displayString*/ 'British Columbia')
  options.add( /*value*/ 'ON', /*displayString*/ 'Ontario')
}

return options
}▼

View example 3: DSL script example for using a dependent parameter value.

In this example, radio button parameter is created to select releases from a given project. The project identified using the relProject parameter must be identified as a dependent parameter to this release name parameter. The release name list can be generated using the following DSL:

import com.electriccloud.domain.FormalParameterOptionsResult
def options = new FormalParameterOptionsResult()
def proj=args.parameters['relProject']
if (proj) {
  getReleases(projectName: proj).each { rel ->
    options.add(rel.releaseName,rel.releaseName)
  }
}
return options▼

Release - Parameter type

Creates a Release dropdown to select a release object. To use this parameter type, you must first provide a way for the user to select the object’s project via a Project, Dropdown Menu, or Text Entry parameter.

Not available for Dashboard or Report objects.

Text Area - Parameter type

Allows for a longer text entry.

Text Entry - Parameter type

Creates a short text entry field. You can select the Dynamic Default Value option to specify the default parameter value based upon other parameters that were added to dependencies. The Dynamic Default Value option is only available for parameters that have dependencies.

View an example of setting the default value for a formal country parameter.

In the following example, when a value for a formal country parameter is selected, the default value for that parameter is automatically filled.

// Retrieve a default value to display for the parameter based on the value of
// another dependent parameter, for example 'country'.
def selectedValue = args.parameters['country']
// Note: You also need to declare a dependency on the 'country' formal parameter
// from this formal parameter to enable the UI to trigger a retrieval of a default value
// for this formal parameter whenever the user changes the 'country' formal parameter value.
if (selectedValue == 'US') {
  return 'Washington'
} else if (selectedValue == 'Ukraine') {
  return 'Kyiv'
}
return ''▼

Default Value

Default value to assign to the parameter if no explicit value is provided.

Required

Select the checkbox to specify the parameter is required. A value must be provided for the parameter if it is required.

Defer expansion

Determines whether to defer parameter value expansion when the parameter value contains $[].

If unchecked (default), expansion is not deferred and is done at the time the parameter value is passed to the process, procedure, task, and so on, depending on where the parameter was defined.
If checked, expansion is deferred and occurs when the process step, procedure step, and so on, executes.

Custom validation

Provides run-time validation on parameters via a user-supplied DSL script. If selected, the Custom Validation dialog displays, allowing you to supply the validation DSL script.

If left empty, no validation occurs.

Select the tooltip icon Tool tip for this selection on the New Input Parameter dialog to see examples.

View example 1: DSL script example for custom validation logic.

// Apply your custom validation logic
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
}▼

View example 2: DSL script example for custom validation logic when a parameter depends upon another parameter.

For custom validation dependency logic, you must declare a dependency on the formal parameter that the validation logic is based upon.

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

if (selectedValue == 'US') {
  if (args.parameters['paramName1'] != 'CA' && args.parameters['paramName1'] != 'CO') {
    // return an appropriate error message in case the validation failed
    return "'paramName1' parameter value is not valid for selected 'country'"
  }
} else if (selectedValue == 'Canada') {
  if (args.parameters['paramName1'] != 'BC' && args.parameters['paramName1'] != 'ON') {
    // return an appropriate error message in case the validation failed
    return "'paramName1' parameter value is not valid for selected 'country'"
  }
}

// Return an empty string or null to indicate validation success
return null▼

Render condition

Render this parameter based on the condition of another parameter. For example, render this parameter if anotherparam equals 10.

If left empty, this parameter renders by default.

Select the tooltip icon Tool tip for this selection to see examples.

View render Condition examples where param1 is the driving parameter for rendering param2.

Render param2 only if param1 is set to 123

Render param2 if param1' is set to `123 and param2 is set to 1

Render param2 if param1 is not set to 456 or param3 is set to 123

`${param1} == '123'`: Render `param2`▼

`${param1} == '123' AND ${param2} == 1`▼

 `${param1} != '456' OR ${param3} == '123''`▼

Dependencies

One or more formal parameters this parameter depends on for custom validations or for rendering dropdown options using DSL. For an example, refer to createFormalParameter.

If left empty, this parameter renders by default.

Supported Shortcuts

You can use shortcuts in DSL arguments as:

A custom validation for all parameter types
Part of the DSL Load options using DSL for the Dropdown Menu and Radio Selector parameter types
The Default Value for the Dynamic Default Value argument for the Dropdown Menu, Radio Selector, and Text Entry parameter types

Refer to the following list of objects which can have formal parameters:

Table 1. Available shortcuts
Object	Supported shortcuts	Examples
Catalog item	/myCatalog /myCatalogItem /myProject	View example 1: Select parameter options: `import com.electriccloud.domain.FormalParameterOptionsResult def options = new FormalParameterOptionsResult() def prop1 = getProperty(propertyName: "/myProject/name") if (prop1) { options.add(prop1.value,prop1.value) } def prop2 = getProperty(propertyName: "/myCatalog/name") if (prop2) { options.add(prop2.value,prop2.value) } def prop3 = getProperty(propertyName: "/myCatalogItem/name") if (prop3) { options.add(prop3.value,prop3.value) } return options` ▼ View example 2: Validation DSL. `def catalogName = getProperty(propertyName: "/myCatalog/name") if (args.parameters['paramName1'] == catalogName.value){ return "'paramName1' parameter value is not valid" } else { // an empty or null response is construed as a validation success return null }` ▼ View example 3: Default value DSL. `def catalogName = getProperty(propertyName: "/myCatalog/name") if (args.parameters['country'] == 'US') { return 'Washington' } return catalogName.value` ▼
Pipeline	/myPipeline /myProject	View the example. `import com.electriccloud.domain.FormalParameterOptionsResult def options = new FormalParameterOptionsResult() def opt1 = getProperty(propertyName: "/myProject/DynParam/testProperty").value options.add(opt1,opt1) def opt2 = getProperty(propertyName: "/myPipeline/DynParam/testProperty") options.add(opt2,opt2) return options` ▼
Procedure	/myProcedure /myProject	View the example. `import com.electriccloud.domain.FormalParameterOptionsResult def options = new FormalParameterOptionsResult() def opt1 = getProperty(propertyName: "/myProject/DynParam/testProperty").value options.add(opt1,opt1) def opt2 = getProperty(propertyName: "/myProcedure/DynParam/testProperty") options.add(opt2,opt2) return options` ▼
FlowState (Pipeline Manual Task)	/myPipeline /myProject /myStage /myTask	View the example. import com.electriccloud.domain.FormalParameterOptionsResult def options = new FormalParameterOptionsResult() def prop1 = getProperty(propertyName: "/myProject/name") if (prop1) { options.add(prop1.value,prop1.value) } def prop2 = getProperty(propertyName: "/myPipeline/name") if (prop2) { options.add(prop2.value,prop2.value) } def prop3 = getProperty(propertyName: "/myStage/name") if (prop3) { options.add(prop3.value,prop3.value) } def prop4 = getProperty(propertyName: "/myTask/name") if (prop4) { options.add(prop4.value,prop4.value) } return options ▼

Rendered Parameters at Runtime

Here is the parameter list that defines several parameters for J-PIPELINE.

Figure 2. Parameter list

When a new pipeline run is started, the rendered panel for these parameters displays.

Figure 3. Rendered panel

There are four parameters corresponding to the four parameters pipeline list. Each has a tool tip with contents populated from the description in the parameter definition.

1	The header type parameter.
2	Radio selector type parameter. The three radio button choices are displayed, along with the Required notation.
3	Date type parameter. This parameter has a dependence on parameter #2. Clicking the value box brings up a date chooser. It is noted as Required.
4	Dropdown menu type parameter. Clicking the drop-down arrow expands the list.