Show TOC

Configuring the Sender REST AdapterLocate this document in the navigation structure

Configure the sender REST adapter to send content from remote clients to the Integration Server.

Prerequisites

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

Procedure
  • Define Request Format
    Specify the data format of the incoming 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 Content-type header
    • Retrieve the value from a Custom HTTP Header by specifying the Header Field
    • If the character set is passed as a GET Variable within the URL, provide the respective Variable Name
    • Retrieve the value from the payload by selecting JSON Content Element and providing the JSON path expression that locates the JSON Element
      Note This feature is currently only available for payloads in JSON and the value is expected to be US-ASCII.
    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.

  • 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. For Best Effort specify the response format.

    Additional ways to define Quality of Service in a more dynamic way:
    • By HTTP Operation

      For each HTTP operation (GET, POST, PUT, DELETE) you can specify a dedicated Quality of Service to be used. This is necessary for example if you want to use one channel for all operations on an entity, where the GET operation would need Best Effort while a PUT operation could use Exactly Once.

    • By Interface Operation
      If the channel is setup to support more than one XI Operation/Interface, the Quality of Service for each operation can be setup individually on the Operation Determination tab.
      Note

      If the Quality of Service is Best Effort, the default HTTP status code is 200; for asynchronous calls, it is 202.

  • Specify Response Format

    For a synchronous scenario (Best Effort), you need to specify the format and processing of the response message. You can select whether the response Data Format is JSON or XML. To process Unstructured Text, select JSON. You can choose to Strip Operation from Message (the outer element of a PI message). You specify the encoding of the message either by using the Request Message Character Set or a Manual Value. In the latter case, enter 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.

  • Specify Response HTTP Header

    You can specify the HTTP headers to be returned to the calling client on the Result HTTP Header tab. Specify a custom header name and the source from which the value will be taken. Available sources are static values, XI message attributes or parts of the message content, specified by either a JSON object name or an XPath expression.

  • Configure Channel Selection

    The channel selection parameters specify which messages will be processed by this channel. Each REST adapter sender channel has a fixed or dynamic endpoint name and will process messages that match the fixed or dynamic filter pattern only. The REST adapter exposes a fixed base endpoint URL. You can refine this address by extending it with a custom part.

    Activate Specify Endpoint and enter the custom Endpoint name extension.

    You can make this channel available for public access by activating Allow public access. This option completely disables authorization for this sender channel.

    Channels with public access allow enabling Cross-Origin-Resource-Sharing requests (CORS) by setting the CORS parameter to either Allow all clients or to Allow only specific clients. In the latter case, you have to specify a comma separated list of allowed client URIs, like "https://myHost.com, http://anotherserver.org". An asterisk symbol "*" symbol specifies that all clients are allowed.

    If you want the channel to process messages that have a specific property in the payload, activate Limit to JSON Element or Limit to XPath Element (depending on the input data format), specify the element by its JSON path or XPATH, and enter the expected value of this element in the Expression field.

    Note The value is expected to be US-ASCII.

    A REST sender channel can handle all HTTP operations. To configure the channel for a specific operation, activate Limit to HTTP Operation and choose the desired operation from the HTTP Operation list.

  • Define REST Resources

    Specify the format of the URL that this channel is meant to process and the information it holds. A REST request typically provides information about the service to be called, a resource and/or resource type, and the operation to be performed.

  • URL Pattern

    The URL Pattern describes the variable part of the URL processed by this channel by using named placeholders. You can either select one of the predefined patterns or enter a Custom Pattern. You can use placeholders other than those in the predefined patterns. Each placeholder variable name must be enclosed in curly braces.

    Do not use GET Variable in the pattern. You can can extract the values of URL variables by using Get Variable from the Operation Source definition.

  • Sources of Resources

    For each of the resources that make up a REST request, you can specify the source of the information. The REST Resources tab provides convenient entry fields for up to ten REST resources, including the most common, such as service, resource type, and resource ID. Select either one of the predefined resources or a Custom Attribute from the Dynamic Attribute list. If you select a custom attribute, you must also enter a name. Specify the attribute value as described in the table below. Once you have used one of the XI Dynamic Attribute entry fields, a new group or a table is displayed. You can define additional resources in the Additional Attributes table by adding rows and entering the name of the resource in the Variable column. The following options are available:

    Table 1: Sources of Resources
    Value Source (Select for common resources) Type (Enter for additional resources) Description / Expression
    Manual Value Manual Manually provide a Static Value to be used.
    URL Pattern Element URL Retrieve the value from the URL by specifying the Pattern Element placeholder name (excluding the braces).
    GET Variable GET Retrieve a value from the URL by providing the respective GET Variable Name.
    HTTP Header Variable Header Retrieve the value from an HTTP header by specifying the HTTP Header Element name.
    HTTP Operation HTTP Use the HTTP operation; no expression required.
    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 JPath Retrieve the value from a JSON payload by locating a JSON Element with simple text content using a JSONPath expression.
  • Define REST Operation

    Specify the REST operation to perform on the resource identified by the information on the previous tab.

  • Operation Source

    Specify how to locate the information about the REST operation to be performed. The following options are available:

    Table 2: Operation Source
    Value Source Description / Expression
    Manual Value Manually provide a Static Value to be used; no mapping (next step) is required.
    URL Pattern Element Retrieve the value from the URL by specifying the Pattern Element placeholder name (excluding the braces).
    GET Variable Retrieve a value from the URL by providing the respective GET Variable Name.
    HTTP Header Variable Retrieve the value from an HTTP header by specifying the HTTP Header Element name.
    HTTP Operation Use the HTTP operation; no expression and no mapping (next step) required.
    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 locating a JSON Element with simple text content using a JSONPath expression.
  • Mapping Source Values to Operation

    If you selected a source that provides a dynamic value (everything but Manual Value and HTTP Operation), you can specify the value associated with a REST operation by entering an Expression. The REST Operation tab provides an entry field for each REST 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 table by adding rows and entering GET, POST, PUT, or DELETE in the Operation column and the respective value in the Expression column.

  • Determine XI Operation
    On the Operation Determination tab you specify how REST operations map to XI operations. For the PI system, the incoming message needs to contain information about the operation/message type as an outer XML element of the message content. For each operation pair you need to add a row to the XI Operation table and provide the following information:
    • The REST operation by the Variable holding the information and possible values of this variable as an Expression
    • The XI operation by the message type in PI that is associated with the desired Operation and its Namespace

    If you have chosen the By Interface Operation Quality of Service, you can define the Quality of Service for each rule you have specified.

    Operation Determination

    Table 3: Values of Quality of Service
    Quality Of Service Value Note
    BestEfford BE  
    ExactlyOnce EO Default
    ExactlyOnceInOrder EOIO  

    The following 3 examples describe the mapping of incoming HTTP calls to XI Operation /Interface.

    Example 1:

    Mapping all processed calls to a specific XI Operation /Interface (here CUSTOMER_CREATE)

    Table 4: Mapping
    Variable Expression Operation Namespace Quality Of Service
    {operation} * CUSTOMER_CREATE http://demo.sap.com  

    Example 2:

    Mapping calls to different XI Operation /Interface depending on incoming HTTP operation. All calls use a QoS of ExactlyOnce, apart from CUSTOMER_GET which uses BestEffort.

    Table 5: Mapping
    Variable Expression Operation Namespace Quality Of Service
    {operation} GET CUSTOMER_GET http://demo.sap.com BE
    {operation} PUT CUSTOMER_UPDATE http://demo.sap.com  
    {operation} POST CUSTOMER_CREATE http://demo.sap.com  
    {operation} DELETE CUSTOMER_DELETE http://demo.sap.com  
    Example URL: http://host:port/RESTAdapter/Customer

    Example 3

    Mapping calls to different XI Operation /Interface depending on incoming service name. All calls use a QoS of ExactlyOnce, apart from CUSTOMER_GET which uses BestEffort

    Table 6: Mapping
    Variable Expression Operation Namespace Quality Of Service
    {service} customer_list CUSTOMER_GET http://demo.sap.com BE
    {service} customer_change CUSTOMER_UPDATE http://demo.sap.com  
    {service} customer_new CUSTOMER_CREATE http://demo.sap.com  
    {service} customer_remove CUSTOMER_DELETE http://demo.sap.com  
    Example URLs:
    http://host:port/RESTAdapter/Customer_list
    http://host:port/RESTAdapter/customer_change
    http://host:port/RESTAdapter/customer_new
    http://host:port/RESTAdapter/customer_remove

Result

You have configured the REST sender adapter. Once it is deployed you can call the sender adapter using the following base URL: <host>:<port>/RESTAdapter/. If you configured a custom endpoint the URL is <host>:<port>/RestAdapter/<endpoint name>/.

Sender Ping

Initiating a channel ping on a sender channel will display the overall status as well as the basic configuration settings such as endpoint name, URL pattern, and data format.