预览

Active Choices 插件用于自由式Jenkins参数化工作创建脚本化、动态和交互式作业参数。主动选择参数可以动态更新，并可以呈现为组合框，复选框，单选按钮或丰富的HTML UI小部件。

主动选择参数使用Groovy编写脚本，或者(可选)Scriptler Groovy脚本。

这些定制脚本支持使用Jenkins Java API、系统环境变量、全局节点属性，以及可能的外部Java和Javascript库。

安装插件后，有三种新的参数类型可用:

1. 主动选择参数
2. 主动选择反应参数
3. 主动选择反应引用参数

NOTE: 反应引用参数允许参数以格式化的HTML形式显示。在使用此特性配置作业时，请记住参数将如何呈现，以及它是否会造成安全问题。

NOTE: 该插件的开发在很大程度上依赖于Jenkins UI的HTML/DOM。我们使用JavaScript导航DOM以创建参数之间的关系和反应性。

Follow JENKINS-63284 获得不需要UI的版本的更新。

当这个问题被解决后，插件应该可以很好地处理Pipelines、DSL、定timers器、cron、 REST-API-triggered jobs等等。

Active Choices parameters允许用户为作业参数选择值。参数值为:

• dynamically generated 动态生成 (使用Groovy或Scriptler脚本)
• dynamically updated based on other UI parameters基于其他UI参数动态更新
• multi-valued(可以有多个值)
• rendered with a variety of UI controls, including dynamic HTML 使用多种UI控件渲染，包括动态HTML

我们将通过简要描述其行为和呈现特征来介绍基于活动选择的UI控件。然后，我们将提供它们的配置指南。

Active Choices Parameter 主动选择参数

Behavior

• Active Choices参数使用Groovy脚本或Scriptler目录中的脚本动态生成构建参数的值选项列表。

Rendering

• Active Choices parameters 可以呈现为标准的选择列表、复选框和单选按钮。
• 可以选择显示文本框筛选器来帮助筛选值选项。
  

Active Choices Reactive and Reactive Reference Parameters

这两个参数都有其他有用的行为，Reactive Reference有一些独特的呈现选项

Behavior

类似于上面的 Active Choices Parameter:

• Active Choices Reactive 和 Reactive Reference parameters 使用Groovy脚本或Scriptler脚本动态地为构建参数生成值选项

此外:

• 当其他作业UI控件的值发生变化时，Active Choices Reactive 和 Reactive Reference parameters 可以动态更新(级联更新)

Rendering Options 呈现选项

Active Choices Reactive

• Active Choices Reactive parameters 可以呈现为标准的选择列表、复选框和单选按钮。
• 可以选择显示文本框筛选器来帮助筛选值选项。

Active Choices Reactive Reference

Active Choices Reactive Reference parameters 用于增强带有参考信息的Jenkins作业表单UI。

记住这个用例，Reactive Reference UI控件可以呈现为:

• An HTML list (bulleted or numbered)：HTML列表(项目符号或编号)
• An HTML input text box：一个HTML输入文本框
• Dynamically generated HTML (image, iframe, etc.)：动态生成HTML (image, iframe, etc.)

动态生成的HTML选项适用于Groovy脚本返回的任何格式良好的HTML。它能够呈现各种HTML元素，包括图片、内联框架、超链接、格式丰富的文本等。

此外，Reactive Reference parameters可以从UI中隐藏，从而提供动态生成隐藏构建参数的选项。这些选项将在Reactive Reference configuration一节中进一步讨论。

Rendering Example 呈现示例

在上面的例子中，当“Gender”参数改变时，“Professions”参数的值选项也会更新。

此外，当“Gender”参数更新时，作为图片呈现的 Reactive Reference parameter “Gender_Balance”也会动态更新。

Behavior and Rendering Summary 行为和呈现摘要

下表总结了三种 Active Choices parameter 类型的行为和呈现特征.

Active Choices Parameter Type Configuration

插件中包含以下参数:

• Active Choices Parameter
• Active Choices Reactive Parameter
• Active Choices Reactive Reference Parameter

