REST Direct Delivery Method

The REST Direct delivery method differs from the standard REST delivery method in that the data is delivered directly to the REST service and no call-back URL is required.

This delivery option is only available in OIEPs and if the delivery fails the OIEP is disabled. There is no resilience handling.

In an OIEP, the delivery method is displayed on the Configuration tab of the editor in the Delivery Method section.

Prerequisites

Changes to the configuration properties outlined below are implemented when the server is restarted.

The REST Direct delivery method reads the outgoing file into memory before sending. To handle the size of the outgoing file and prevent time-outs and rejections you must scale the heap size.
Configure the URL dropdown parameter using the RestDirectDeliveryURL property. If necessary, use a comma to separate multiple URLs.

For example, using this configuration, two systems are displayed in the 'URL' dropdown:
Configure the RESTDirectAndDelivery.TimeoutSeconds property to set the timeout in seconds on HTTP requests made through REST calls. There is no parameter in the Configuration dialog for this setting.

Configuration

For information on a parameter, hover over the parameter field to display help text.

For Select Delivery Method, choose REST Direct.
In URL, select the URL that points to the REST endpoint where the delivered data should be received.
Proxy Config. 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.
In the HTTP Method option, use the dropdown to select a POST, PUT, or PATCH method.

If required, in the Query Parameters field add any query parameters that are required for a successful REST transaction. Click on the Add parameter link to add the first query parameter. Once a query parameter is added, click the ellipsis button () to add additional query parameters. To remove query parameters, click on the 'X.'
For Headers, click the Add Parameter link and add a key and a value. This is part of the HTTP network protocol.
On the Add parameter dialog, click the OK button and the Header is displayed in the field. If multiple headers are needed, use the Add Parameter link to add each additional key and value pair.

Note: Once a header is displayed, click the ellipsis button () to edit it or the X button to remove it.

For more information about headers, refer to the 'Additional Request Information' section at the end of this topic.
In Footer, add data required for the recipient to verify that the full message was received. This is part of the HTTP network protocol but not required.

The footer can be used to mark the end of a multi-part REST call (that is a REST call containing the payload split in more packages). The footer could also contain a checksum that the receiver can use to detect if the payload in a multi-part message has been changed by the middleware.
In Zip Content, specify whether to zip the contents before upload.
In ZIP Include Timestamp, choose whether or not the filename of the zip file includes a timestamp. Enabling this option may make it easier to distinguish between files.
In Report HTTP Response Body Error, select ‘Yes’ to include the HTTP response body in the BGP execution report. If an HTTP error occurs, the first 4,000 characters of the response body will be added to the report. By default, this option is set to 'No’.
Optionally, complete the required parameters for Basic Authentication, Token-based Authentication, or mTLS Authentication as described in the Authentication section below.
On the Edit Delivery Configuration dialog, click the OK button to save the delivery method.

Authentication

The REST Direct delivery plugin supports both basic authentication, token-based authentication, and mutual authentication.

Basic Authentication

For basic authentication, enter the username and password and specify whether or not the plugin should use preemptive authentication. With preemptive authentication enabled, the basic authentication value for the Authorization header will be 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 is a header that will be sent with the request to the service.

Mutual Authentication

For mutual authentication (mTLS), configure the Certificate Key Store. Mutual authentication provides enhanced security compared to basic authentication.

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

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

The REST Direct delivery plugin will automatically call the business function when a new token is required.

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

Additional Request Information

By default, the REST Direct delivery option sends multipart/form-data POST requests with the exported file available in the part named 'file' with Content-Type application/octet-stream. The example below shows the properties for such a request:

Headers

Accept-Encoding = gzip,deflate

Connection = close

Content-Length = 1354

Content-Type = multipart/form-data; boundary=JN_qruUpDaHqm9BgW_b4-adAHDftQbjuvDI

Body (Metadata)

Content-Disposition: form-data; name="file"; filename="result.zip"

Content-Type: application/octet-stream

Via the UI it is possible to change the HTTP method and also to overwrite the Content-Type header. For instance, this header could be set to 'application/xml' for a STEPXML export (unzipped) thereby overwriting the default 'multipart/form-data' value making the request properties be:

Headers

Accept-Encoding: gzip,deflate

Connection: close

Content-Length: 1354

Content-Type: application/xml

Body <The exported XML>Additional Request Information

Headers

Accept-Encoding = gzip,deflate

Connection = close

Content-Length = 1354

Content-Type = multipart/form-data; boundary=JN_qruUpDaHqm9BgW_b4-adAHDftQbjuvDI

Body (Metadata)

Content-Disposition: form-data; name="file"; filename="result.zip"

Content-Type: application/octet-stream

Headers

Accept-Encoding: gzip,deflate

Connection: close

Content-Length: 1354

Content-Type: application/xml

Body <The exported XML>