表单智能 API

3069 上次更新时间：2021-02-21 18:26:02

Document

1.功能简介

表单智能 API 是速融云针对第三方的系统对接情况，特意优化，对开发人员非常的友好。与传统 openApi 的最大区别就是利用无代码的能力，让接口的格式完全由第三方自己设计，大大减轻了第三方的对接成本，用自己的方式进行开发。

2.api 类型

这6 种接口涵盖了对数据的 CRUD。 同时配合以流程与事件表单，达到更加融合状态。也阐释了「速融云」的品牌价值 「快速融合」

  • 发起表单
  • 更新表单
  • 删除表单
  • 添加或更新
  • 获取表单数据多条
  • 获取表单数据单条

3.智能 API设计思路

在第三方对接的角度来看，一个应用可以理解为一个数据库，而表单可以理解为一张数据表，平台通过 openAPI 提供表单的 CRUD的功能 。为了更加个性化对接第三方系统，我们先来看 2 个问题。

1.速融云如何理解第三方提交内容呢？

A：原理是通过 JSONPATH 进行提取相关的变量。速融云在接收到请求以后，会提取 body 的数据，然后根据预设的 jsonPath 进行提取然后使用。例如 我们官方收集数据错误，先对 团队 ID 进行提取，其次在对内容进行设置。

2.速融云如何知道用什么样的格式给第三方返回？

A：原理是通过预设的 json 模板，平台自动进行替换数据。 因为速融云本身无法预先知道第三方想要什么，而解决这个问题最好方式是第三方在设计一个 json 模板，在返回时进行数据的替换填充。

3.数据流转图

3.名词解释

别名(或称中间变量)
在智能 api 中，用于存放 jsonPath 提取的数据，作用域为单次请求。如果把一次api 调用看成一次函数调用（方法调用），别名 类似于 函数内部的局部变量。

4.视频讲解

为了快速的熟悉 openApi 体系，我们提供了一个简短视频帮助大家理解。 coming soon！

5.注意事项

  1. 表单智能 API 所有接口请求都为POST 请求。
  2. 如果请求时不带有任何参数，请至少使用 {} 为请求体，否则会出现  400 请求无效 (Bad request) 错误。
  3. 创建者或者更新人需要用速融云的 userID
  4. 设计 JSON 模板时，(单行文本、多行文本、智能引用、下拉框、手机号等字符类型控件无需添加双引号)
  5. 分页获取的数据 page 从1 开始
  6. jsonPath 需要保证正确否则会与操作结果预期不符
  7. 请保证 jsonPath 提取的数据需要与控件需要的类型保持一致，否则会导致公式等计算错误。
  8. 在设置JSON 模板时，请务必保证字段名与字段类型保持一致。否则系统将会过滤掉不合法的字段模板

