外部数据源介绍

你在什么情况下能用到？

公司同时使用多个系统（智书合同、人事系统、销售管理系统），需要将其他系统数据同步到智书合同表单中的字段作为数据填写，此时通过配置外部数据源为控件的数据来源，就不需要在多个系统维护同一份数据。

例如：智书合同一个涉及销售的合同审批，销售同学提交审批时需要填写外部客户名单，名单已经维护在销售管理系统中且经常变动，这时就可以通过配置外部数据为单选/多选的选项，销售同学在提交审批时只选择自己已跟进的客户，且当销售管理系统中的数据更新时还能同步更新到审批系统中，无需反复维护。

可以帮你解决什么问题？

该功能可以调用外部API，并将API调用结果绑定到合同的字段上，从而避免在多个系统重复进行更新、修改，避免重复劳动。

使用指南

事前准备

开发同学需根据「技术文档」一节的要求，开发相应API

配置API

前往系统管理 - 合同流程管理 - 点击自定义配置，并点击添加对接项

2. 填入对接项名称，名称应保持可读，并点击编辑按钮

3. 第二步执行完成后，将会弹出数据源配置：

这个配置页面复杂，下面分段解释：

3.1 设置触发时机

这部分页面主要用于配置调用API的条件。

填入项	作用	详情描述
触发时机	指定在何时调用外部，当触发时机满足配置时，才会调用API	- 表单字段变化时：监听当前表单中某些字段，当字段的内容发生变化时 - 鼠标点击字段时：指定字段被点击时
监听字段	和触发时机配合使用	举个例子，如下配置表示：当“合同名称”这个字段发生变化时，就去调用API

3.2 数据源获取

这部分内容用于定义如何请求一个API。

填入项	作用	详情描述
请选择	指定HTTP请求方法	目前支持HTTP常用的请求方法
请输入Url	指定API的请求地址	-
Token	Token主要是为了确保数据安全，防止接口被恶意调用	token会以名为“token”的header传输
动态Token	允许调用一个API，从而获取Token	详见技术文档一节
请求头	这部分请求会放在HTTP header中传输	- 入参名称：待传递的header名称 - 请选择：支持如下选项 - 表单字段：从表单字段中取值 - 固定值：你可以填写一个任意的值 - 表达式：可以编写表达式。目前表达式只是初步支持，功能不够完善，不建议使用，近期会增强 - “选择表单字段”： - 当选择“表单字段”时，可以将表单字段绑定到参数上； - 当选择“固定值”时，可将用户填写的值绑定到参数上； - 当选择“表达式”时，可将表达式解析后的值绑定到参数上例如：那么，调用API时，传输的header如下： param1=当前合同名称的值 param2=123
请求体	这部分请求会序列化成JSON结构体，放在HTTP请求体中传输	- 入参名称：待传递的请求体名称 - 请选择：支持如下选项 - 表单字段：从表单字段中取值 - 固定值：你可以填写一个任意的值 - 表达式：可以编写表达式。目前表达式只是初步支持，功能不够完善，不建议使用，近期会增强 - “选择表单字段”： - 当选择“表单字段”时，可以将表单字段绑定到参数上； - 当选择“固定值”时，可将用户填写的值绑定到参数上； - 当选择“表达式”时，可将表达式解析后的值绑定到参数上下面举几个例子： - 对于普通的字段类型，例如：那么在调用API时，将传输如下的请求体： { "param1": "当前合同名称的值", "param2": 3 } - 对于人员、部门类型，例如：那么在调用API时，将传输如下的请求体： { "employeeExtraInfo": [ { "openId": "智书openId", "userId": "智书userId", "employeeId": "员工id", "employeeCode": "员工编码", "name": "员工名称" } ], "partmentExtraInfo": [ { "departmentId": "部门id", "openDepartmentId": "部门openId", "realDepartmentId": "部门department_id，示例值：D096", "code": "部门编码", "name": "部门名称" } ] } 目前审批人回填功能还未支持上述的人员、部门请求体的格式构造，请求格式如下： { "partment": "员工的employeeId" } - 对于交易方字段、我方字段，例如：那么在调用API时，将传输如下的请求体： { "legalEntity": [ { "legalEntityName": "我方-名称", "legalEntityCode": "我方-编码" } ], "tradingParty": [ { "tradingPartyCode": "交易方-编码", "partyName": "交易方-名称" } ] } 目前审批人回填功能还未支持上述交易方字段、我方字段的格式构造，请求格式如下： { "legalEntity": "我方-编码", "tradingParty": "交易方-编码" } - 对于相关单据，例如：那么在调用API时，将传输如下的请求体： { "param": [ { "serialId": "10001" } ] }
Query参数	这部分会作为HTTP Query String传输	配置方式类似请求头、请求体例如：那么，传输的参数如下： ?param1=合同名称的值&param2=123
路径参数	这部分会作为HTTP路径参数传输	路径参数用于应对Url中路径存在占位符的场景。例如：如图，一些Url是动态的，{{path}}需要动态取值。路径参数可解决问题。 - Url中的占位符使用{{名称}}的形式占位，例如{{path}} - 路径参数名称需要和{{}}中的内容相同，例如path 这样，在请求时，将会构造如下地址： http://www.foo.bar/some-path/合同名称的值

