钉钉开发文档

企业接入流程

更新时间: 2019-4-8

本文档将帮助企业内部开发者快速对接钉钉【审批】,具体步骤如下:

重要更新

审批接口支持后台设置的固定流程设计了,支持或签会签了,支持更多控件,详情请仔细阅读本文。如需使用新功能,请更新下服务端API SDK。

步骤一:OA管理后台创建审批表单,该表单用于承载开发者发起的审批实例

1、登录OA管理后台,选择【工作台】,点击【审批】。

2、开发者可以在审批管理页面新建并编辑审批表单,也可以对编辑审批分组和导出审批数据。这里我们选择点击【创建新审批】,或者点击【编辑表单】对一个已有的审批进行编辑。

3、进入表单设计器页面,把控件拖入到表单中。目前发起审批接口支持两种模式,主动传审批人和复用审批后台设置的审批流程。
主动传审批人模式:调用接口的时候,传入approvers参数,指定审批人。目前该种模式,只支持四种控件,分别是【单行输入框】、【多行输入框】、【图片】、【明细】,其中【明细】控件里可以添加另外的三种控件。假如审批表单中使用了其他控件(如附件、日期等),在调用发起审批实例的接口时会报错。该模式下,不支持会签或签等操作。
复用审批后台设置的审批流程模式:调用接口的时候,不传入approvers参数,就会自动复用预设值的审批流程。该模式下,为了满足审批流程设置的需要,在原有四种控件基础上,新增了金额、数字、日期区间、单选框这四种控件。开发者可以组装这四种控件,然后在流程设计页面使用。具体这新增的四种控件如何传参,会在下面的参数详解说明。同时,该模式下,可在流程设计里设置审批人的或签会签等操作。流程设计页面见下图:



步骤二:开发者准备接口参数

可以在自己的erp系统或E应用里开发一个自己的审批表单页面(非必须),用于让用户来填写表单信息发起审批。这里的表单控件名需要一一对应开发者在【步骤一】中创建的钉钉【审批】表单控件。如下图中开发者自己编写的审批表单页面,使用了【行程明细】、【交通工具】、【出差事由】、【图片】四个表单名称,与步骤一图中的表单名称一一对应。这里强烈建议开发者运行一下审批的QuickStart,深入了解一下各个表单控件的接口传参格式。下图为QuickStart中设计的E应用审批表单页面:
image.png

步骤三:开发者调用发起审批实例接口

如何调用接口请参考发起审批实例

步骤四:开发者监听审批事件的回调

什么是回调

回调是开发者在钉钉开放平台注册一个http接口,并订阅相关的事件,当事件发生时,钉钉这边会主动调用开发者注册的http接口,返回对应的事件信息。

你是否需要订阅审批事件的回调

两种情况下,可以注册下审批回调:

  • 调用发起审批实例接口以后,需要实时获取审批的状态
  • 用户在钉钉审批应用里发起了审批(如请假、报销),开发者需要实时获取审批状态

回调数据格式

参考审批事件回调

如何注册回调

  • 企业可以直接使用QuickStart服务端程序,配置完对应的参数,运行CallBackController.java里的main方法即可为企业注册回调。
  • 也可以直接参考业务事件回调,审批回调的tag是bpms_task_change和bpms_instance_change

表单参数详解

表单参数采用key,value的形式,其中key是每个控件对应的名字,value可以是普通字符串,也可以是json字符串,具体来说:

输入框类型

value是普通字符串

图片类型

value是json数组,每个数组元素必须为图片的url,如

["http://url1","http://url2","http://url3"]

明细类型

明细控件内部也只能由输入框控件和图片控件组成,它的value格式如下:

[
    [
        {"name":"开始时间","value":"2018-09-01"},
        {"name":"结束时间","value":"2018-09-03"}
    ],
    [
       {"name":"开始时间","value":"2018-09-05"},
       {"name":"结束时间","value":"2018-09-07"}
    ]
]

金额、数字类型

value是数字

单选框类型

value是字符串,必须是在审批模板设计时预设值的单选框的值

日期区间

name是一个数组,value也是对应数组,格式如下:

{
      "name": "[\"开始时间\",\"结束时间\"]",
      "value": "[\"2019-02-19\",\"2019-02-25\"]"
}

传参总结

对于在【步骤一】中我们创建的表单,对应的发起审批实例时需要传的表单参数(java例子)。

List<FormComponentValueVo> list2 = new ArrayList<FormComponentValueVo>();
FormComponentValueVo obj3 = new FormComponentValueVo();
obj3.setName("交通工具");
obj3.setValue("飞机");
 
FormComponentValueVo obj4 = new FormComponentValueVo();
obj4.setName("出差事由");
obj4.setValue("开会");
 
FormComponentValueVo pic = new FormComponentValueVo();
pic.setName("图片");
pic.setValue("[\"http://aaa/media\"]");
 
FormComponentValueVo mingxi2 = new FormComponentValueVo();
mingxi2.setName("开始时间");
mingxi2.setValue("2018-09-01");
 
FormComponentValueVo mingxi3 = new FormComponentValueVo();
mingxi3.setName("图片");
mingxi3.setValue("[\"http://aaa/media\"]");
 
FormComponentValueVo obj7 = new FormComponentValueVo();
obj7.setName("明细");
obj7.setValue(JSON.toJSONString(Arrays.asList(Arrays.asList(mingxi2, mingxi3))));
 
list2.add(obj3);
list2.add(obj4);
list2.add(pic);
list2.add(obj7);

以上代码,每个setName里面的值就是审批表单里左侧的标签值,每个setValue里的值就是用户在填写审批表单时输入的值。
组装明细的时候,value是数组套数组的格式,推荐使用json转化。

以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!