Configuring the Sender REST Adapter with Polling

Configure the sender REST adapter to poll remote REST APIs and send the result to the Integration Server.

Prerequisites

You have created a sender channel using adapter type REST, used REST Polling message type and chosen to configure it in the Integration Directory.

Procedure

• Configure Proxy Server

  If the REST service provider can be reached using an HTTP proxy server, you can configure to use it. Activate Use Proxy and enter the Host name and the Port that the proxy uses to receive HTTP requests. If the proxy requires user authentication, enter Username and Password.

• Define Transport Level Security

  For TLS/SSL-enabled endpoint authentication using X.509, you can configure certificates: If the server requests a certificate from the client, activate Use Client Certificates and specify the name of the key store in Key Store View and the certificate alias in Key Store Entry. If the server requires user authentication, activate Use Basic Authentication and specify Username and Password. If the server requires authentication with the OAuth, activate Authorize with OAuth and select the appropriate OAuth flow.

• Define Network Timeouts

  Connection and Socket Timeouts can be configured by specifying the time to wait in seconds. The default value is 300.

• Define Quality of Service

  Select how the message is to be processed by the Integration Engine from the Quality of Service list. For Exactly Once In Order enter a Queue Name.

• Define REST URL

  Specify the target URL and the sources of information for its dynamic parts (incremental key variable). A REST request typically provides information about the service to be called, a resource and/or resource type, and the operation to be performed in the URL.

• Define HTTP Operation

  Specify the HTTP operation of the outgoing HTTP call. The value can be POST, PUT, DELETE or GET.

• Define Request Message

  If the HTTP operation is not GET, you can specify the outgoing request message. Specify the Request Content, the HTTP Content-type and the Character Set.

• Define Polling Interval

  Specify the interval in which the remote REST service will be called. The value defines the minimal wait interval between remote calls in seconds.

• Configuring Custom HTTP Headers

  User-defined HTTP header elements can be defined in the HTTP Headers table. User-defined headers will override any automatically added headers – for example defining the Authorization header will override other authentication settings in the channel.

  Note

  The HTTP headers of the HTTP result message are copied into the XI message as dynamic message attributes and are therefore available for later reference.

• Define Data Format

  Specify the data format of the result message. You can choose whether the request Data Format is JSON or XML. To process Unstructured Text, choose JSON. If the expected data format is JSON, you can choose to Convert JSON to XML.

• Convert JSON to XML

  If the format is JSON, the REST adapter can convert it to XML. This is necessary if you wish to do further processing in PI (mapping or routing, for example) based on the message content. Activate Convert to XML. You can also activate the Add Wrapper Element option if the JSON may contain multiple top-level elements. Enter a Name and a Namespace for the wrapper element. If the JSON request is expected to contain keys that have invalid XML Name Start or XML Name characters, activate the Escape invalid name start characters and/or the Mangle invalid name characters options. These will escape invalid characters at the start or remainder of XML tags respectively with the sequence configured in the Escape sequence option.

  Note

  If the Log JSON Message parameter is activated, the converted JSON content is logged in the message monitor.

• Split Payload into Messages

  If the response payload does contain a table like structure, the adapter allows splitting the response into several single PI messages. The table can be specified by an XPath expression, for XML based payloads, or an object name, for JSON based payloads.

• Filter out Duplicates

  Specify an XPath expression or JSON object that identifies a unique ID in the message. That ID will be used to ignore messages with an ID that has been already processed by the adapter.

• Setting up Incremental Requests

  For REST APIs that allow incremental requests, the adapter allows to store the timestamp of the latest call or a custom value (specified by an XPath expression or a JSON element). The value will be stored between the calls and can be referenced in the REST URL as a placeholder with name incrementalToken. Depending on the data type of the result message, the incremental value can be referenced as a JSON object or XPath expression in the Incremental Token Element parameter

If a value is needed even for the first call, it can be set up in the Initial Value parameter.

If the token is configured to be extracted from the message content, you can specify an action to be executed in case the response does not contain that specific element or in case the value is empty. Possible actions are:

TImestamps can be formatted using the following pattern letters:

Result

You have configured the sender REST adapter in polling mode.

Sender Ping

When the user initiates a channel ping, the channel tries to execute an HTTP HEAD call on the dynamic URL and displays the resulting HTTP header containing the URL-specific metadata.

If this call executes successfully, the dynamic URL is valid. If this call fails, the path of the URL might be wrong. The receiver channel then tries to execute an HTTP OPTIONS call, returning the resulting HTTP header with server-specific metadata.

If this call executes successfully, the host and port are valid, but the dynamic URL is not correct. If this call fails as well, the receiver simply tries to find and connect to the server. If the connection is successful, the server does not support HTTP or HTTPS. If this call fails, the host name and/or port are invalid or the server does not allow a connection at all.