3.3 数据源回填

用于将API的响应结果，绑定到合同字段上。响应需按照要求返回，详见技术文档 - Response 一节。
这块比较简单，举个例子，API的响应如下：

{
    "param1": "aaaaa",
    "param2": "bbbbb"
}

那么就可以配置成如下：

这表示将“aaaaa”绑定到字段收支类型上；“bbbbb”绑定到字段计价方式上。

校验接口
数据源配置完成后，用户可进行模拟，调用API，从而验证接口配置是否正确。
如果正确，点击保存按钮即可添加该数据源。

技术文档

请求

本节探讨用户请求相关注意点与细节。

请求头 - 静态token认证

如图配置，会传递一个名为token，值为 a-test-token 的header。
TIPS：发送请求时，Token的默认名称为token，如果希望以其他名称发送，请发起oncall，并联系我们的技术同学修改

请求头 - 动态token认证

配置动态token的URL

API调用过程中会获取上面的 URL (https://example.com/getToken)来获取token，并将从接口获得的值，放到header中传递。
暂时无法在飞书文档外展示此内容
TIPS：

上图中，如果右侧的{"key":"value"} 为空，则会以GET方式请求URL；如果不为空，则会以POST方式请求URL

发送请求时，Token的默认名称为token，如果希望以其他名称发送，请发起oncall，并联系我们的技术同学修改

请求体

请求体不仅可传递文本型的字段（数字、字符串类型），也支持传递结构体。下面举几个例子：

对于普通的字段类型，例如：

那么在调用API时，将传输如下的请求体：

{
    "param1": "当前合同名称的值",
    "param2": 3
}

对于人员、部门类型，例如：

那么在调用API时，将传输如下的请求体：

{
    "employeeExtraInfo": [
        {
            "openId": "智书openId",
            "userId": "智书userId",
            "employeeId": "员工id",
            "employeeCode": "员工编码",
            "name": "员工名称"
        }
    ],
    "partmentExtraInfo": [
        {
            "departmentId": "部门id",
            "openDepartmentId": "部门openId",
            "realDepartmentId": "部门department_id，示例值：D096",
            "code": "部门编码",
            "name": "部门名称"
        }
    ]
}

对于交易方字段、我方字段，例如：

那么在调用API时，将传输如下的请求体：

{
    "legalEntity": [
        {
            "legalEntityName": "我方-名称",
            "legalEntityCode": "我方-编码"
        }
    ],
    "tradingParty": [
        {
            "tradingPartyCode": "交易方-编码",
            "partyName": "交易方-名称"
        }
    ]
}

对于相关单据，例如：

那么在调用API时，将传输如下的请求体：

{
    "param": [
        {
            "serialId": "10001"
        }
    ]
}

默认传递字段

除页面上配置的字段外，还会额外传输一些默认字段，如下（只有在合同提交页面才存在）：

字段名称	含义	传输位置
contractId	合同id	请求体
contractNumber	合同编号	请求体
belongedDepartmentId	合同所属部门id	请求体
applier	申请人id	请求体
submitterUserId	提交人id	- 请求体 - query参数 - 路径参数 - header参数
submitterEmployeeCode	提交人工号	- 请求体 - query参数 - 路径参数 - header参数

响应

响应字段类型

WARNING
响应结果必须符合示例要求，否则前端组件将无法渲染。

响应字段类型说明

字段类型	值类型	示例	说明
数字字段	number	123456	整数
单行/多行文本字段	string	"文本值"	字符串
日期区间字段	array	["2021-10-13","2021-10-22"]	字符串数组
日期字段	string	2021-10-01	字符串
金额	json	{"amount": "33545", "currency": 1} amount为字符串，currency为整数	常见币种类型国际编码： CNY(1, "人民币元", "CNY", "¥"), USD(2, "美元", "USD", " $"), < b r / > J P Y (3, " 日元 ", " J P Y ", " J ￥"), < b r / > E U R (4, " 欧元 ", " E U R ", "€"), < b r / > GBP (5, " 英镑 ", " GBP ", "￡"), < b r / > SG D (6, " 新加坡元 ", " SG D ", " S$ "), THB(7, "泰铢", "THB", "฿"), HKD(10, "港币", "HKD", "HK$"), KRW(8,"韩元","KRW","₩")
链接	object	{ "url": "https://www.bytedance.com/", "title": "字节跳动" } url为字符串，title为字符串	-
单选/多选字段	object/array	Case 1仅回填选项： [ { "label": "自定义1", "labelCn":"自定义1 - 中文", "labelEn":"自定义1 - 英文", "labelJp":"自定义1 - 日文", "value": "v1" }, { "label": "自定义2", "labelCn":"自定义2 - 中文", "labelEn":"自定义2 - 英文", "labelJp":"自定义2 - 日文", "value": "v2" } ] [ { "label": "自定义1", "value": "v1" }, { "label": "自定义2", "value": "v2" }] Case 2回填选项 + 选中默认值： - 单选 { "value": "v2", //选中的默认值 "options": [ { "label": "自定义1", "value": "v1" // value必须为字符串 }, { "label": "自定义2", "value": "v2" }] } - 多选 { "value": ["v2"], //选中的默认值 "options": [ { "label": "自定义1", "value": "v1" // value必须为字符串 }, { "label": "自定义2", "value": "v2" }] } - value类型是字符串 - value为空则清空用户选中值 - 如果选中的默认值在新列表中不存在则清空用户选中的值 - 列表不支持回填options	-
明细字段	object[]	[{ "numberType": 123456, "textType": "asdfads", "stringType": "第一行", "dateType": [ "2021-10-13", "2021-10-22" ], "singleDateType": "2021-10-01", "amountType": { "amount": "33545", "currency": 4 }, "selectType": "1" }] 数组中的值参考其他类型的格式	-
树形字段	object/array	[{ "label": "人力成本", "value": "MDBS00000005", "children": [ { "label": "人力成本 - 保险", "value": "MDBS00000196", "children": null }, { "label": "人力成本 - 补偿金", "value": "MDBS00000197", "children": null } ] }, { "label": "市场费", "value": "MDBS00000181", "children": [ { "label": "品牌市场费", "value": "MDBS00000003", "children": null }, { "label": "拉新市场费", "value": "MDBS00000004", "children": null } ] }] 树形中的所有字段的value不能相同，否则组件将无法渲染	-
对方/我方字段	object/array	[ { "type": "trading_party", "code": "V00225001" }, { "type": "legal_entity", "code": "L00178002" } ] type - 字段类型： - trading_party：对方字段类型 - legal_entity：我方字段类型 code - 主数据编码	-
人员类型/人员多选类型	object/array	[ { "type": "userId", "userId": "12345678" }, { "type": "employeeId", "employeeId": "87654321" }, { "type": "larkId", "larkId":"56781234" } ] - type: Id类型 - userId、employeeId、larkId: Id值	-
审批人回填	array	{ "userId":["1111","2222"] } 对象，userId字段是字符串数组	-
付款计划 / 收款计划 - 付款时间 / 收款时间	object	{ "reminderDate": "2023-07-31", "reminderDateTypeCode": 2, "intervalDays": 1, "intervalDayTypeCode": 1 } reminderDateTypeCode： - 0 - 固定时间，1 - 不固定时间，2 - 履约条件完成后，默认值为0，固定时间 reminderDate： - 付款时间类型=固定时间（reminderDateTypeCode = 0），必填 - 付款时间类型=不固定时间、履约条件完成后（reminderDateTypeCode = 1，2），不可填，如果传入则自动清空 intervalDayTypeCode： - 间隔日的天数单位：1 - 工作日， 2 - 自然日 - 付款时间类型=履约条件完成后（payment_date_type_code = 2），必填 - 付款时间类型=固定时间、不固定时间（payment_date_type_code = 0，1），不可填，如果传入则自动清空 intervalDays： - 履约条件完成到付款日之间的间隔时间，单位为 (自然日/工作日)，单位由interval_day_type_code字段决定 - 付款时间类型=履约条件完成后（payment_date_type_code = 2），必填 - 付款时间类型=固定时间、不固定时间（payment_date_type_code = 0，1），不可填，如果传入则自动清空	-
履约类型	number	0或1 - 0 - 需付款，1 - 无需付款	-
履约事项	string	"文本值"	字符串
有无发票	bool	true或false - true - 有发票，false - 无发票	-
付款金额 / 收款金额	json	{"amount": "33545", "currency": 1} 同上述金额字段。当履约类型为无需付款时，该字段不可填	-
付款说明 / 收款说明	string	"文本值"	字符串
银行账户	number	123456	整数
付款对象 / 收款对象	不支持回填	-
部门	不支持回填	-

示例

错误码

错误码	说明
0	正确
110345	token校验失败
110343	数据不存在
110342	系统异常

表单字段回填

外部数据源介绍#

你在什么情况下能用到？#

可以帮你解决什么问题？#

使用指南#

事前准备#

配置API#

3.1 设置触发时机#

3.2 数据源获取#

3.3 数据源回填#

技术文档#

请求#

请求头 - 静态token认证#

请求头 - 动态token认证#

请求体#

默认传递字段#

响应#

响应字段类型#

响应字段类型说明#

示例#

错误码#

外部数据源介绍

你在什么情况下能用到？

可以帮你解决什么问题？

使用指南

事前准备

配置API

3.1 设置触发时机

3.2 数据源获取

3.3 数据源回填

技术文档

请求

请求头 - 静态token认证

请求头 - 动态token认证

请求体

默认传递字段

响应

响应字段类型

响应字段类型说明

示例

错误码