Jira自动化的实用工具——ScriptRunner简介及最佳实践

近日，龙智举办的DevSecOps研讨会年终专场“趋势展望与实战探讨：如何打好DevOps基础、赋能创新”在上海圆满落幕。龙智Atlassian技术与顾问咨询团队，以及清晖、JamaSoftware、CloudBees等生态伙伴的嘉宾发表了主题演讲，分享他们在DevOps领域的丰富经验与独到见解，并围绕Atlassian最新产品趋势与Jira、Confluence等工具的最佳实践，展开了深入探讨。

本篇文章回顾龙智技术总监李毅的演讲，聚焦于Jira的实用插件ScriptRunner，分享如何使用ScriptRunner拓展Jira的功能、ScriptRunner的重要功能模块以及最佳实践。

演讲回顾

如何在Jira中进行团队成本与时间管理

大家好，我今天将分享如何使用ScriptRunner扩展Jira的功能，内容主要分为四个部分。

首先，我将介绍ScriptRunner是什么样的产品，让大家对其有一个整体的认识。

第二部分，我将详细讲解ScriptRunner中各个功能模块的作用，以便在为业务方提供解决方案时能够有所参考，知道应该使用ScriptRunner中的哪个模块来实现目标。

第三部分是实践经验总结。我会分享在实践和为客户提供解决方案过程中积累的一些经验，推荐一些实用做法，并提供注意事项，以便大家应用ScriptRunner时能够轻松上手。

最后，我将总结一些在Jira中通用且重要的模块，以及在为客户提供服务时经常出现的使用场景。

ScriptRunner——针对Jira自动化、定制功能及扩展的解决方案

首先，我们来快速了解一下ScriptRunner是怎样的产品。ScriptRunner主要利用Groovy脚本的强大功能，实现了Jira Software和Jira Service Desk本身无法实现的功能；以及从自动化，批量操作，构建自定义工作流，到第三方系统集成，ScriptRunner赋予Jira管理员超强的扩展能力。

它的主要优势是一体化、功能强大以及降本增效。作为一个产品，它包含了多个功能模块，几乎涵盖了用户可能需要的所有功能。相比购买多个插件，我们推荐首选ScriptRunner，因为它的功能丰富且实用。其次，它的功能强大，特别适用于构建复杂的自动化工作流，以减少人工成本。此外，它还能帮助团队实现降本增效，能够通过简单的脚本来支持业务需求，而无需进行定制化插件开发。

ScriptRunner的主要特点包括自动化、高度定制化、可扩展以及提升用户体验。它不仅能够满足各种自动化需求，还能够根据不同行业的特殊要求进行高度定制，以满足业务场景的需求。同时，它的拓展性也非常好，能够轻松实现与Atlassian体系中的其他工具的集成，也可以通过RestAPI的方式与其他异构系统进行数据交互。无论是Jira管理人员还是日常使用Jira的用户，都能够充分体验到其强大的功能。

ScriptRunner功能模块

让我们一起浏览ScriptRunner的各个功能模块，了解它们的主要用途。

1、控制台——Script Console。控制台主要用于编写试验性的脚本或进行一次性功能验证。用户可以在此处执行定期清理用户、查询Issue数据、项目数据等任务，并查看结果。此外，用户还可以在控制台学习和测试Jira REST API和HAPI，非常方便。

2、Built-In Scripts，该模块集成了许多内置的通用性脚本，提供了许多实用功能，例如批量操作用户、批量操作Issue、查看日志、切换日志等。对于不太熟悉Groovy脚本编写的用户，建议先查看内置脚本，看是否已经满足需求。

3、Listeners，顾名思义，它用于监听Jira中发生的事件，并在捕捉到事件后执行特定的脚本处理。

4、Jobs允许您定期自动的运行脚本，从而节省管理员的时间，并降低人工执行的风险。

5、Script Fields就是所谓的脚本字段，它使用Groovy脚本计算或合并来自一个或多个现有字段的数据，并将它们展示在自定义字段中。通常用来展示扩展的Issue信息。

6、Behaviours行为模块，是Script Fields的特有模块，也是最重要的模块之一。它用于控制Issue界面上字段的行为，使得用户可以根据需要定制化业务场景和流程。

7、Workflows也是常用模块之一，主要通过Script Conditions、Script Validators和Script Post Functions来增强和自动化工作流程。

8、Script Fragments主要与定制化UI相关，可以添加按钮、Web图标等。

