系统集成

本系统支持使用 Groovy (opens new window) 语言进行系统集成的客制化开发, Groovy 语言是 Java 语言的一个超集， 其支持 Java 语言的语法，但增加了更多动态特性， 更加适用于进行领域建模和运行时增强。

目标读者

本文档的目标读者为：本系统的开发和实施人员

集成定义

系统集成包括两种类型:

1. 集成类型为 Incoming 的集成定义，用于自动生成接口，供第三方系统调用。
2. 集成类型为 Outgoing 的集成定义，用于在 Domain 对象 CUD(创建，更新，删除) 的 生命周期，调用第三方系统的相关接口，进行数据推送或通知。

系统提供通过界面创建数据集成定义的方式，具体步骤为:

1. 在系统中创建类型为 Dynamic Integration Core Logic 的动态逻辑，并将承接外部 接口传递数据或向外发送数据的逻辑在动态逻辑中进行实现。
2. 如果需要根据业务场景，在运行时，需要根据接口调用或对象的数据来决定是否执行该 集成的核心逻辑，则可创建类型为 Dynamic Integration enable logic 的动态逻辑， 并在下一步骤创建系统集成时，进行使用。
3. 在系统中创建类型为 Incoming/Outgoing 的系统集成对象。

提示

创建 Incoming 类型的集成定义时，系统会自动生成一个可供外部系统调用的，只适用于 该 webhook 接口的请求路径。

对于 Incoming 和 Outgoing 类型的集成定义，系统均会自动生成一个用户，在后续系 统执行该集成的相关逻辑时，均会使用该用户作为执行的用户上下文。

传入集成

注入变量

数据传入接口的启用和核心逻辑的执行中，可用的注入变量如下表所示：

变量名称	变量类型	描述
integration	tech.muyan.dynamic.integration.DynamicIntegration	当前执行的集成对象定义
headers	Map<String, String>	请求头
parameters	java.lang.Object	请求体或请求参数
requestTime	java.time.LocalDateTime	请求的时间
requestUrl	java.lang.String	不包含 queryString 的请求 URL
userContext	grails.plugin.springsecurity.userdetails.GrailsUser	当前操作的用户信息
organization	tech.muyan.Organization	执行集成对象的所属组织
application	grails.core.GrailsApplication	当前的 grails 应用上下文
log	Closure<?>	用于打印执行日志的 log 闭包

提示

• 对于 HTTP Method 为 GET 的传入集成请求，parameters 参数为 url 参数的列表，其类型为 grails.web.servlet.mvc.GrailsParameterMap
• 对于 HTTP Method 为 POST 的传入集成请求，parameters 参数为 http 请求体的内容，其类型为 org.grails.web.json.JSONObject

返回结果

如下分别列出了 Enable Logic 和 Core Logic 执行应返回的结果类型

Enable Logic 返回结果

Enable Logic 运行后的返回结果的结构如下

// 表示该 action 或 task 或 widget 是否启用
[result: true | false]

Core Logic 返回结果

集成定义的 core logic 运行后，应返回 Map<String, Object> 类型的结果给系统，系 统会直接将该结果进行 JSON 化，并返回给调用方。

HTTP 回应的状态码说明

以下列出了不同场景下，系统的 HTTP 回应状态码

场景描述	状态码
根据调用 URL 没有找到集成定义	404
根据调用 URL 找到了多个集成定义	500
找到的集成定义未激活或不在有效期内	200
集成定义中的 enable Logic 执行返回 false	200
Core logic 执行成功	200
集成执行过程中抛出任何异常	500

注意

请勿基于系统的返回信息文本进行业务判断，因该信息不保证对系统升级的兼容性

提示

传入集成定义的调用路径为: /webhook/<webhookKey> ，当前支持 get 和 post 两 种调用方式。

重新生成 webhook 接口路径

为避免 webhook 调用地址泄露造成安全隐患，系统提供了重新生成 webhook 接口路径的功 能。

在集成的列表页面，选中需重新生成接口路径的集成定义，并运行 Regenerate URL 这个 动作，即可重新生成接口路径，原接口路径将会被禁用。