字段模板构造示例：  $${SINGLELINE_ke2gu300UkvW107H#表单名称}$$     SINGLELINE_ke2gu300UkvW107H为字段 ID  表单名称为控件名称。

  1. 请求时 请务必 在 Request Header 中需带上

1.  Content-Type：application/json ，并以以 json 格式提交数据。
   2. 同时添加  token 字段。   Authorization: Bearer xxxxxxToken

在线演示测试
   https://www.sojson.com/http/test.html

6.接口设计流程

1.权限需求

必须为应用管理员以及以上权限才能进行配置。

2.设置步骤

1.编辑表单–>「扩展设计」–>「智能 api」–>「发起表单/更新等」,修改完成以后记得发布

2.查看字段对照表, 「获取批量数据」


3.获取每一个接口的请求 URL 。 注意接口的 URL 不会变。 如果 token 不慎泄露，请务必及时重置 TOKEN
4.平台在 jsonPath 提取的地方都提供有 验证 jsonPath 的校验器。可以用来判断 jsonPath 提取的结果和类型是否正确。

7.接口-创建发起表单

接口描述

  • 1.给指定表单中，插入 1 条数据。如果插入多条请多次调用。
  • 2.如果设置了发起人， 则需要为速融云的 userID， 具体请查看流程引擎相关开放平台设计。
  • 3.开放平台调用以后，流程将会自动流转。

数据处理流程

第三方系统请求数据—>开放平台接受数据—>根据预设的 JSONPath 进行提取变量数据—>根据填写规则复制–>返回成功标识–>表单在速融云内部进行流转–>第三方收到反馈结果

配置流程

  • 1.配置需要提取的变量
  • 2.设置变量填入控件的规则。
  • 3.设置创建后的 responseBody


8.接口-创建更新表单

接口描述

更新一条 or 一批的数据。

数据处理流程

第三方系统请求数据—>开放平台接受数据—>根据预设的 JSONPath 进行提取变量数据—>筛选更新的目标（1 条或多条）—>更新数据—>返回成功标识–>表单在速融云内部进行流转。

注意 ：

  • 1.筛选的数据有可能筛选出来多条，此时需要第三方保证筛选条件的正确性。
  • 2.如果只想根据固定的 ID 进行更新，请使用数据唯一。（唯一标识是「智能 api」-「获取数据（多条或者单条）」返回数据中的 recordId）
  • 3.空值跳过筛选的含义为，如果请求筛选的字段为空， 将不加入到筛选条件中。如果想筛选控制，请取消勾选。

配置流程

  • 1.配置中间变量。（此处的中间变量，筛选条件和更新表单控件都可以进行公用。）
  • 2.设置筛选规则。如果筛出来数据为多条则多条更新，如果没有则一条也不更新。
  • 3.设置更新规则。
  • 4.设置创建后的 responseBody


9.接口-添加或更新表单

接口描述

  • 这个接口类似于 我们在 sql 中使用 Insert Or Update 功能，如果存在更新，不存在则创建。

  • 同理，平台先根据传入的参数，进行筛选数据，如果不存在就进行写入，如果存在就直接更新。

数据处理流程

第三方系统请求数据—>开放平台接受数据—>根据预设的 JSONPath 进行提取变量数据—>筛选更新的目标（1 条或多条）—>更新数据or 创建数据—>返回成功标识–>表单在速融云内部进行流转。

配置流程

  • 1.配置提取的中间变量。（此处的中间变量，筛选条件和更新表单控件都可以进行公用。）

  • 2.设置筛选规则。如果筛出来数据为多条则多条更新，如果没有则创建。

  • 3.设置更新规则和创建规则

  • 4.设置创建后的 responseBody


10.接口-删除表单

接口描述

根据筛选条件对一批数据执行删除操作。

数据处理流程

第三方系统请求数据—>开放平台接受数据—>根据预设的 JSONPath 进行提取变量数据—>筛选更新的目标（1 条或多条）—>删除数据—>返回成功标识
注意：
1.筛选的数据有可能筛选出来多条，此时需要第三方保证筛选条件的正确性。
2.如果只想根据固定的 ID 进行删除，请使用数据唯一。（唯一标识是「智能 api」-「获取数据（多条或者单条）」返回数据中的 recordId）
3.空值跳过筛选的含义为，如果请求筛选的字段为空， 将不加入到筛选条件中。如果想筛选控制，请取消勾选。
4.如果筛选出多条数据，可以选择停止删除。

配置流程

1.配置中间变量。（此处的中间变量，筛选条件和更新表单控件都可以进行公用。）
2.设置筛选规则。
3.删除所有筛选出来的数据

11.接口-获取批量数据

接口描述

根据条件查询一批数据，支持分页获取。

数据处理流程

第三方系统请求数据—>开放平台接受数据—>根据预设的 JSONPath 进行提取变量数据—>筛选更新的目标（1 条或多条）—>返回数据
注意：

  • 1.分页获取 page =1 是第一页数据。

  • 2.在设置JSON 返回模板时，请务必保证字段名与字段类型保持一致。否则系统将会过滤掉不合法的字段.数据将无法返回。修改表单空名称后，需要进行二次修改

    • 字段模板构造示例： $${SINGLELINE_ke2gu300UkvW107H#表单名称}$$ SINGLELINE_ke2gu300UkvW107H为字段 ID 表单名称为控件名称。

配置流程

  • 1.配置中间变量。（此处的中间变量，筛选条件和更新表单控件都可以进行公用。）
  • 2.设置筛选规则。
  • 3.设置返回body模板


 注意：返回的类型统一为 其中 {responseBody} 为我们的 json 模板

12.接口-获取单条数据

接口描述

  • 根据条件查询一条数据，如果筛选出来是多条数据，则返回第一条数据。

  • 一般使用recordId 获取具体的示例详情

  • 注意，单条数据与多条基本一致，需要说明的是，返回接口不一致，-获取单条数据返回的是对象，而多条是 List 需要注意。

以上内容是否对你有帮助？