金蝶云星空单据回传钉钉通知:一条策略的实战拆解

这个策略解决什么问题

一条业务单据写入金蝶云星空后,审批人和发起人最怕的就是「黑盒」——单据已经在 ERP 里落库,但钉钉群里静悄悄,人不知道下一步该找谁。我们在客户现场做过统计,单据完成后 30 分钟内没有任何回执,发起人平均会重复问 2-3 次,白白消耗沟通成本。

这条策略干的事很朴素:金蝶云星空回写完成后,自动调钉钉的工作流通知接口,在对应审批实例下补一条评论,把单据编号、状态、结果一并回写到发起人和审批人的视野里。它不是数据同步,而是状态回执——确保 ERP 的每一次落库,在协作软件侧都能被「听见」。

数据流向与字段映射

整个链路是三段式:金蝶云星空 → 轻易云数据集成平台(Qeasy)内部状态校验 → 钉钉工作流评论接口。

表头字段(单据编号、单据状态、申请人)在源端校验阶段拿到,经轻易云组装后作为评论正文传入钉钉;表体字段本策略不涉及,属于其他策略的边界。

在轻易云上如何配置

进入轻易云数据集成平台的策略编辑界面,这条策略有三个值得注意的配置点。

第一,源端 metadata 选择「请求空操作」,type=QUERY。这一步不是真正去取业务数据,而是用一次轻量回查确认上一节点的金蝶写入是否已可见。idCheck 必须开启,平台会用返回里的 id 字段判定上一节点是否真正成功——如果上游失败,这一节点会自动跳过,不会出现"金蝶没写进去,钉钉却通知成功"的尴尬。

第二,目标端调钉钉的 topapi/process/instance/comment/add,method=POST,type=EXECUTE。request 是一个对象结构,内含评论正文、processInstanceId 等字段。这里的关键是 processInstanceId 要从轻易云运行上下文中拿,而不是前端硬编码——单据和审批实例的绑定关系,通常在前置策略里已经落到了平台上下文里。

第三,autoFillResponse 关闭,buildModel 关闭。评论接口对回执内容不敏感,平台不需要为它生成解析模型,反而能减少无谓的字段映射维护。这是轻易云平台上处理"通知型"策略的常见做法:编码映射集中管理,通知型接口不必为每条评论建模型,省下后期维护成本。

实施步骤

分阶段调度是这条策略能不能稳定运行的关键。

第一步:增量起点。 上游策略把单据写入金蝶云星空后,本策略的 cron(1 1 1 2 3)作为兜底重试——主链路其实是被事件触发的,这条 cron 更多是给"事件丢了"的极端情况兜底。稳妥的做法是:主链路用事件触发,这条 cron 留作每 3 小时一次的健康巡检。

第二步:全量触发。 通知型策略通常不做全量,只在历史数据修复期才需要手工跑一次——比如某天钉钉审批实例迁移、或者工作流模板变更后,需要补发通知。我们一般用轻易云的「手工触发」+「按单据号过滤」组合,精准补发,不批量重放。

第三步:调度频率。 目标端策略的 cron(*/7 8-22 * * *)是工作时段每 7 分钟一轮,8 点到 22 点覆盖大多数企业的上班时间。非工作时段停止是为了不打扰发起人,也是为了避开钉钉接口的非必要调用频次。

踩坑复盘

坑一:把通知策略当数据同步策略来配。 典型错误是给评论接口也建了完整的请求/响应模型,导致后期钉钉接口稍微变字段就要改一堆映射。稳妥做法:通知型接口只配 request 必需字段,关闭 autoFillResponse 与 buildModel。

坑二:idCheck 关闭后静默失败。 有些工程师为了"跑得快"关掉 idCheck,结果上一节点金蝶写入失败,本节点照常调钉钉,业务群里出现"已成功"的假通知。idCheck 是这条策略的生命线,绝不能关。

坑三:processInstanceId 取错位置。 有人把单据号当 processInstanceId 用,钉钉返回"实例不存在"。这两个 ID 来自不同系统,绑定关系必须在轻易云的运行上下文里维护,不能前端硬编码。

坑四:评论正文里塞了敏感字段。 金蝶回写的单据里常有客户名称、金额、备注,全部塞进钉钉评论会导致越权可见。建议在轻易云的字段映射阶段做脱敏,只回执单据编号、状态和一句话结论。

坑五:cron 表达式和事件触发混用导致重复通知。 如果主链路靠事件触发、cron 又同时在跑,极端时序下会发两条评论。稳妥做法:事件触发为主,cron 仅作健康巡检,且巡检时通过去重键(单据号+状态)跳过已通知单据。

适用场景与不适用场景

适用:金蝶云星空作为 ERP 主干,钉钉作为日常协作与审批入口的中小型企业;单据状态变更需要立刻触达发起人/审批人;不希望为每条单据单独开发通知服务。

不适用:需要富媒体卡片、需要跳转 OA 链接、需要按角色路由到不同审批人的复杂通知场景;金蝶与钉钉并非主审批链路的企业。