4.2.1-interface-declaration-creation

4.2.1 Interface Declaration Creation

4.2.1.1 SOAP Protocol

Before registering an interface of the SOAP protocol, the prerequisites are to create SOAP connection service and provide correct protocol address, namely the WSDL address. Thus, the interface can be combined with the service address in the connection service to form the complete address content.

Process of Registering SOAP Protocol Interface: Integration Platform -> Third-party Interface -> Interface Declaration -> Create -> SOAP

Configuration Instructions:

Basic Information:

Interface Name: Name of the registered interface. Required.
Service: Select from the pull-down list, select the SOAP connection service created in Third-party Interface-Interface Declaration. Required.
Status: Enabled by default. The interface will be unavailable if disabled.
Function Identifier: Can be both manually or auto-filled. Only letters, numbers, and underscores are allowed, 6-32 characters. Required. This identifier is mainly used for other applications to call. For example, when the JS panel of a low-code platform calls, this function identifier will be used).
Usage Scenario: Select in the pull-down list (Fetch: e.g., query; Write in: e.g., create, modify, delete). Required.
Cache Duration: Set the cache duration. This option is required when the Usage Scenario is "Fetch".
Capability: Used to mark which applications use this interface, making it easier to quickly locate the corresponding interface within applications. Select in the pull-down list. Optional. Application scenarios are as follows (Taking Process Integration as example): a. First, configure the corresponding capability in the interface declaration, such as setting the interface name as "Acquisite Form" and the capability to "Process Integration - Form Field Value Acquisite Interface" b. In Process Platform-Process Integration-Form Integration-Interface Settings-Form Acquisite Interface, creator can locate the corresponding interface quickly.

Function Details:

WSDL Address: The description of the web service address to which the interface belongs. Required.
Details: Click "Acquisite Interface Details" to verify whether the address is valid and acquisite the list of interfaces under the service based on the current WSDL address. The interface information is displayed in the binding function pull-down list for selection.
Binding Function: Select the interface provided by the web service in the pull-down list.
Response Timeout: Set the time for calling the interface.
Pagination Query: Disabled by default, and can be enabled manually (Paginated Query cannot be enabled when the usage scenario is "Write in").

Request Parameter Settings: Automatically filled in when a binding function is selected and cannot be edited.

Returned Parameter Settings

Mapping Template: Automatically filled in when a binding function is selected and cannot be edited.
Mock Data: To customize the returned parameters, and are mainly used to temporarily configure mock data when the back-end interface is not yet developed but the front-end needs to call it for joint debugging.
Error Parameter Settings: Automatically filled in when a binding function is selected and cannot be edited.

Call Rule: Determines whether users can call this interface during runtime of the application using this interface. Disabled by default (When disabled, no users can call this interface during runtime).

Users: Refers to users who have permission to call this interface when the application or form is running. Required. Users can be designated as individuals, departments, institutions, groups, etc.
Remarks: Remarks of registering interface declaration.

4.2.1.2 JDBC Protocol

Prerequisites for Registering A JDBC Protocol Interface: Create a JDBC connection service.

Process of Registering A JDBC Protocol Interface: Integration Platform -> Third-party Interfaces -> Interface Declaration -> Create -> JDBC

Configuration Instructions:

Basic Information:

Interface Name: Name of the registered interface. Required.
Service: Select from the pull-down list, select the JDBC connection service created in Third-party Interface-Connection Service. Required.
Status: Enabled by default. The interface will be unavailable if disabled.
Function Identifier: Can be both manually or auto-filled. Only letters, numbers, and underscores are allowed, 6-32 characters. Required. (This identifier is mainly used when other applications call this interface.)
Usage Scenario: Select in the pull-down list. (Fetch: e.g., query; Write in: e.g., create, modify, delete). Required.
Cache Duration: Set the cache duration. This option is required when the Usage Scenario is "Fetch".
Capability: Used to mark which applications use this interface, making it easier to quickly locate the corresponding interface in applications. Select in the pull-down list. Optional.

Function Details:

Pagination Query: Disabled by default, can be enabled manually (Cannot be enabled when the Usage Scenario is "Write in"; Can be enabled when the Usage Scenario is "Fetch").
Script Type: Supports both General SQL and Stored Procedure.

General SQL Statement: Input the SQL statement to be executed. Required.

Request Parameter Settings: Request parameter can be left empty and is empty by default. Users can determine whether to configure request parameters according to actual needs. Request parameter should be Simple types+Object+Array. Other types are not supported. Object is allowed to contain array type property in the configuration. When setting the parameter, pay attention to the following points: (1) The parameterized SQL statement is based on OGNL expression, and must comply with MyBatis syntax rules. (2) All dynamic parameters must be added with the common alias "p", which stands for parameter. (3) The parameter path in SQL must match the request parameter property path defined in the JDBC interface declaration. (4) Input parameters can be left empty. The input parameters must match the names and data types of the input parameters referenced in the dynamic SQL when they are not empty. (5) Parameters can have custom aliases. Chinese aliases are not supported.

Take query SQL as an example, the configuration is as follows:

Returned Parameter Settings: After executing the SQL statement, the returned results can be parameterized according to actual need. Left empty by default. Pay attention to the following when setting parameters: (1) The parameter name must be the name included in the corresponding table of the current SQL statement. (2) When the Usage Scenario is "Fetch", users can set the returned result to be a single record or multiple records. When the Usage Scenario is "Write in" and the returned results contains only one field, the returned data type can be set according to the field type, such as character, number, or date. (3) When the returned data is in list format or pagination is enabled, only the multiple records option can be matched.