传出集成

数据传出集成用于在系统内的 Domain 数据被创建、更新、或者删除时，通知其他外部系统。

注入变量

如下是数据传出接口调用时，上下文中的注入变量列表:

变量名称	变量类型	描述
integration	tech.muyan.dynamic.integration.DynamicIntegration	当前执行的集成对象定义
object	<? extends GormEntity>	触发集成的对象实例
oldObject	<? extends GormEntity>	修改前的对象(只包含被修改的属性)
newObject	<? extends GormEntity>	修改后的对象
objectType	tech.muyan.DomainClass	当前操作的对象类型
eventType	tech.muyan.enums.OutgoingIntegrationListenEvent	触发集成的 Domain CUD 事件
userContext	grails.plugin.springsecurity.userdetails.GrailsUser	当前操作的用户信息
organization	tech.muyan.Organization	执行集成对象的所属组织
application	grails.core.GrailsApplication	当前的 grails 应用上下文
log	Closure<?>	用于打印执行日志的 log 闭包

注意

• 对于 CREATE 事件，上下文中不会存在 oldObject 变量
• 对于 DELETE 事件， 上下文中不会存在 newObject 变量
• oldObject 对象中只会包含被修改的属性，而 newObject 对象中包含了所有属性

返回结果

Enable Logic 返回结果

Enable Logic 运行后的返回结果的结构如下

// 表示该 action 或 task 或 widget 是否启用
[result: true | false]

Core Logic 返回结果

Core Logic 应返回一个 Map<String, Object> 类型的对象，返回结果的结构如下

[
  requestNeeded? : true | false //是否需要平台调用集成的目标 Http 接口
  headers? : Map<String, String> //如需平台调用集成的目标 Http 接口，使用的请求头列表
  body? : Map<String, Object> //如需平台调用集成的目标 Http 接口，使用的请求体或请求参数及值列表
]

对于 GET 集成请求，系统会将该 Map 格式化为 key1=value1&key2=value2 的形式，并 将其附在请求 URL 后，请求集成中的地址。

对于 POST 集成请求，系统会将该 Map 格式化为 JSON 对象，并将作为请求的 body， 请求集成中的地址。

如果客制化代码返回了键为 requestNeeded, 值为 true 的元素，或者返回结果中不包含 键为 requestNeeded 的元素，则平台会使用返回的 headers 和 body 数据，调用集 成的目标HTTP 接口。

如果客制化代码返回了键为 requestNeeded, 值为 false 的元素，则平台不会调用集成 的目标 HTTP 接口，需要客制化代码自行进行相关 http 调用。

注意

传出集成如果委托系统框架来进行 HTTP 请求，则当前只支持 get 和 post 两种调用方式。

提示

传出集成的执行通过一个后台的异步调用实现，不会影响到 Domain 数据操作本身的性能和 成功/失败状态。

数据集成接口的启用规则

系统集成的核心逻辑是否被调用，取决于如下几个判断条件:

1. 该集成定义的 active 字段是否为 true
2. 当前日期是否在集成定义的 effectiveDate 到 expiryDate 之间
3. 该集成定义中，未定义 enableLogic, 或其 enableLogic 执行是否返回值为 true

以上三个条件会依 1, 2, 3 的顺序进行判断。

调试及问题排查

集成的执行记录会被保存在 DynamicIntegrationExecRecord 对象中。

对于传入集成，系统会将传入 HTTP 请求的如下信息保存在执行结果中:

• 请求的 HTTP Method
• 请求头
• 请求参数
• Enable logic 执行结果

对于传出集成，除上述请求第三方系统的请求参数外，系统还会将请求第三方系统后收到的 回应信息保存在执行结果字段中，具体包括:

• 回应的 HTTP 状态码
• 回应的 HTTP 头信息
• 回应的 HTTP Body

此外，与其他类型的 DynamicLogic 执行相同，在集成的代码实现中，也可以使用 log 方法进行日志打印，打印的日志可以会保存在执行记录的 log 列。