Configuring the Receiver REST Adapter

Configure the receiver REST adapter to send information from the Integration Server to a Web service provider.

Prerequisites

You have created a receiver channel using adapter type REST 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 Custom HTTP Headers

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

    The header value may contain all placeholders defined on the REST URL tab.

  • 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 Userame and Password.

    If the server requires authentication with the OAuth SAML Bearer Token profile, activate Authorize with OAuth and select the SAML Bearer Assertion flow.

    Specify the URL of the access token endpoint in the Access Token URL parameter and configure the SAML specific settings expected by this endpoint in the options SAML Issuer, SAML Audience and SAML Recipient. Select the certificate and key used to sign the assertion with the SAML Issuer Key Store and SAML Issuer Key Alias options.

    If the channel does not use principal propagation, specify a static user in the SAML Subject option.

  • Define Network Timeouts

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

  • Define REST URL

    Specify the target URL and the sources of information for its dynamic parts. 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.

  • URL Pattern
    The URL Pattern describes the full URL produced by this channel by using named placeholders for dynamic parts. Placeholder variable names must be enclosed in curly braces.
  • Sources of Resources
    For each of the pattern variables that make up the URL, you can specify the source of information. The REST URL tab provides convenient entry fields for up to ten variables. Specify the pattern elements as described in the table below. Once you have used one of the Pattern Variable Replacement entry fields, a new group or a table is displayed. You can define additional elements in the Additional Pattern Elements table by adding rows and entering the name of the resource in the Variable column. The following options are available:
    Sources of Resources
    Value Source (Select for common elements) Type (Enter for additional elements) Description / Expression
    Manual Value Manual Manually provide a Static Value to be used.
    Adapter Specific Attribute Header Retrieve the value from an Adapter-Specific Attribute by name. The predefined names are: service, resource, id, resource2, id2, operation.
    XML Content Element XPath Retrieve the value from an XML payload by providing the XPath Expression that locates a single element or attribute with simple text content.
    JSON Content Element JSON Retrieve the value from a JSON payload by providing a JSON Expression that locates an element with simple text content.
    Binding Element Binding Retrieve the value from a PI-specific element. The available elements in the Binding Element list and their corresponding Expression entries are as follows:
    • Interface (Interface)
    • Interface with Namespace (InterfaceNamespace)
    • From Service (FromService)
    • To Service (ToService)
    • From Party (FromParty)
    • To Party (ToParty)
  • Define REST Operation

    Specify how to determine the REST operation.

  • Operation Source
    The following options for locating the information are available:
    Operation Source
    Value Source Description / Expression
    Manual Value Manually provide a Static Value to be used; no mapping (next step) is required.
    Adapter Specific Attribute Retrieve the value from an Adapter-Specific Attribute by name.
    XML Content Element Retrieve the value from an XML payload by providing the XPath Expression that locates a single element or attribute with simple text content.
    JSON Content Element Retrieve the value from a JSON payload by providing a JSON Expression that locates an element with simple text content.
    Binding Element Retrieve the value from a PI-specific element by selection from the Binding Element list.
  • Mapping Source Values to Operation

    If you have selected a source that provides a dynamic value (everything but Manual Value), you can specify the value associated with an operation by entering an Expression. The REST Operation tab provides an entry field for each operation. If more than one value of the defined source is associated with an operation, you can define additional mappings in the Additional Operation Mapping Rules table by adding rows and entering GET, POST, PUT, or DELETE in the Operation column and the respective value in the Expression column.

  • Define Request Format

    Specify the data format of the outgoing message. You can choose whether the request Data Format is JSON or XML. To process Unstructured Text, choose JSON. The outer element of a message declares the operation/message type. You can choose to Strip Operation from Message. You specify the encoding of the message with the Character Set Name. If the expected data format is JSON, you can choose to Convert XML Payload to JSON. If messages contain a wrapper, you can choose to remove it by activating Strip Outer Element.

    If the payload is expected to contain escaped XML tag names, the channel can convert escaped characters back to their original value by enabling the Remove escaped name start character and/or Remove mangling of invalid name characters. Specify the used escape sequence in the Escape sequence option.

  • Define Response Format
    For a synchronous scenario, specify the data format of the response message. Select either XML or JSON from the Data Format list. To process Unstructured Text, select JSON. The message encoding can be specified by the Character Set source and a value (if applicable). You have the following options:
    • Use a fixed Manual Value and provide a Character Set Name (default is UTF-8)
    • Use the value from the HTTP Header (Content-type)
    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 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 an Element Name and an Element 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.

  • Define Operation Rules
    Specify how XI operations map to REST resources by mapping the name of the incoming operation/message type back to adapter-specific variables. You need to add a row to the Operation Rules table for each operation-variable pair and provide the following information:
    • The XI operation by the message type in PI associated with the desired Operation and its Namespace
    • The REST resource by the Variable that holds the information and its value
  • Define Response Determination
    Specify how the response operations map to XI operations. For each operation pair, add a row to the Response Type table and provide the following information:
    • The XI operation by the message type in PI associated with the desired Operation and its Namespace
    • The REST Response operation name and Namespace

Result

You have configured the receiver REST adapter.

Receiver Ping

When the user initiates a channel ping, the receiver 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.