拦截工作项属性修改
适用环境 | SaaS |
私有部署 |
要求
ONES |
---|
v3.7.54+ |
概述
当你希望在工作项属性变更时做一些处理和校验,可以通过使用工作项处理器能力来实现需求。该能力能够在系统产生工作项更新事件时,对事件做前置处理、校验和后置通知。当安装了使用该能力的插件后,工作项更新事件会在处理之前先由 插件进行前置处理,插件可根据需求对本次事件采取忽略、拒绝和修改等操作;而在事件处理完成之后,插件会收到一个通知,此时可进行一些后置的处理。
适用场景:
- 工作项的某个属性或者状态在更改时有限制,例如不允许更改需求类型的工作项修改标题。
- 在工作项属性更改完成后,执行后置操作。例如更新了需求类型的工作项负责人之后,给对应的人员发送邮件。
使用范围
-
已覆盖
包括工作项属性、脚本属性、状态的变化;
包括标品前端操作以及直接调用接口产生的事件;
-
未覆盖
不包括评论、上传文件等不直接改变属性/状态的操作;
不包括计算属性如停留次数、间隔时间等的变化;
不包括后置动作触发的变动;
不包括工时的处理(工时是一个单独的
item
类型,在后续能力中增加对应的类似能力);不包括非正常流程修改状态的功能所触发的状态变更;
触发点
- 工作项详情页面进行属性或状态修改
- 批量修改工作项属性
- 批量变更工作项类型
能力表现
使用工作项处理器能力配置不允许修改需求负责人,修改需求负责人时 报错
使用
当 ONES 启用了使用工作项处理器能力的插件后,工作项属性和状态变更事件执行流程如下图所示:
第一步:添加配置
使用 npx op add ability
添加task-event-handler
能力。添加之后会新增backend/src/task-event-handler.ts
文件,在配置文件中新增了以下配置。
开发者只需要关注的工作项类型和工作项属性两个配置,支持配置多个工作项类型和工作项属性,多个配置之间以 "," 分隔。
示例配置: 表示关注需求和缺陷的工作项类型,关注截止日期和负责人的工作项属性的更改事件。
abilities:
- id: de265bd9-9otf
name: 工作项处理器
abilityType: TaskEventHandler
version: 1.0.0
function:
taskActionDoneFunc: taskActionDone
taskPreActionFunc: taskPreAction
config:
- fieldType: Input
key: issueTypeScope
show: true
label: '工作项类型'
value: '需求,缺陷'
- fieldType: Input
key: field
show: true
label: '工作项属性'
value: '截止日期,负责人'
第二步:添加前置处理
backend/src/task-event-handler.ts
文件中会自动生成taskPreAction
函数,该函数是前置处理函数,在事件生效前会先调用该函数,并根据返回内容采取不同的策略。
-
返回内容
taskPreAction
函数返回内容的结构体如下所示,根据is_follow
、is_reject
和task_events
字段的值采取不同策略:- 忽略:设置返回的
is_follow = false
,表示插件不做额外处理,更新事件按正常流程执行。 - 拒绝:设置返回的
is_follow = true && is_reject = true
,表示不执行此次更新事件,直接结束。 - 接受:设置返回的
is_follow = true && is_reject = false
,表示接受此次事件,但不修改此次更新内容,只在事件完成之后通知插件。 - 修改:设置返回的
is_follow = true && is_reject = false
并通过返回task_events
对象添加属性修改,表示接受此次事件,对此次的更新内容进行修改并在事件完成之后通知插件。
- 忽略:设置返回的
即使在插件逻辑中不需要增加新的修改,也需要把原来的task_events
字段的数据返回,否则变更事件可能失败
type taskPreResponse = {
statusCode: number
body: {
code: number
body: {
is_follow: boolean
is_reject: boolean
reject_reason: string
task_events: any
other_data: string
}
}
}
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
is_follow | string | 是 | 是否关注 |
is_reject | string | 是 | 是否拒绝 |
reject_reason | string | 否 | 拒绝原因 |
task_events | []TaskEvent | 是 | 变更的数据(插件可以添加变更属性值) |
other_data | interface | 否 | 其他数据(该数据会传递到 taskActionDone 方法) |
-
入参介绍
在函数入参的请求体中包含以下内容:
参数 类型 是否必填 描述 user_uuid string 是 用户 uuid
lang string 是 当前用户语言 task_events []TaskEvent 是 变更的数据 TaskEvent
参数 类型 必填 说明 task_fields []TaskEventField 是 变更属性列表 task_uuid string 是 工作项的 uuid
action string 是 update
: 普通属性transit
:状态变更(带有步骤属性)change_issue_type
:工作项类型变更publish_version
:版本发布add
: 新建工作项issue_type_scope_uuid string 是 在所属项目下工作项类型 UUID issue_type_scope_name string 是 工作项类型在项目下的名字 issue_type_scope_name_map map[string]string 是 issue_type_scope
在各个语言版本的名称TaskEventField
参数 类型 必填 说明 field_uuid string 否 属性 uuid
field_type string