Configuring the Sender REST Adapter

PDF download from SAP Help Portal:

http://help.sap.com/saphelp_nw73ehp1/helpdata/en/c8/0bd82a4a4c4408925110371b9a7643/content.htm

Created on July 19, 2016

The documentation may have changed since you downloaded the PDF. You can always find the latest information on SAP Help
Portal.

Note

This PDF document contains the selected topic and its subtopics (max. 150) in the selected structure. Subtopics from other structures are not included.

2016 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose
without the express permission of SAP SE. The information contained herein may be changed without prior notice. Some software products marketed by SAP
SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are
provided by SAP SE and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP
Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set
forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional
warranty. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE in
Germany and other countries. Please see www.sap.com/corporate-en/legal/copyright/index.epx#trademark for additional trademark information and notices.

Table of content

PUBLIC Page 1 of 5
2014 SAP SE or an SAP affiliate company. All rights reserved.
 Table of content
1 Configuring the Sender REST Adapter

PUBLIC Page 2 of 5
2014 SAP SE or an SAP affiliate company. All rights reserved.
 1 Configuring the Sender REST Adapter
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.
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.
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.
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

PUBLIC Page 3 of 5
2014 SAP SE or an SAP affiliate company. All rights reserved.
 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

PUBLIC Page 4 of 5
2014 SAP SE or an SAP affiliate company. All rights reserved.
 {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.

Related Information
Quality of Service

PUBLIC Page 5 of 5
2014 SAP SE or an SAP affiliate company. All rights reserved.