Single Record: The query result returns only one record, and the returned datum is an object type.
Multiple Records: The query results return all matching records, and the returned data are in list format.
Add Parameters: After selecting a single record or multiple records, set the returned parameter fields.
Extract Parameters: The extracted SQL must be parameter-free. After extraction, the output parameter fields in the SQL will be displayed in the returned parameters. Due to slight differences between the field types in the data and Java types, creator can manually adjust the field types of the returned parameters after extraction.

Call Rule: Determines whether users can call this interface during runtime of the application using this interface. Disabled by default (No users can call the interface during runtime if it is disabled).

Users: Refers to users who have permission to call this interface when the application or form is running. Required. Users can be designated as individuals, departments, institutions, groups, etc.
Remarks: Remarks of registering interface declaration

Stored Procedure: Input the stored procedure statement to be executed. Required.

Request Parameter Settings: Request parameters can be left empty and are empty by default. Users can determine whether to configure request parameters according to the actual need. Request parameter should be Simple types+Object+Array. Other types are not supported. Object is allowed to contain array type property in the configuration. When setting the parameter, pay attention to the following points: (1) The parameterized stored procedure statements are based on OGNL expression and must comply with MyBatis syntax rules. (2) All dynamic parameters must be added with the common alias "p", which stands for parameter. (3) The parameter path in SQL must match the request parameter property path defined in the JDBC interface declaration. (4) Input parameters can be left empty. The input parameters must match the names and data types of the input parameters referenced in the dynamic SQL when they are not empty. (5) Parameters can have custom aliases. Chinese aliases are not supported.

Returned Parameter Settings: After executing the stored procedure statement, users can parameterize the returned parameters according to the actual need. Left empty by default. Pay attention to the following when setting parameters: (1) The parameter name must be the name included in the corresponding table of the current SQL statement. (2) When the Usage Scenario is "Fetch", users can set the returned result to be a single record or multiple records. When the Usage Scenario is "Write in" and the returned results contains only one field, the returned data type can be set according to the field type, such as character, number, or date. (3) When the returned data is in list format or pagination is enabled, only the multiple records option can be matched.

Single Record: The query result returns only one record, and the returned data is an object type.
Multiple Records: The query results return all matching records, and the returned data is in list format.
Add Parameters: After selecting a single record or multiple records, set the returned parameter fields.
Extract Parameters: The extracted SQL must be parameter-free. After extraction, the output parameter fields in the SQL will be displayed in the returned parameters. Due to slight differences between the field types in the data and Java types, creator can manually adjust the field types of the returned parameters after extraction.

Users: Refers to users who have permission to call this interface when the application or form is running. Required. Users can be designated as individuals, departments, institutions, groups, etc.
Remarks: Remarks of registering interface declaration

4.2.1.3 REST Protocol

Prerequisites for Registering A REST Protocol Interface: Create a REST connection service and provide the correct REST interface address.

Process of Registering REST Protocol Interface: Integration Platform -> Third-party Interface -> Interface Declaration -> Create -> REST

Configuration Instructions:

Basic Information:

Interface Name: Name of the registered interface. Required.
Service: Select from the pull-down list, select the REST connection service created in "Third-party Interface-Connection Service". Required.
Status: Enabled by default. The interface will be unavailable if disabled.
Function Identifier: Can be both manually or auto-filled. Only letters, numbers, and underscores are allowed, 6-32 characters. Required. (This identifier is mainly used when other applications call this interface.)
Usage Scenario: Select in the pull-down list. (Fetch: e.g., query; Write in: e.g., create, modify, delete). Required.
Cache Duration: Set the cache duration. This option is required when the usage scenario is "Fetch".
Capability: Used to mark which applications use this interface, making it easier to quickly locate the corresponding interface within applications. Select in the pull-down list. Optional.

Function Details:

Request method: Different request methods result in different request parameter settings. The parameter settings supported by various request methods are as follows:

POST (Acquisite input parameters only from Body): Only supports setting Body parameters.
POST (Mixed input parameters): Supports setting Body parameters, URL parameters, and Header parameters.
POST (No input parameters): Does not support setting custom parameter.
GET (Input parameters only from Query): Only supports setting URL parameter.
GET (Mixed input parameters): Supports setting URL and Header parameters.
GET (No input parameters): Does not support setting custom parameter.

Request Path: Input the current interface path or the URL path where the interface is located, then combine it with the service address in the connection service to assemble the complete address content.
Pagination Query: Disabled by default, can be enabled manually (Cannot be enabled if the Usage Scenario is "Write in"; Can be enabled if the Usage Scenario is "Fetch").

Request Parameter Settings: When setting Body parameters for a POST request, the parameter format can be set to either Form format or JSON format.

Form: Parameters can be set as basic type+array type.
JSON: Parameters can be set as any type.
Extract Parameters: Parameters extraction is designed to acquisite interface returned parameters in a convenient and quick way. The data format for extracted parameters must be JSON. This function serves only as an auxiliary tool and cannot guarantee that every field matches the corresponding data type of the interface returned parameters.

Response Parameter Settings: Set returned parameters in accordance with the results returned by the interfaces. Left empty by default.

Error Settings Handling: Set the format of the error message returned by the interface. Left empty by default.

Call Rule: Determines whether users can call this interface during runtime of this application. Disabled by default. (No users can call the interface during runtime if disabled).

Users: Refers to users who have permission to call this interface when the application or form is running. Required. Users can be designated as individuals, departments, organizations, groups, etc.
Remarks: Remarks for registering interface declaration