# 前言
这里介绍如何扩展你的自动化助手自定义功能。在开始之前，你需要先创建一个托管应用，如果还没有请参考教程 (opens new window)
# 了解自动化助手
# 自动化助手是TAPD推出的业务规则平台，提供开放灵活的规则指令，简洁易用的配置， 用「触发条件 + 执行动作」的方式进行编排和执行 ，
# 帮助用户处理繁琐流程，提升跨平台协作效率。
更多请参考自动化助手介绍 (opens new window)
# 扩展能力支持
自动化助手分为Trigger（事件触发）、Condition（条件匹配）、Executor（执行动作）三大模块
# 配置文件示例
app:
code: demo
name: demo
desc: demo
icon: demo
tag:
- name: demo
envs:
- key: API_SECRET
secret: strings
modules:
autotasks: # 配置自动化任务扩展
- code: AutoDemo # 自动化任务对象标识，建议使用能标识扩展系统的code，需要跟现有保持一致
name: AutoDemo
icon: business # 扩展显示的图标，目前支持icon: business
search:
handler: item.get # 获取单个对象的实现
trigger: # 自动化任务事件扩展
events:
- code: trigger_demo # 自动化对象 - 事件标识
desc: 由xxx事件触发
icon: execute
name: 触发器demo
event_change: # event_change 用来扩展事件的格式转化
handler: trigger.change
option: # 事件配置时的组件可选值
handler: trigger.option
related: # 配置支持触发的类型
- 'story::field_change'
- 'bug::field_change'
executors: # 执行节点扩展
actions:
- code: change_demo_field # 执行节点标识Code
name: 变更Demo对象字段
icon: business # 扩展显示的图标，目前支持icon: business
desc: 变更Demo对象字段
option: # 执行节点组件配置可选值
handler: item.option
exec: # 执行节点执行操作
handler: item.update
related: # 该执行节点允许被哪些事件触发
- 'story::*'
conditions: # 条件扩展
- code: demo_condition # 条件对象code (普通字段校验condition)
name: 插件condiiton Demo #条件对象名
icon: business # 扩展显示的图标，目前支持icon: business
desc: 这是一个condition demo对象 # 条件对象描述
option: # 返回条件候选字段列表
handler: condition.option
data: # 返回字段值，用于条件判断
handler: condition.data
related: # 哪些trigger对象下可以配置这个条件判断
- 'story'
- 'bug'
- 'task'
- code: demo_condition2 # 条件对象code (特殊校验任务condition)
type: progress # 需要执行type，固定为progress
data: # 返回任务结果
handler: progress.data
option: # 返回任务列表
handler: progress.option
desc: 这是一个condition demo对象 # 条件对象描述
icon: progress # 扩展显示的图标，固定为: progress
name: 插件condiiton Demo2 #条件对象名
related:
- story
- bug
- task
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# Executor配置
# 配置含义
| 参数 | 类型 | 说明 |
|---|---|---|
| app.modules.autotask.executors.actions.option.handle | string | 候选值接口名，用于获取界面配置候选值 |
| app.modules.autotask.executors.actions.exec.handle | string | 执行接口名，用于触发后调用 |
| app.modules.autotask.executors.actions.related | string | 关联的Trigger事件，支持通配符 |
related字段用来指定哪些事件可以触发这个自定义的执行器。story::*表示需求的所有事件,task::create表示任务的创建事件。
- 附所有事件：
bug::attachment
bug::code_change
bug::comment
bug::create
bug::custom_ops
bug::status_change
bug::timer
bug::update
iteration::timer
iteration::update
pipeline::build_end
pipeline::custom_ops
story::attachment
story::code_change
story::comment
story::create
story::custom_ops
story::parent_story_status_change
story::status_change
story::sub_story_status_change
story::sub_task_status_change
story::timer
story::update
task::attachment
task::code_change
task::comment
task::create
task::custom_ops
task::status_change
task::timer
task::update
tobject::attachment
tobject::create
tobject::status_change
tobject::timer
tobject::update
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
Executor依赖两个接口，分别是"候选值接口"和"执行接口"
# 候选值接口
# 接口说明
TAPD请求此接口，获取候选值数据，渲染到自动化助手配置页面
# 请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| workspace_id | integer | tapd项目ID |
| nick | string | 用户英文名 |
| object_code | string | executor对象code |
# 返回数据
# 格式说明
需返回一个数组，通过递归嵌套方式实现级联选择
表单控件格式
| 参数 | 类型 | 说明 |
|---|---|---|
| label | string | 表单控件label |
| key | string | 字段标识 |
| fieldType | string | 表单类型。目前支持：select,select-multi,input,user,dateinput |
| ｜options | array | 候选值列表 |
候选值格式
| 参数 | 类型 | 说明 |
|---|---|---|
| name | string | 候选值名称 |
| value | string | 候选值 |
| data | string | 选中后出现的表单控件列表，支持无限级嵌套 |
# 数据示例
options = [
{
'label' : '字段A',
'key' : 'field_a',
'fieldType' : 'select',
'options' : [
{
'name' : '选项A',
'value' : 'option_a',
'data' : [
{
"key": "field_a",
"label": "子字段B",
"fieldType": "select",
"options": [
{
"name": "子选项A",
"value": "child_option_a"
},
{
"name": "子选项B",
"value": "child_option_a"
}
]
}
]
},
{
'name' : '选项B',
'value' : 'option_b'
}
]
}
]
return options
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# 执行接口
# 接口说明
TAPD请求此接口，完成执行操作
# 请求参数
固定参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| workspace_id | integer | tapd项目ID |
| nick | string | 用户英文名 |
| object_code | string | executor对象code |
其他参数：由"候选值接口"指定
# Trigger配置
# 关键配置
trigger:
events:
- code: trigger_demo
desc: 由xxx事件触发
icon: execute
name: 触发器demo
event_change:
handler: trigger.change
option:
handler: trigger.option
related:
- story::*
- bug::field_change
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
# 候选值接口
trigger.option表示在项目文件中的modules/autotasks/trigger.js文件定义了一个option方法，方法返回了用户配置自动化规则触发器时可选的候选值。
- 代码示例
module.exports.option = data => [
{
label: '修改字段',
key: 'field',
fieldType: 'select',
options: [
{
name: '单选下拉字段A',
value: 'fieldA',
data: [
{
label: '字段变更为',
key: 'fieldVal',
fieldType: 'select',
options: [
{
name: '选项1',
value: 1,
},
{
name: '选项2',
value: 2,
},
],
},
],
},
{
name: '文本字段C',
value: 'fieldB',
data: [
{
label: '字段变更为',
key: 'fieldVal',
fieldType: 'normal-input',
},
],
},
],
},
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
- 数据格式
1.调用参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| workspace_id | integer | tapd项目ID |
| nick | string | 用户英文名 |
| object_code | string | trigger对象code |
2.返回数据
见代码示例
# 事件推送
请在事件发生时请求这个接口推送事件数据到TAPD
# 事件转换接口
示例中的trigger.change表示在项目文件中的modules/autotasks/trigger.js文件定义了一个change方法，事件推送到TAPD后，会调用这个方法将第三方事件数据转换成标准自动化规则事件数据。
- 数据格式
1.调用参数
自定义
2.返回数据
| 参数 | 类型 | 说明 |
|---|---|---|
| timestamp | integer | 时间戳 |
| user | string | 用户英文名 |
| new | object | 事件发生后的对象数据，字段与option字段对应 |
| old | object | 事件发生前的事件数据 |
| tapd_object_id_list | array | tapd对象ID，包括：需求ID、缺陷ID、任务ID |
标准自动化事件格式，示例：
{
"from": "open_app",
"timestamp": 1625567088,
"user": "dobbyzhang",
"new": {
"field":"fieldA",
"fieldVal":1
},
"old": {
"fieldVal":1
},
"tapd_object_id_list":[
"1020357843854927833"
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 关联配置
related字段用来指定自定义trigger可以触发哪些自定义的执行动作。story::add_comment表示需求的添加评论,bug::field_change表示缺陷的字段变更。
- 附所有事件：
bug::field_change
bug::status_change
story::add_comment
story::create_child
story::field_change
story::status_change
task::add_comment
task::field_change
task::status_change
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# Condition配置
# 关键配置
conditions: # 条件扩展
- code: demo_condition # 条件对象code
name: 插件condiiton Demo #条件对象名
icon: business # 扩展显示的图标，目前支持icon: business
desc: 这是一个condition demo对象 # 条件对象描述
option: # 返回条件候选字段列表
handler: condition.option
data: # 进行字段值，用于条件判断
handler: condition.data
related: # 哪些trigger对象下可以配置这个条件判断
- 'story'
- 'bug'
- 'task'
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
# 候选值接口
conditions.option.handler表示在项目文件中的modules/autotasks/condition.js文件定义了一个option方法，方法返回了用户配置自动化规则条件时可选的字段候选值。
- 代码示例
module.exports.option = data => [
{
"fieldSystemName": "field1", //字段标识，英文字符串
"displayName": "标题", //字段名
"fieldType": "text", //字段表单类型，候选值:text,userchooser,date,tselect,select_text,percent,float,tselect-multiple，具体用法请参考文档和示例
"fieldIsSystem": false, //是否系统字段，这里统一为false
"fieldOption": [], //字段候选值
"fieldOptionSort": [] //候选值排序
},
{
"fieldSystemName": "field2",
"displayName": "处理人",
"fieldType": "userchooser",
"fieldIsSystem": false,
"fieldOption": [],
"fieldOptionSort": []
},
{
"fieldSystemName": "field3",
"displayName": "处理时间",
"fieldType": "date",
"fieldIsSystem": false,
"fieldOption": [],
"fieldOptionSort": []
},
{
"fieldSystemName": "field3",
"displayName": "状态",
"fieldType": "tselect",
"fieldIsSystem": false,
"fieldOption": {
"open": "未开始",
"progressing": "进行中",
"done": "已完成"
},
"fieldOptionSort": [
{
"value": "open",
"label": "未开始"
},
{
"value": "progressing",
"label": "进行中"
},
{
"value": "done",
"label": "已完成"
}
]
},
{
"fieldSystemName": "field4",
"displayName": "迭代",
"fieldType": "select_text",
"fieldIsSystem": false,
"fieldOption": {
"9999988": "当前迭代",
"1000000755001568633": "【固氮菌】5",
"1000000755001567989": "【阿尼亚】5",
},
"fieldOptionSort": [
{
"value": "9999988",
"label": "当前迭代"
},
{
"value": "1000000755001568633",
"label": "【固氮菌】5"
},
{
"value": "1000000755001567989",
"label": "【阿尼亚】5"
},
]
},
{
"fieldSystemName": "field6",
"displayName": "进度",
"fieldType": "percent",
"fieldIsSystem": false,
"fieldOption": [],
"fieldOptionSort": []
},
{
"fieldSystemName": "field7",
"displayName": "完成时间",
"fieldType": "datetime",
"fieldIsSystem": false,
"fieldOption": [],
"fieldOptionSort": []
},
{
"fieldSystemName": "field8",
"displayName": "价格",
"fieldType": "float",
"fieldIsSystem": true,
"fieldOption": [],
"fieldOptionSort": []
},
{
"fieldSystemName": "field9",
"displayName": "水果",
"fieldType": "tselect-multiple",
"fieldIsSystem": false,
"fieldOption": {
"草莓莓莓莓": "草莓莓莓莓",
"苹果果果果": "苹果果果果",
"西柚柚柚": "西柚柚柚",
"西瓜": "西瓜"
},
"fieldOptionSort": [
{
"value": "草莓莓莓莓",
"label": "草莓莓莓莓"
},
{
"value": "苹果果果果",
"label": "苹果果果果"
},
{
"value": "西柚柚柚",
"label": "西柚柚柚"
},
{
"value": "西瓜",
"label": "西瓜"
}
]
},
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
- 数据格式
1.调用参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| workspace_id | integer | tapd项目ID |
| object_code | string | 对象标识(story,bug,task) |
2.返回数据
见代码示例
# 数据接口
示例中的condition.data.handler表示在项目文件中的modules/autotasks/condition.js文件定义了一个data方法，TAPD进行条件判断前，会调用这个方法获取数据，然后与规则配置的数据进行比对，得出条件判断结果。
- 数据格式
1.调用参数
| 参数 | 类型 | 说明 |
|---|---|---|
| workspace_id | integer | tapd项目ID |
| object_code | string | 对象名(story,bug,task) |
| object_id | integer | 对象ID |
2.返回数据
| 参数 | 类型 | 说明 |
|---|---|---|
| status | integer | 状态，候选值：1（成功） |
| msg | string | 提示文案，如：执行单元测试 |
| data | object | 用于条件判断的数据，字段与option字段对应 |
返回示例1：
/**
* 返回数据，用于条件比对
* @returns {Object} 组件配置JSON
*/
module.exports.data = function () {
return {
status:1, //状态，候选值：1（成功）
msg:'xxxxxx', //显示在判断失败或判断待定时的文案
data:{
field1:'aaa',
field2:'bbb',
field3:'ccc',
field4:'ddd',
},
};
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 关联配置
related字段用来指定哪些对象可以配置自定义condition。
- 附常用对象：
story
task
bug
1
2
3
2
3