Configuring a Gateway Integration Endpoint - REST

A gateway integration endpoint (GIEP) allows STEP to communicate with an external storage system. Once a GIEP has been created and REST is selected, the configuration settings allow you to identify the location of the required data.

To use mTLS or TLS with this type of endpoint, refer to the Mutual Transport Layer Security topic.

Prerequisites

Configure data for the dropdown parameters:

1. Configure the Server URL dropdown parameter using the RESTGateway.ServerURL property. If necessary, use a comma to separate multiple URLs. For example, using this configuration, two options are displayed in the 'Server URLs' dropdown:

   

   When configuring the Address Typeahead functionality (in the Web User Interfaces documentation), use the URL for the applicable address search service:

   • Loqate - https://api.addressy.com/

   • Google Places - https://maps.googleapis.com/maps/api/place/

   • For other address service options, refer to the service documentation for the relevant URL.

2. Configure the RESTGateway.Timeout property to set the timeout in seconds on HTTP requests made through REST gateway calls. The default timeout is 30 seconds and displays in light gray text. There is no parameter in the Configuration dialog for this setting.

   

3. Proxy Configuration dropdown parameter. Proxy functionality is intended for facilitating internet access, which is always available from SaaS environments. If a proxy is necessary for your scenario, contact Stibo Systems Support.

Configuration

The following steps are for REST configuration.

1. On the Gateway Integration Endpoint Configuration dialog, use the following parameters to specify the external system the gateway integration endpoint will access.

   

   • Server URL - The URL of the server to be accessed from the dropdown. Dropdown options are provided as defined in the Prerequisites section above.

   • Default content type - Data format or content type to be used for the endpoint. Type your own or select from the dropdown list of the most commonly used options.

   • Statistic groups - Optional. Regular expression can be used to group executed REST methods on the endpoint's Statistics tab. The regular expression must match the entire URL, for example, .*/products/.*. Use the regular expression syntax available in Java in the java.util.regex.Pattern class. For more information, refer to the Gateway Integration Endpoint Statistics topic or the Regular Expression topic in the Resource Materials online help documentation.

   • SSL trust store location - The trust store holds certificates that verify that the system can be trusted. This is legacy functionality that is not required to be set and is replaced by the global trust store configuration. For more information, refer to the Mutual Transport Layer Security topic.

   • Proxy Configuration - Proxy functionality is intended for facilitating internet access, which is always available from SaaS environments. If a proxy is necessary for your scenario, contact Stibo Systems Support.

2. Click Save to complete the configuration.

3. Enable the endpoint as defined in the Running a Gateway Integration Endpoint topic.

4. Test the connection from the gateway as follows:

   • On the Gateway Connectivity flipper, click the Check Connectivity button.

   • In the Check Connectivity dialog, in the Java Script Check Code section, add an option:

     gateway.get()
     gateway.put()
     gateway.post()

     

   • Click the Check Connectivity button and verify success or make the necessary corrections to connect.

5. Create the following as needed:

   • JavaScript business action to access the gateway endpoint, as defined in the Gateway Integration Endpoint Bind topic of the Resource Materials online help documentation.

   • Address Typeahead to access an address search service, as defined in the Address Typeahead topic of the Web User Interfaces documentation.

Authentication

The gateway integration endpoint REST plugin supports both basic authentication and token-based authentication.

Basic Authentication

With preemptive authentication enabled, the basic authentication value for the Authorization header is sent with the first request to the external service instead of only sending the value after having received a basic authentication challenge from the service.

Token-Based Authentication

With the token-based authentication option, the responsibility for producing any required request headers is delegated to a business function. The business function must be configured to not expect any input and must produce a Map<String, String>, each map entry being a header to be sent with the request to the service.

The screenshot below shows the editor for a compatible business function that retrieves a token using the OAuth 2.0 client credentials flow and passes back to the gateway integration endpoint REST plugin as a value for the Authorization header.

The JavaScript shown above can be copied below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
var map = new java.util.HashMap();
map.put("grant_type", "client_credentials");
map.put("client_id", "m2m");
map.put("client_secret", clientSecret);

var request = giep.post().urlEncodedBody(map);
var response;

try {
    response = request.invoke();
} catch (e) {
    if (e.javaException instanceof com.stibo.gateway.rest.RESTGatewayException) {
        throw "Error getting token: " + e.javaException.getMessage();
    } else {
        throw (e);
    }
}
var obj = JSON.parse(response + "");
var authHeaderValue = "Bearer " + obj.access_token;

var resultMap = new java.util.HashMap();
resultMap.put("Authorization", authHeaderValue);

return resultMap;

The parameter for selecting the business function is the 'Auth Header Value Function.' The REST plugin automatically calls the business function when a new token is required.

Note: It is strongly discouraged to configure both basic authentication and token-based authentication since this configuration is not supported.