System Integration

This system supports customized development for system integration using the Groovy (opens new window) language. The Groovy language is a superset of the Java language, supporting Java syntax but adding more dynamic features, making it more suitable for domain modeling and runtime enhancement.

Target Audience

The target audience of this document is: developers and implementers of this system

Integration Definition

System integration includes two types:

1. Integration definitions of type Incoming, used to automatically generate interfaces for third-party systems to call.
2. Integration definitions of type Outgoing, used to call related interfaces of third-party systems during the CUD (Create, Update, Delete) lifecycle of Domain objects, for data pushing or notification.

The system provides a way to create data integration definitions through the interface, with the following steps:

1. Create dynamic logic of type Dynamic Integration Core Logic in the system, and implement the logic for accepting external interface data transfer or sending data externally in the dynamic logic.
2. If you need to decide whether to execute the core logic of the integration at runtime based on interface calls or object data according to business scenarios, you can create dynamic logic of type Dynamic Integration enable logic, and use it when creating system integration in the next step.
3. Create a system integration object of type Incoming/Outgoing in the system.

TIP

When creating an Incoming type integration definition, the system will automatically generate a request path for the webhook interface that can be called by external systems and is only applicable to that webhook interface.

For both Incoming and Outgoing type integration definitions, the system will automatically generate a user, which will be used as the execution user context when the system executes the related logic of the integration in the future.

Incoming Integration

Injected Variables

The injected variables available in the enable and core logic execution of the data incoming interface are shown in the following table:

Variable Name	Variable Type	Description
integration	tech.muyan.dynamic.integration.DynamicIntegration	Current executing integration object definition
headers	Map<String, String>	Request headers
parameters	java.lang.Object	Request body or request parameters
requestTime	java.time.LocalDateTime	Request time
requestUrl	java.lang.String	Request URL without queryString
userContext	grails.plugin.springsecurity.userdetails.GrailsUser	Current operating user information
organization	tech.muyan.Organization	Organization to which the integration object belongs
application	grails.core.GrailsApplication	Current grails application context
log	Closure<?>	Log closure for printing execution logs

TIP

• For incoming integration requests with HTTP Method GET, the parameters parameter is a list of url parameters, of type grails.web.servlet.mvc.GrailsParameterMap
• For incoming integration requests with HTTP Method POST, the parameters parameter is the content of the http request body, of type org.grails.web.json.JSONObject

Return Results

The following lists the result types that should be returned after the execution of Enable Logic and Core Logic respectively

Enable Logic Return Result

The structure of the return result after Enable Logic execution is as follows

// 表示该 action 或 task 或 widget 是否启用
// Indicates whether this action or task or widget is enabled
[result: true | false]

Core Logic Return Result

After the core logic of the integration definition runs, it should return a result of type Map<String, Object> to the system, which the system will directly JSON-ify and return to the caller.

HTTP Response Status Code Explanation

The following lists the system's HTTP response status codes in different scenarios

Scenario Description	Status Code
No integration definition found based on the call URL	404
Multiple integration definitions found based on the call URL	500
Found integration definition is not activated or not within valid period	200
Enable Logic in integration definition returns false when executed	200
Core logic executed successfully	200
Any exception thrown during integration execution	500

WARNING

Please do not make business judgments based on the system's return message text, as this information does not guarantee compatibility with system upgrades

TIP

The calling path for incoming integration definitions is: /webhook/<webhookKey>, currently supporting two calling methods: get and post.

Regenerate Webhook Interface Path

To avoid security risks caused by webhook call address leakage, the system provides the functionality to regenerate the webhook interface path.

On the integration list page, select the integration definition that needs to regenerate the interface path, and run the Regenerate URL action to regenerate the interface path. The original interface path will be disabled.

Outgoing Integration

Data outgoing integration is used to notify other external systems when Domain data in the system is created, updated, or deleted.

Injected Variables

The following is a list of injected variables in the context when the data outgoing interface is called:

Variable Name	Variable Type	Description
integration	tech.muyan.dynamic.integration.DynamicIntegration	Current executing integration object definition
object	<? extends GormEntity>	Object instance triggering the integration
oldObject	<? extends GormEntity>	Object before modification (only modified attributes)
newObject	<? extends GormEntity>	Object after modification
objectType	tech.muyan.DomainClass	Type of the current operating object
eventType	tech.muyan.enums.OutgoingIntegrationListenEvent	Domain CUD event triggering the integration
userContext	grails.plugin.springsecurity.userdetails.GrailsUser	Current operating user information
organization	tech.muyan.Organization	Organization to which the integration object belongs
application	grails.core.GrailsApplication	Current grails application context
log	Closure<?>	Log closure for printing execution logs

WARNING

• For CREATE events, the oldObject variable will not exist in the context
• For DELETE events, the newObject variable will not exist in the context
• The oldObject object will only contain modified attributes, while the newObject object contains all attributes

Return Results

Enable Logic Return Result

The structure of the return result after Enable Logic execution is as follows

// 表示该 action 或 task 或 widget 是否启用
// Indicates whether this action or task or widget is enabled
[result: true | false]

Core Logic Return Result

Core Logic should return an object of type Map<String, Object>, with the following structure

[
  //是否需要平台调用集成的目标 Http 接口
  //Whether to call the target Http interface of the integrated platform
  requestNeeded? : true | false 
  //如需平台调用集成的目标 Http 接口，使用的请求头列表
  //The list of request headers used if let platform to call the target Http API
  headers? : Map<String, String> 
  //如需平台调用集成的目标 Http 接口，使用的请求体或请求参数及值列表
  //The list of request bodies or request parameters and values used if let platform to call the target Http API
  body? : Map<String, Object> 
]

For GET integration requests, the system will format this Map into the form of key1=value1&key2=value2, and append it to the request URL to request the address in the integration.

For POST integration requests, the system will format this Map into a JSON object, and use it as the request body to request the address in the integration.

If the customized code returns an element with the key requestNeeded and value true, or if the return result does not contain an element with the key requestNeeded, the platform will use the returned headers and body data to call the target HTTP interface of the integration.

If the customized code returns an element with the key requestNeeded and value false, the platform will not call the target HTTP interface of the integration, and the customized code needs to make the relevant http calls itself.

WARNING

For outgoing integrations that delegate HTTP requests to the system framework, currently only get and post calling methods are supported.

TIP

The execution of outgoing integration is implemented through a background asynchronous call, which does not affect the performance and success/failure status of the Domain data operation itself.

Enabling Rules for Data Integration Interfaces

Whether the core logic of system integration is called depends on the following judgment conditions:

1. Whether the active field of the integration definition is true
2. Whether the current date is between the effectiveDate and expiryDate of the integration definition
3. Whether the integration definition has not defined enableLogic, or its enableLogic execution returns a value of true

These three conditions will be judged in the order of 1, 2, 3.

Debugging and Problem Troubleshooting

The execution records of integrations are saved in the DynamicIntegrationExecRecord object.

For incoming integrations, the system will save the following information of the incoming HTTP request in the execution result:

• HTTP Method of the request
• Request headers
• Request parameters
• Enable logic execution result

For outgoing integrations, in addition to the above request parameters for third-party systems, the system will also save the response information received after requesting the third-party system in the execution result field, specifically including:

• HTTP status code of the response
• HTTP header information of the response
• HTTP Body of the response

In addition, as with other types of DynamicLogic execution, the log method can also be used for logging in the implementation code of the integration, and the printed logs will be saved in the log column of the execution record.