现在我们来描述它们的配置细节。

Active Choices Parameter: Configuration Options (Example 01)

An Active Choices Parameter 通过在参数配置中设置以下选项来配置

The ‘Name’ and ‘Description’

这些是典型的参数名称和描述，对所有Jenkins参数都是常见的

The ‘Script’

‘Script’ 是会动态生成参数值选项的 Groovy 代码 或 Scriptlet 脚本

• 通过选择这两个单选按钮选项中的任何一个，您可以直接键入Groovy脚本，也可以使用Scriptler脚本
• 脚本必须返回一个 java.util.List, 一个 Array（数组） 或者一个 java.util.Map，如下例所示:

    return ['Option 1', 'Option 2', 'Option 3']

The ‘Fallback Script’

The ‘Fallback Script’ 配置选项提供了备用的参数值选项，以防主脚本因抛出异常或不返回 java.util.List, Array or java.util.Map 而失败。

The ‘Choice Type’

’Choice Type’ 选项为选项值提供了四种不同的呈现选项:

1. 允许单个选择的列表框
2. 允许多个选择的列表框
3. 复选框列表(允许多个选择)
4. 单选按钮列表(允许单个选择)

The ‘Enable Filter’

The ‘Enable Filter’ 选项将在UI控件中提供一个文本框过滤器，可以在其中输入文本过滤器，然后只列出包含文本的值选项。

这个 filter（过滤器）是独立于控件之外的。

Active Choice Parameter Rendering (Example 01)

The Example 01 Active Choice parameter 配置生成以下构建表单UI控件。用户可以从一个可筛选的下拉列表中选择一个“State”选项。

Making ‘Default’ selections

当控件初始化时，可以默认选中 Active Choices UI control 中显示的一些选项.

您可以通过添加后缀来定义缺省值选择，从脚本返回的元素中选择要作为默认选择的元素.

在下面的例子中，当参数UI控件呈现时，我们将“Parana”状态作为默认选择。

Making ‘Disabled’ selections

您还可以通过添加后缀来定义禁用的选择;

添加 :disabled 到您希望禁用的元素.

在下面的示例中，我们将使各种元素被禁用和不可更改。

然后你会发现，:selected 和 :disabled 能够同时被选中.

我们将 Active Choices 的实现归功于 Dynamic Parameter plugin（动态参数插件）的开发人员的一些初始概念和代码。

然而，Active Choices 插件和原来的 Dynamic Parameter 插件之间有几个重要的区别和改进:

1. Active Choices 参数可以呈现为一个多选择控件(组合框或复选框)，允许用户为该参数选择多个值
2. **可以筛选参数选项值列表。**如果 “Enable Filters” 选项被选中了，将显示一个额外的输入框，允许用户筛选选项。
3. 如果值生成器脚本引发异常，可以定义一个’fallback’行为。
4. 可以在动态生成的值列表中定义默认值选择

Active Choices Reactive Parameter: Configuration Options (Example 02)

Active Choices Reactive 参数配置了一组与上述活动选项参数类似的选项。 但是，Reactive 参数提供了附加的“Referenced parameters”配置选项。

• This option, takes a list of job parameters that trigger an auto-refresh of the Reactive Parameter when any of the ‘Referenced parameters’ change
• 此选项接受一列作业参数，当任何“引用参数”发生更改时，该作业参数将触发响应性参数的自动刷新

The ‘Referenced parameters’

“Referenced parameters”文本字段包含一列逗号分隔的参数名称(来自当前作业)，当它们的值发生变化时，将触发响应性参数的刷新。

在重新执行脚本之前，这些参数的值被传递给脚本绑定上下文，以便为Active Choices控件生成一组新的选项值。

Active Choices Reactive Parameter Rendering (Example 02)

让我们检查一下使用Active Choices Reactive 参数呈现的Jenkins构建表单，该表单满足以下需求。

The form:

• 允许用户选择几个巴西州之一
• 提供一个附加控件，其中动态显示属于所选状态的一组城市
• 允许用户选择一个或多个显示的城市

