飞书项目自动化连接器 - 飞书官网

飞书项目自动化连接器

飞书

使用场景​
面向开发者​
面向管理员​
自动化触发器​
自动化操作​
附:自动化出入参字段类型​
附:触发器类型枚举​
附:触发器类型枚举​
自动化连接器是一种开发者扩展自动化流程规则的开放能力,支持空间管理员将插件触发器/操作与平台内置触发器/操作进行连接,并配置相关跨系统的数据集成逻辑。 ​
功能范围 ​
  1. 自动化开放能力包含触发器、条件、操作 ​
​
功能类别​
描述​
图示​
触发器 ​
支持将三方http事件转发到平台,触发平台内置或安装插件的操作 ​
​
​
250px|700px|reset
​
​
条件 ​
当开发者定义触发器的返回参数时,支持管理员配置对应的条件筛选规则,由平台提供对应的数据计算和筛选过滤功能 ​
​
250px|700px|reset
​
​
操作 ​
支持以自动化或插件触发器为触发时机,调用插件相关逻辑 ​
​
250px|700px|reset
​
​
​
  1. 触发器/操作规则表单开放 ​
​
用户类别​
描述​
图示​
开发者 ​
开放自动化触发器/操作表单组件,开发者仅需定义字段类型/字段名称即可渲染对应规则表单 ​
​
250px|700px|reset
​
​
管理员 ​
使用自动化插件时可配置规则,且操作支持将平台内字段与三方系统字段进行值同步配置 ​
​
250px|700px|reset
​
​
​
  1. 自动化插件配置支持热更新 ​
开发者侧:当表单规则发现变化或数据接收对应的webhook地址变化时,无需发版及可实时更新(新增或删除功能点位仍需发版) ​
管理员侧:已安装插件自动化功能升级后无需更新即可进行使用,若已配置规则发生变化,对应在列表中会提示用户进行配置更新 ​
使用场景​
​
场景类别​
场景描述​
开发方法​
插件触发器​
​
当google日历新增一个日程时,在当前meego空间创建一个日程数据,并同步相关字段 ​
​
​
触发器-调用插件:当「google日历」插件的「新增日程」事件触发时 ​
开发者需要支持管理员配置三方账号与meego空间的绑定,并绑定账号下的数据源 ​
可自行在「集成」点位中完成授权模块开发 ​
插件条件-字段值:如果触发器选择的数据满足筛选条件 ​
开发者需要设计触发器出参,对应出参可直接应用于条件值计算 ​
内置操作-字段操作:将「触发器关联日程」的「名称」字段同步为「触发器中选择的插件google日历」的「标题」字段,且「描述」字段同步为「触发器中选择的插件jira」的「描述」字段,且「状态」字段设置为「进行中」 ​
插件触发器+内置操作时,操作的规则表单支持两种模式:设置固定值&同步值,同步值支持引用触发器出参 ​
跨系统数据的映射关系需由开发者存储:当存在对已有空间数据进行更新的逻辑时,需在实际规则执行时携带触发数据关联的工作项实例id ​
插件操作​
当子任务分配人员时,创建对应负责人的飞书任务 ​
​
触发器-人员分配:当「需求」工作项「常规需求流程/需求开发」节点下的子任务人员变更时 ​
操作-调用插件:执行「飞书任务」插件的「创建任务」操作(明盒) ​
开发者需要支持管理员配置三方账号与meego空间的绑定,并绑定账号下的数据源 ​
可自行在「集成」点位中完成授权模块开发 ​
开发者支持自定义操作规则表单​
规则组件对齐现有自动化组件能力,支持管理员配置固定值,也支持配置动态值(选项范围为触发器出参) ​
​
功能亮点 ​
面向开发者 ​
  1. 降低openAPI调用量:针对复杂接口调用可以由平台能力待解决,使用插件触发器+内置操作闭环跨系统数据同步/更新及状态同步等高频数据集成场景 ​
  1. 降低插件运维成本:将飞书项目与不同三方系统之间的字段映射由规则表单承接,开发者仅需定义三方系统中的字段名称及类型,即可通过表单配置保证不同空间与三方系统之间的灵活映射关系 ​
  1. 提升插件扩展性:将原先数据集成中的硬编码能力转换成灵活配置,飞书项目的自动化能力直接可被插件所消费,提升插件的扩展性 ​
面向管理员 ​
  1. 数据集成规则统一管理:针对平台内及跨平台的数据集成,均统一在自动化中进行管理,避免因openAPI造成的规则冲突对平台数据更新不可控现象 ​
  1. 提升插件易用性:数据集成类规则均支持由空间管理员配置,平台内置触发器、操作可直接与插件数据进行集成,提升整体规则易用性 ​
管理员流程 ​
  1. 按需引导内部团队开发者进行相关插件开发(详见开发者流程) ​
  1. 在插件管理-添加插件中搜索对应的插件并进行安装 ​
  1. 安装后会对应插件功能项会自动展现在自动化触发器/操作中,直接进行相关规则配置即可 ​
