自动化连接器是一种开发者扩展自动化流程规则的开放能力，支持空间管理员将插件触发器/操作与平台内置触发器/操作进行连接，并配置相关跨系统的数据集成逻辑。
功能范围
- 自动化开放能力包含触发器、条件、操作
功能类别 | 描述 | 图示 |
触发器 | 支持将三方http事件转发到平台，触发平台内置或安装插件的操作 | 250px|700px|reset |
条件 | 当开发者定义触发器的返回参数时，支持管理员配置对应的条件筛选规则，由平台提供对应的数据计算和筛选过滤功能 | 250px|700px|reset |
操作 | 支持以自动化或插件触发器为触发时机，调用插件相关逻辑 | 250px|700px|reset |
- 触发器/操作规则表单开放
用户类别 | 描述 | 图示 |
开发者 | 开放自动化触发器/操作表单组件，开发者仅需定义字段类型/字段名称即可渲染对应规则表单 | 250px|700px|reset |
管理员 | 使用自动化插件时可配置规则，且操作支持将平台内字段与三方系统字段进行值同步配置 | 250px|700px|reset |
- 自动化插件配置支持热更新
开发者侧：当表单规则发现变化或数据接收对应的webhook地址变化时，无需发版及可实时更新（新增或删除功能点位仍需发版）
管理员侧：已安装插件自动化功能升级后无需更新即可进行使用，若已配置规则发生变化，对应在列表中会提示用户进行配置更新
使用场景
功能亮点
面向开发者
- 降低openAPI调用量：针对复杂接口调用可以由平台能力待解决，使用插件触发器+内置操作闭环跨系统数据同步/更新及状态同步等高频数据集成场景
- 降低插件运维成本：将飞书项目与不同三方系统之间的字段映射由规则表单承接，开发者仅需定义三方系统中的字段名称及类型，即可通过表单配置保证不同空间与三方系统之间的灵活映射关系
- 提升插件扩展性：将原先数据集成中的硬编码能力转换成灵活配置，飞书项目的自动化能力直接可被插件所消费，提升插件的扩展性
面向管理员
- 数据集成规则统一管理：针对平台内及跨平台的数据集成，均统一在自动化中进行管理，避免因openAPI造成的规则冲突对平台数据更新不可控现象
- 提升插件易用性：数据集成类规则均支持由空间管理员配置，平台内置触发器、操作可直接与插件数据进行集成，提升整体规则易用性
管理员流程
- 按需引导内部团队开发者进行相关插件开发（详见开发者流程）
- 在插件管理-添加插件中搜索对应的插件并进行安装
- 安装后会对应插件功能项会自动展现在自动化触发器/操作中，直接进行相关规则配置即可
开发者流程
自动化触发器
开发者后台配置
首先需要在开发者后台增加插件构成 -「自动化触发器」，并完善相关配置。
- 触发器名称：自动化触发器名称，指代插件具体的功能项，如「创建jira缺陷」
- 触发器描述：自动化触发器描述，指定该触发器具体实现了什么样的功能，如「当jira创建新缺陷时触发」
- 触发器key：系统自动生成，不可修改
- webhook推送至：用于接受触发器规则订阅事件，支持https/http地址（对应支持实时更新，无需插件发版即可生效）
- token：支持开发者配置验签token，配置后平台推送至对应地址时会携带token信息
- 触发器入参：支持开发者配置触发器节点规则表单，格式规范详见下表
{
"field_type": "字段类型", // 字段类型，与meego业务相关的字段类型，用户需要按照字段类型对应的数据结构进行解析值，详见3.1.2
"form_config": {
"label": {"origin": "字段名称"},
"description": {"origin": "字段描述"},
"placeholder": {"origin": "字段提示文案"},
"validate": {
"requited": {
"value": true // 字段是否必填，在不同场景会有不同的现象
// 1. 触发器入参，不起作用
// 2. 触发器出参，开发者调用触发器API时必须传递，否则将视为不满足触发条件
// 2. 操作入参，规则配置者必须指定该字段的值
}
}
},
"field_attr": {
"option": { // 仅当field_type为select、radio、multi_select时生效
"type": "enum", // enum为默认下拉选项，remote从url获取下拉选项，url响应必须为如下的list结构，post方案,application/json的body传参
"remote": {
"url": "可公网访问的POST方式的http地址" // 由开发者提供，需要按照 如下格式返回body
// [
// {
// "label": "选项名称",
// "value": "选项id"
// }
// ]
},
"enum": [
{
"label": {"origin": "选项展示名称"},
"value": "选项id"
}
]
},
}
}}}}}}}}
- 触发器出参：支持开发者配置触发器节点出参，用于后续条件/操作节点进行规则配置，格式规范同上
一个插件支持开发多个自动化触发器，配置互相独立生效
事件列表
规则订阅事件
规则配置者填写触发器入参并保存规则后，meego会向开发者定义的 触发器 Webhook 推送地址发送如下格式请求：
{
"header": {
"operator": "", // 操作人
"event_type": "RuleSubscribeEvent", // 事件类型
"token": "" // token
},
"payload": {
"project_key": "", // 空间唯一标识
"rule_name": "", // 规则名称
"rule_group_id": "", // 规则ID
"rule_list": [
"rule_id": "", // 触发器分支唯一标识
"trigger_type": 0, // 触发器类型，可参考触发器类型枚举
"node_list": [
"node_id": "", // 触发器节点id
"created_at": "", // 规则创建时间
"updated_at": "", // 规则执行时间
"operate_type": "subscribe" // 操作行为：1. subscribe（新建规则，订阅），2. unsubscribe（修改规则后，取消订阅），3. update（修改规则，更新信息）
"field_item": [
{
"field_key": "", // 触发器入参字段key
"field_value": any // 触发器入参字段值，数据类型可参考字段类型对应的数据类型
}
]
]
]
}
}}}}}}}}
开发者推送事件规范
规则配置者填写触发器入参并保存规则后，开发者可以向触发器API发送请求从而触发自动化规则执行：
触发器API Body参数如下：
{
"字段key": {
"label": "字段名称，可用于规则配置者的自定义参数", // 规则配置自定义参数
"value": any // 字段值，值数据类型取自字段key定义的字段类型，可参考插件自动化配置规范
},
"work_item_ids": { // 特殊支持字段，开发者不需要在插件自动化配置规范，使用在内置操作，value格式固定为工作项id数组
"label": "",
"value": [124235,23523]
}
}}}}}}}}
自动化操作
开发者后台配置
首先需要在开发者后台增加插件构成 -「自动化操作」，并完善相关配置
250px|700px|reset
- 操作名称：自动化操作名称，指代插件具体的功能项，如「字段合并」
- 操作描述：自动化操作描述，指定该操作具体实现了什么样的功能，如「将文本类字段合并到另一个文本字段」
- 操作key：系统自动生成，不可修改
- 适用的触发器类型：支持配置操作可应用的触发器类型，不选择时则默认自动化内所有触发器均可调用当前插件
- webhook推送至：支持配置接收webhook的用户地址，支持https/http地址（对应支持实时更新，无需插件发版即可生效）
- token：支持开发者配置验签token，配置后平台推送至对应地址时会携带token信息
- 操作入参：支持开发者配置操作节点规则表单，格式规范详见下表
{
"field_type": "字段类型", // 字段类型，与meego业务相关的字段类型，用户需要按照字段类型对应的数据结构进行解析值，详见3.1.2
"form_config": {
"label": {"origin": "字段名称"},
"description": {"origin": "字段描述"},
"placeholder": {"origin": "字段提示文案"},
"validate": {
"requited": {
"value": true // 字段是否必填，在不同场景会有不同的现象
// 1. 触发器入参，不起作用
// 2. 触发器出参，开发者调用触发器API时必须传递，否则将视为不满足触发条件
// 2. 操作入参，规则配置者必须指定该字段的值
}
}
},
"field_attr": {
"option": { // 仅当field_type为select、radio、multi_select时生效
"type": "enum", // enum为默认下拉选项，remote从url获取下拉选项，url响应必须为如下的list结构，post方案,application/json的body传参
"remote": {
"url": "可公网访问POST方式的http地址" // 由开发者提供，需要按照 如下格式返回body
// [
// {
// "label": "选项名称",
// "value": "选项id"
// }
// ]
},
"enum": [
{
"label": {"origin": "选项展示名称"},
"value": "选项id"
}
]
},
}
}}}}}}}
一个插件支持开发多个自动化操作，配置互相独立生效
业务流程
250px|700px|reset
事件列表
平台事件
指代开发者与自动化通讯时，平台给到插件的事件，主要为规则订阅事件：RuleSubscribeEvent。
工作项事件
指代规则运行时，触发器对应的工作项变更事件或事件任务事件，主要包含以下内容：
触发器 | event_type |
创建工作项 | WorkitemCreateEvent |
字段值修改 | WorkitemUpdateEvent |
终止工作项 | WorkitemAbortedEvent（工作项终止） WorkitemRestoreEvent（工作项恢复） |
工作项状态修改 | WorkitemStatusEvent |
任务状态修改 | TaskStatusEvent |
任务修改 | TaskUpdateEvent |
角色操作 | WorkitemPersonAssignedEvent |
节点状态修改 | WorkFlowNodeStatusEvent |
节点排期操作 | WorkFlowNodeScheduleEvent |
评论操作 | WorkitemCommentEvent |
工作项归档 | WorkitemFinishEvent |
删除工作项 | WorkitemDeleteEvent |
定时循环 | TimedTriggerEvent |
动态时间任务 | DynamicTimeTriggerEvent |
事件结构体明细
- RuleSubscribeEvent —— 规则订阅
{
"header": {
"operator": "", // string, 操作者的userkey
"event_type": "WorkitemCreateEvent", // string, webhook的event_type
"token": "", // string，注册webhook填入的token
"uuid": "" // string，幂等串
},
"payload": { // json结构，基于facade_idl里面workitem结构
"project_key": "", // 规则所属空间key
"rule_name": "", // 规则组名称
"rule_group_id": "", // 规则组id
"trigger_at": 0, // 当前推送时间
"rule_list": [
{
"rule_id": "", // 规则id
"trigger_type": 1, // 触发器类型，可参考触发器类型枚举
"node_list": [
{
"node_id": "", // 规则节点id
"work_item_type_key": "", // 涉及工作项类型
"created_at": 1639548775000, // int，64位，创建时间戳
"updated_at": 1639548775000, // int，64位，更新时间戳
"operate_type": "subscribe" // 规则操作类型，subscribe-订阅，unsubscribe-取消订阅,update-更新订阅
}
]
}
]
}
}}}}}}}
- 其余事件
当规则执行时，平台会向开发者定义的 操作 Webhook 推送地址发送如下格式请求：
事件推送
插件在收到 HTTP POST 请求后，需要在 60 秒内以 HTTP 200 状态码，以及如下响应结构返回：
{
"code": 0
}}}}}}}
否则飞书项目自动化将认为本次推送失败，并以 6秒 的间隔重新推送事件，最多推送 3 次。
附：自动化出入参字段类型
附：触发器类型枚举
附：触发器类型枚举
1 // 创建工作项
2 // 完成工作项
3 // 删除工作项
4 // 终止或恢复工作项
5 // 工作项状态修改
6 // 字段值修改
7 // 评论操作
9 // 工作项节点流转
10 // 排期操作
11 // 人员分配
14 // 任务修改
15 // 任务状态修改
18 // 定时任务
19 // 动态时间任务
30 // 任务创建
31 // 任务删除
32 // 连接器触发