Job UI由两个参数组成:

1) States: An Active Choice Parameter

第一个参数是States 示例01中的Active Choice 参数. 它允许用户选择几个巴西州之一。
我们也可以简单地使用Jenkins选择参数，但是我们使用了 Active Choice 参数(如示例01所示)。用于此的Groovy脚本是:

return[
'Sao Paulo',
'Rio de Janeiro',
'Parana',
'Acre'
]

2) Cities: An Active Choices Reactive Parameter

第二个参数是 Cities，Active Choices Reactive Parameter 该参数动态显示一组属于所选状态的城市，并允许用户选择多个值。城市参数配置如上例02所示。

注意：

• 城市Reactive 参数引用前面定义的状态参数(‘Referenced parameters’=States);
• The ‘Choice Type’ 被设置为复选框。这将允许用户通过选择多个复选框来选择一个或多个城市。
• 一个自定义的 ‘Groovy Script’ 将用于生成如下所示的城市值选项(脚本返回的最后一个列表值)

if (States.equals("Sao Paulo")) {return ["Barretos", "Sao Paulo", "Itu"]
} else if (States.equals("Rio de Janeiro")) {return ["Rio de Janeiro", "Mangaratiba"]
} else if (States.equals("Parana")) {return ["Curitiba", "Ponta Grossa"]
} else if (States.equals("Acre")) {return ["Rio Branco", "Acrelandia"]
} else {return ["Unknown state"]
}

每当用户更改States参数的选项时，Cities参数将得到动态更新。注意，状态引用参数是如何在脚本绑定中使用的，并且可以直接使用。

您可以使用反应性参数类型来处理一些事情，比如显示给定的组ID的Maven工件列表。

Active Choices Reactive Reference Parameter: Configuration Options

A Reactive Reference parameter 配置了一组类似于上面所示的Active Choices Reactive参数选项。

但是， Reactive Reference 参数提供了一组独特的呈现选项 (see ‘Choice Type’).

• Input text box：输入文本框
• Numbered list：编号列表
• Bullet items list：项目列表
• Formatted HTML：格式化的HTML
• Formatted Hidden HTML：格式化隐藏HTML

鉴于各种各样的呈现选项，Active Choices Groovy脚本必须为每个选项返回以下类型的变量:

Choice Type	Groovy Returns	Comment
Input text box	String	返回的字符串出现在一个简单的文本框中
Numbered list	List	返回列表显示为一个编号列表
Bullet items list	List	返回列表显示为项目符号列表
Formatted HTML	String	返回的字符串必须是格式化良好的HTML才能正确显示。你可以在这里加入任何HTML标签，例如：一些<table>，或者是另一个网站的 <form>
Formatted Hidden HTM	String	参数不会在UI中显示

Reactive Reference 参数的典型应用程序是动态显示参考信息，可用于指导用户对另一个作业参数进行适当的值选择。

按照设计，除了一个重要的例外，Reactive Reference 参数的值不会传递给构建环境。当选择类型被设置为格式化HTML或格式化隐藏HTML，并且HTML是一个“输入”元素时，值可以被传递给构建。

参见“高级用法”一节了解更多说明。

Example Configuration: Active Choices Reactive Reference Parameter

我们展示了3个具有不同选择类型的反应性引用示例，以及在Jenkins job UI中相应的呈现。

考虑这样一个例子，用户需要选择一种食物来补充可用的葡萄酒。如果能提供一些有用的参考信息，用户在选择特定的葡萄酒时就会更加容易。我们将此引用信息称为WINE_RULE，并且可以使用反应性引用变量轻松实现它。

当用户从WINE_MENU中进行新选择时，WINE_RULE会自动更新(注意引用的参数=WINE_MENU)。因此，当我们做一个WINE_MENU选择时，我们还会得到一个WINE_RULE来指导FOOD_MENU 的选择。

Reactive Reference Configuration (Example 03)

WINE_RULE参数的完整配置如下所示。

Reactive Reference Groovy script (Example 03)