开发者流程 ​
自动化触发器 ​
开发者后台配置 ​
首先需要在开发者后台增加插件构成 -「自动化触发器」,并完善相关配置。 ​
  1. 触发器名称:自动化触发器名称,指代插件具体的功能项,如「创建jira缺陷」 ​
  1. 触发器描述:自动化触发器描述,指定该触发器具体实现了什么样的功能,如「当jira创建新缺陷时触发」 ​
  1. 触发器key:系统自动生成,不可修改 ​
  1. webhook推送至:用于接受触发器规则订阅事件,支持https/http地址(对应支持实时更新,无需插件发版即可生效)​
  1. token:支持开发者配置验签token,配置后平台推送至对应地址时会携带token信息 ​
  1. 触发器入参:支持开发者配置触发器节点规则表单,格式规范详见下表 ​
​
{​
"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"​
}​
]​
},​
}​
}}}}}}}}
​
  1. 触发器出参:支持开发者配置触发器节点出参,用于后续条件/操作节点进行规则配置,格式规范同上 ​
​
🙆‍♀️
一个插件支持开发多个自动化触发器,配置互相独立生效 ​
​
事件列表 ​
规则订阅事件 ​
规则配置者填写触发器入参并保存规则后,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地址 ​
​
​
​
​
请求方式​
POST ​
​
​
​
​
请求地址​
/webhook/auto/trigger/data ​
​
​
​
​
请求参数​
参数类型​
参数名​
是否必填​
值类型​
说明​
​
query ​
project_key ​
是 ​
string ​
空间key ​
​
query ​
plugin_key ​
是 ​
string ​
插件key ​
​
query ​
trigger_key ​
是 ​
string ​
触发器key ​
​
header ​
X-ITEM-UUID ​
否 ​
string ​
幂等key ​
​
header ​
X-TOKEN ​
否 ​
string ​
开发者后台提示的token签名 ​
​
body ​
{​
// 满足触发器定义的参数,详见以下​
}​
​
​
​
响应参数 ​
{​
"code": 0 ​
// 1001 qps限制​
// 1002 大小超过限制​
// 1003 幂等​
// 1004 签名错误​
// 1005 黑名单限制​
// 2001 参数异常​
// 2002 缺乏必填参数​
// 5001 系统错误​
}​
​
​
​
​
​
​
触发器API Body参数如下: ​
​
{​
"字段key": {​
"label": "字段名称,可用于规则配置者的自定义参数", // 规则配置自定义参数​
"value": any // 字段值,值数据类型取自字段key定义的字段类型,可参考插件自动化配置规范​
},​
"work_item_ids": { // 特殊支持字段,开发者不需要在插件自动化配置规范,使用在内置操作,value格式固定为工作项id数组​
"label": "",​
"value": [124235,23523]​
}​
}}}}}}}}
​
自动化操作 ​
开发者后台配置 ​
首先需要在开发者后台增加插件构成 -「自动化操作」,并完善相关配置 ​
​
250px|700px|reset
​
​
  1. 操作名称:自动化操作名称,指代插件具体的功能项,如「字段合并」 ​
  1. 操作描述:自动化操作描述,指定该操作具体实现了什么样的功能,如「将文本类字段合并到另一个文本字段」 ​
  1. 操作key:系统自动生成,不可修改 ​
  1. 适用的触发器类型:支持配置操作可应用的触发器类型,不选择时则默认自动化内所有触发器均可调用当前插件 ​
  1. webhook推送至:支持配置接收webhook的用户地址,支持https/http地址(对应支持实时更新,无需插件发版即可生效)​
  1. token:支持开发者配置验签token,配置后平台推送至对应地址时会携带token信息 ​
  1. 操作入参:支持开发者配置操作节点规则表单,格式规范详见下表 ​
​
{​
"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 ​
​
事件结构体明细 ​
  1. 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-更新订阅​
}​
]​
}​
]​
} ​
}}}}}}}
​
  1. 其余事件​