9、JQL Functions扩展了Jira的内置功能，允许您进行更精细的搜索操作，以快速获取项目/问题的更详细信息。

10、REST Endpoints模块主要利用Groovy脚本迅速定义REST Endpoints，并可以与企业内部协同使用的工具集成并交互数据，例如从HR系统拉取用户数据或从其他需求管理平台获取项目的任务开发进度等。

11、Resources模块可建立本地或外部数据库的链接，以及Ldap用户管理的链接。一旦建立了连接，在其他场景编写脚本时都可以直接使用，通过内置的BaseUtil和LdapUtil工具类，可以轻松获取所需的数据。

12、最后是Mail Handler模块，虽然使用频率不高，但在用户接收邮件时执行指定操作时非常有用。

ScriptRunner最佳实践

动态表单

在实际为客户提供解决方案时，我们总结了一些使用ScriptRunner的好方法和注意事项。

我想推荐大家尝试使用Dynamic Forms（动态表单）功能。动态表单允许创建的脚本带有一些需要用户动态输入的参数，从而增强了脚本的通用性。Dynamic Forms可以保存脚本，并且带有注释，即使对代码不太了解的用户也可以理解脚本的用途，提高了易用性。你可以编写一个通用型的脚本，在多个地方都能派上用场，因此我强烈推荐大家使用动态表单功能。

我编写了一个简单的示例，以便大家了解这个概念。这个示例包含一个带有"注释"的变量，称为"user Picker"。它可以通过这种方式将变量绑定到用户上，当用户使用这个脚本时，就可以动态输入用户变量。这个脚本的实际功能非常简单，它通过JQL查询“经办人等于输入的用户变量”的所有Issue并进行批量操作。这样的脚本具有通用性，每个人都可以动态输入想要的用户变量参数。

这只是其中一个示例。实际上，动态表单可以支持Jira中绝大多数的字段类型，包括Issue、Group、Project等，甚至各种工作流方案和权限方案。你可以选择并基于它编写通用性的脚本。

HAPI

我也强烈推荐大家使用HAPI。HAPI是ScriptRunner扩展出的便捷API，它实际上是基于Jira脚本的，但做了一层紧凑的封装，进一步降低了用户的使用门槛。使用HAPI不需要对Jira过于熟悉。

通常情况下，按照JavaAPI的方式编写脚本会比较繁琐。但是，直接使用HAPI会更为简洁。

接下来我会举几个例子，大家可以体会一下。使用HAPI相对来说门槛非常低，而且编辑器中针对HAPI提供了很多代码提示功能。只要按照提示编写，基本上都会有相应的建议。这降低了很多用户的使用门槛，因此我也非常推荐大家在编写脚本时尽量使用HAPI。

简单举几个例子。首先是创建Issue，非常简单，只需一句话。你可以在Console中执行一下代码，它会在“ABC”项目下创建一个类型为“Task”的Issue，其摘要为“my first HAPI”。相比使用Java API来编写，这种方式更加简单。

接下来是批量搜索Issue的写法，同样也非常简单。直接使用JQL语句，甚至可以通过filter进行过滤。我们可以限制返回的条数。

以下是关于用户的一些例子。可以看到，创建用户也非常简单，只需使用users.即可，后面的信息就是用户名、邮箱和全名。通过Users.getByName就能获取到相应的用户信息。users.的使用非常广泛，它提供了许多提示，内置了许多实用的函数。而projects.则提供了与项目相关的功能提示。

因此，我非常推荐大家尝试使用HAPI来编写代码，便捷高效。

以下是关于几个泛用性高的模块的推荐用法以及使用过程中需要注意的事项。

首先是特色功能——Behaviours。Behaviours通常用于用户界面，包括新增、编辑、转换界面等。它也可用于JSM的portal端。如果您正在使用JSM产品，并且需要在portal端定制字段的行为，也可以考虑使用它。

Behaviours通常用于字段的必填校验，只读控制，显示/隐藏控制，以及字段的选项动态变动，字段联动等。在使用过程中，要避免多个Behaviours脚本同时控制同一个字段的情况。需要做好控制范围，确保字段不会受到多个脚本的影响。此外，Behaviours不适用于批量操作，也不支持移动Issue界面。

它还支持项目类别的映射。通常情况下，脚本的控制范围是通过项目和问题类型映射来实现的。如果我们利用ChangeEvent事件，并在此事件中使用MappingService进行映射。那么我们就可以实现脚本对项目类别的范围控制了。