为每个选项生成WINE_RULE 格式化的HTML的groovy脚本如下所示。

switch(WINE_MENU){case~/.*Champagne.*/:winerec='Champagne is perfect with anything salty'return "<b>${winerec}</b>"break
case ~/.*Sauvignon Blanc.*/:winerec='Sauvignon Blanc goes with tart dressings and sauces'return "<b>${winerec}</b>"
breakcase~/.*Grüner Veltliner.*/:winerec='Choose Grüner Veltliner when a dish has lots of fresh herbs'return "<b>${winerec}</b>"break
case~/.*Pinot Grigio.*/:winerec='Pinot Grigio pairs well with light fish dishes'return "<b>${winerec}</b>"break
case ~/.*Chardonnay.*/:winerec='Choose Chardonnay for fatty fish or fish in a rich sauce'return "<b>${winerec}</b>"
breakcase~/.*Off-Dry Riesling.*/:winerec='Off-Dry Riesling pairs with sweet & spicy dishes'return "<b>${winerec}</b>"breakcase~/.*Moscato dAsti.*/:winerec='Moscato dAsti loves fruit desserts'return "<b>${winerec}</b>"break
case ~/.*dry Rosé.*/:winerec='Pair a dry Rosé with rich, cheesy dishes'return "<b>${winerec}</b>"
breakcase~/.*Pinot Noir.*/:winerec='Pinot Noir is great for dishes with earthy flavors'return "<b>${winerec}</b>"break
}

Advanced Usage Notes 高级用法说明

编写Groovy脚本时的注意事项

你的Groovy脚本绑定可以使用另外两个变量:

• jenkinsProject -> Jenkins项目对象
• jenkinsBuild -> Jenkins构建对象

将 Reactive Reference 值传递给构建

如前所述，Reactive Reference 参数的值通常不会传递给构建。但是，在一些场景中，传递这些值的能力是很有意义的。

有关此特性的更广泛讨论，请阅读这里here.

场景1:传递一个可由用户编辑的动态创建的值

在这个场景中，我们希望为用户提供一个可编辑的动态默认值。这可以通过以下反应性参考配置来实现:

• 选择类型： Formatted HTML
• Groovy脚本返回一个带有动态默认值的HTML输入元素
• 高级选项设置为
  

场景2:传递一个动态创建的值，该值是隐藏的(用户不能编辑)

在这个场景中，我们希望构建能够访问UI中由用户输入/选项选择生成的动态参数。该参数是通过编程方式创建的，不能由用户编辑。这可以通过以下反应性参考配置来实现:

• 选择类型: Formatted Hidden HTML

• Groovy脚本返回一个带有动态默认值的HTML输入元素

• 高级选项设置为
  

  当你想要计算在构建中使用的值时，一个“Formatted Hidden HTML”选择类型是有用的，但是这些值不应该被用户修改(例如。来计算部署URL)。

  在这两种情况下，groovy脚本都必须返回格式化如下的HTML元素:

  return "<input name=\"value\" value=\"${ReactiveRefParam}\" class=\"setting-input\" type=\"text\">"
  

    **ReactiveRefParam** is the Reactive Reference value that will be passed to the build#### Scenario 3: Create an input control with dynamic HTML and pass its value to the buildThis is an interesting application of the Reactive Reference parameter. It allows you to create custom UI parameter controls with improved interactivity. See [example](https://wiki.jenkins-ci.org/display/JENKINS/Reactive+Reference+Dynamic+Parameter+Controls)### Advanced Option: Omit Value FieldBy default Reactive References pass to the build a hidden \<input name="value" value=""\>. It means that your Reactive Reference parameter will always be empty, but you can use a Formatted HTML parameter and instruct the plug-in to not include this hidden value parameter.You can click the Advanced button and there you will find an option to omit the value field. This will you let you define a value for the hidden parameter.![](https://wiki.jenkins.io/download/attachments/74875908/ACR_c03_advanced.gif?version=1&modificationDate=1435933116000&api=v2)### Using Active Choices with Scriptler scriptsWe assume users that need to use Scriptler generated parameters are already familiar with the Scriptler Plug-in. If you need further information on how to use the Scriptler Plug-in, please refer to [its Wiki page](https://wiki.jenkins-ci.org/display/JENKINS/Scriptler+Plugin) first.Similarly to a Groovy script, a Scriptler script is also written in Groovy and used to render the parameter. Your Scriptler script is also expected to return a java.util.List, Array or java.util.Map for Active Choices and Reactive parameters, or custom HTML elements for the Reactive Reference parameter. Note that the value of other build parameters (when using Scriptler in combination with Active Choices) will be available in the Scriptler script context. You do not need to define such parameters in the Scriptler interface, or during the job definition. However, **the main advantage that the Scriptler Plug-in** provides is the creation of a **reusable** **Groovy script catalog** that can be used across multiple jobs or even for automation.To make your Scriptler scripts reusable across multiple projects you should parameterize them and assign script parameters using build parameters.#### Example`Environments.groovy` in Scriptler​```syntaxhighlighter-pre