当规则执行时,平台会向开发者定义的 操作 Webhook 推送地址发送如下格式请求: ​
事件推送 ​
插件在收到 HTTP POST 请求后,需要在 60 秒内以 HTTP 200 状态码,以及如下响应结构返回: ​
​
{​
"code": 0​
}}}}}}}
​
否则飞书项目自动化将认为本次推送失败,并以 6秒 的间隔重新推送事件,最多推送 3 次。 ​
附:自动化出入参字段类型​
​
field_type枚举 ​
​
开发者消费数据结构 ​
字段类型 ​
示例 ​
值含义 ​
范围 ​
text ​
string ​
单行文本 ​
{​
"value": "测试单行文本"​
}​
文本值 ​
触发器入参、触发器出参、操作入参 ​
multi_text ​
string ​
多行文本 ​
{​
"value": "测试多行文本"​
}​
文本值 ​
触发器入参、触发器出参、操作入参 ​
date ​
number ​
日期 ​
{​
"value": 1727091486000​
}​
毫秒时间戳 ​
触发器入参、触发器出参、操作入参 ​
schedule ​
{​
start: number​
end: number​
}​
​
日期区间 ​
{​
"value": {​
"start": 1727091486000,​
"end": 1727091486000​
}​
}​
开始时间戳和结束时间戳 ​
操作入参 ​
​
boolean ​
boolean ​
开关 ​
{​
"value": true​
}​
true、false、null ​
触发器出参、操作入参 ​
user ​
string ​
人员 ​
{​
"value": "测试user key"​
}​
User key ​
触发器入参、操作入参 ​
multi_user ​
array[string] ​
多选人员 ​
{​
"value": [​
"测试user key"​
]​
}​
User key数组 ​
触发器入参、触发器出参、操作入参 ​
number ​
number ​
数字 ​
{​
"value": 123.1​
}​
数字 ​
触发器入参、触发器出参、操作入参 ​
link ​
string ​
链接 ​
{​
"value": "https://bytedance.larkoffice.com"​
}​
url ​
触发器出参、操作入参 ​
select ​
string ​
单选 ​
{​
"value": "测试选项id"​
}​
选项id ​
触发器入参、操作入参 ​
radio ​
string ​
单选按钮 ​
{​
"value": "测试选项id"​
}​
选项id ​
触发器入参、操作入参 ​
multi_select ​
array[string] ​
多选 ​
{​
"value": [​
"测试选项id"​
]​
}​
选项id数组 ​
触发器入参、操作入参 ​
​
附:触发器类型枚举​
​
field_type枚举 ​
​
开发者消费数据结构 ​
字段类型 ​
示例 ​
值含义 ​
范围 ​
text ​
string ​
单行文本 ​
{​
"value": "测试单行文本"​
}​
文本值 ​
触发器入参、触发器出参、操作入参 ​
multi_text ​
string ​
多行文本 ​
{​
"value": "测试多行文本"​
}​
文本值 ​
触发器入参、触发器出参、操作入参 ​
date ​
number ​
日期 ​
{​
"value": 1727091486000​
}​
毫秒时间戳 ​
触发器入参、触发器出参、操作入参 ​
schedule ​
{​
start: number​
end: number​
}​
​
日期区间 ​
{​
"value": {​
"start": 1727091486000,​
"end": 1727091486000​
}​
}​
开始时间戳和结束时间戳 ​
操作入参 ​
​
boolean ​
boolean ​
开关 ​
{​
"value": true​
}​
true、false、null ​
触发器出参、操作入参 ​
user ​
string ​
人员 ​
{​
"value": "测试user key"​
}​
User key ​
触发器入参、操作入参 ​
multi_user ​
array[string] ​
多选人员 ​
{​
"value": [​
"测试user key"​
]​
}​
User key数组 ​
触发器入参、触发器出参、操作入参 ​
number ​
number ​
数字 ​
{​
"value": 123.1​
}​
数字 ​
触发器入参、触发器出参、操作入参 ​
link ​
string ​
链接 ​
{​
"value": "https://bytedance.larkoffice.com"​
}​
url ​
触发器出参、操作入参 ​
select ​
string ​
单选 ​
{​
"value": "测试选项id"​
}​
选项id ​
触发器入参、操作入参 ​
radio ​
string ​
单选按钮 ​
{​
"value": "测试选项id"​
}​
选项id ​
触发器入参、操作入参 ​
multi_select ​
array[string] ​
多选 ​
{​
"value": [​
"测试选项id"​
]​
}​
选项id数组 ​
触发器入参、操作入参 ​
​
附:触发器类型枚举​
​
1 // 创建工作项 ​
2 // 完成工作项 ​
3 // 删除工作项 ​
4 // 终止或恢复工作项 ​
5 // 工作项状态修改 ​
6 // 字段值修改 ​
7 // 评论操作 ​
9 // 工作项节点流转 ​
10 // 排期操作 ​
11 // 人员分配 ​
14 // 任务修改 ​
15 // 任务状态修改 ​
18 // 定时任务 ​
19 // 动态时间任务 ​
30 // 任务创建 ​
31 // 任务删除 ​
32 // 连接器触发
​
预约飞书企业效能顾问 深度诊断企业痛点,定制专属 AI 办公方案

字节跳动旗下 AI 工作平台

关联文章推荐

优质内容,精华实践

先进团队,先用飞书

欢迎联系我们,飞书效能顾问将为您提供全力支持
分享先进工作方式
输送行业最佳实践
全面协助组织提效
标题标题标题标题标题标题标题标题标题标题标题标题标题标题标题标题标题标题

字节跳动旗下 AI 工作平台

联系我们立即试用