最后，Behaviours不支持插件扩展的自定义字段，但可以通过Vendors API进行兼容。Vendors指的是Marketplace上的供应商，他们通常会提供免费的API。因此，如果您希望扩展出的自定义字段也受到Behaviours的控制，可以考虑集成该API进行扩展。

最后，让我们来谈谈Script Fields。Script Fields主要用于只读字段，它也集成了许多内置的脚本字段，可以满足大部分业务场景的需求。

例如，“No. of Times In Status”（状态次数），这个字段可以统计Issue进入指定状态的次数。在实际应用中，这个功能可以在很多地方发挥作用，比如一个工作流中反复进入某个状态，我们可能需要统计这个状态的次数。例如，在测试中，如果一个bug被反复打开，可能就存在问题，我们可以利用这个脚本字段来统计这种情况。这些指标可以帮助我们后续进行跟踪和分析。

另外一个常见的自定义场景是业务方有自己特殊的业务逻辑。典型的例子包括问题严重度字段的实时计算，这需要根据其他字段的值通过一定的业务规则计算后得出；或者是Issue的评分，通常也是依赖于其他字段并进行业务规则计算得出的。Script Fields通常在这些自定义场景中使用。

ScriptRunner客户案例

接下来，我将分享一些重要模块的具体实际案例，供大家参考。当大家在工作中遇到类似的场景时，可以考虑通过这些方式去实现。

Behaviours

首先是Behaviours，它主要的适用场景是在创建、编辑和转换界面中增加字段的行为逻辑(业务规则)，相当于定制化业务规则。

• 当字段A选择某选项时，字段B显示并且必填；

• 字段A和字段B有联动效果，如：字段A选择了 "上海"，字段B的选项值变为 "徐汇区"，"普陀区";

• 校验字段A的日期和字段B的日期间隔不能超过60天；

• 校验字段A的日期不能早于字段B ；

• 限制字段A的编辑权限，只有用户组a中的用户才可以编辑，其他用户都是只读；

• 限制某些问题类型的创建；

• 当issuePicker字段A选择一条Issue后，自动将字段B的值变更为该Issue中某个字段的值；

Custom Listener

然后是Custom Listener模块，也是非常重要的。它适用于在发生特定事件时需要执行相应的处理逻辑的场景。

• IssueA和IssueB有链接关系，当IssueA字段更新时，将对应的字段值同步到IssueB；

• 当Issue中的模块发生变化时，将Issue的经办人修改为该模块的负责人;

• IssueA和IssueB有链接关系，当IssueA状态变化时，将状态同步到IssueB；

• 当Issue经办人变更时，给自定义字段赋值；

• 当IssueA字段更新时，同时更新动态表单IssuePicker选择的Issue中相关字段值；

• 当Issue中的字段、状态发生变化时，产生邮件通知或添加评论。

Workflows

Workflows也是一个被广泛使用的模块。它的适用场景是定制化专属的工作流以及自动化业务流程。我们分别从condition、validator和post-function来讨论几个典型的业务场景。

Custom script condition：

• “问题等级”字段为S级时，需要负责人审批，其他问题等级则不需要；

根据“问题严重度”字段值的不同，执行不同的工作流。

Custom script validator：

• 若“项目负责人”字段为空时，Issue 必须停留在原状态，工作流往下流转时需要给出错误提示。

Custom script post-function：

• Issue 创建成功后，自动将经办人设置为经办人的主管，并且发邮件通知；

• Issue 最终完成时，自动给“最终完成时间”字段赋值。

Script Field

最后再谈一下脚本字段，它的适用场景是字段只读并且字段值依赖其他字段自动计算或统计。通用场景有：

• 脚本字段A的值是根据字段B、字段C 的值，按照业务规则自动计算所得；

• 脚本字段A的值根据Issue进入Open状态后的天数统计得到。

总结一下今天演讲的主要内容：如果您要使用ScriptRunner，重点关注Behaviours、Listeners、Workflows以及Script Fields这几个模块。将精力集中在这些模块上，再加上动态表单和HAPI的使用，就可以解决绝大部分的问题。如果大家还有其他问题解决不了，可以联系Atlassian全球白金合作伙伴——龙智，我们将提供优秀的解决方案，帮助你们达到目标。

我今天的分享就到这，谢谢大家！