return ["Select:selected", "DEV", "TEST", "STAGE", "PROD"]

HostsInEnv.groovy in Scriptler

// Static content examples. These lists can be generated dynamically as an alternative.
List devList    = ["Select:selected", "dev1", "dev2"]
List testList   = ["Select:selected", "test1", "test2", "test3"]
List stageList  = ["Select:selected", "stage1"]
List prodList   = ["Select:selected", "prod1", "prod2", "prod3", "prod4"]List default_item = ["None"]if (Environment.equals('DEV')) {return devList
} else if (Environment.equals('TEST')) {return testList
} else if (Environment.equals('STAGE')) {return stageList
} else if (Environment.equals('PROD')) {return prodList
} else {return default_item
}

Pipeline in Jenkinsfile

properties([parameters([[$class: 'ChoiceParameter',choiceType: 'PT_SINGLE_SELECT',name: 'Environment',script: [$class: 'ScriptlerScript',scriptlerScriptId:'Environments.groovy']],[$class: 'CascadeChoiceParameter',choiceType: 'PT_SINGLE_SELECT',name: 'Host',referencedParameters: 'Environment',script: [$class: 'ScriptlerScript',scriptlerScriptId:'HostsInEnv.groovy',parameters: [[name:'Environment', value: '$Environment']]]]])])pipeline {agent anystages {stage('Build') {steps {echo "${params.Environment}"echo "${params.Host}"}}}
}

Filter Supports Regular Expressions 过滤器支持正则表达式

请注意，尽管可用于活动选项参数的文本“Filter”框通过简单地键入一些文本提供了简单的不区分大小写的过滤，但它还支持使用正则表达式进行更复杂的过滤。

下面的示例展示了使用正则表达式筛选复杂选项列表的示例：

Security 安全

Active Choice versions before v2.0 使用可能不安全。在使用旧版本之前，请查看以下警告:

• Arbitrary code execution vulnerability：任意代码执行漏洞
• Stored cross-site scripting ulnerability：存储跨站点脚本易损性

从 Active Choices v2.0 开始，用于Active Choices Reactive Reference Parameter 的 沙箱 Groovy 脚本将不再提出认为HTML是不安全的，例如 <script> 标签.

这可能会在 Build With Parameters 表单上导致n个行为改变，比如缺少元素。

要解决这个问题，需要将Groovy脚本发出的HTML配置为在脚本安全沙箱之外运行，可能需要在***进程内脚本审批***中单独进行管理员审批。

Active Choices 将额外加载两个文件：Javascript files, JQuery and unochoice.js.

Languages Supported 支持的语言

1. English
2. Portuguese (Brazil)) Work in Progress
3. If you want to include yours, send us a pull request with the messages.properties files or get in touch!

Known Limitations 已知的限制

1. 这些参数应该只由人来处理，而在由插件、API或脚本触发作业时，它们并不工作。
   • Please see this issue for more.
2. 在归档问题之前，请查看故障排除页面： Troubleshooting Page