PDF Download
PDF Download
PUBLIC
Warning
This document has been generated from the SAP Help Portal and is an incomplete version of the official SAP product
documentation. The information included in custom documentation may not re ect the arrangement of topics in the SAP Help
Portal, and may be missing important aspects and/or correlations to other topics. For this reason, it is not for productive use.
This is custom documentation. For more information, please visit the SAP Help Portal 1
1/18/2023
Prerequisites
You have created a receiver channel using adapter type REST and chosen to con gure it in the Integration Directory.
Procedure
If the REST service provider can be reached using an HTTP proxy server, you can con gure 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.
User-de ned HTTP header elements can be de ned on the HTTP Headers tab. User-de ned headers will override any
automatically added headers – for example de ning the Authorization header will override other authentication settings
in the channel.
The header value may contain all placeholders de ned on the REST URL tab.
For TLS/SSL-enabled endpoint authentication using X.509, you can con gure certi cates: If the server requests a
certi cate from the client, activate Use Client Certi cates and specify the name of the key store in Key Store View and
the certi cate 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 pro le, activate Authorize with OAuth and
select the SAML Bearer Assertion ow.
Specify the URL of the access token endpoint in the Access Token URL parameter and con gure the SAML speci c
settings expected by this endpoint in the options SAML Issuer, SAML Audience and SAML Recipient. Select the
certi cate 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.
De ne Network Timeouts
You can con gure Connection and Socket Timeouts by specifying the time to wait in seconds. The default value is 300.
De ne 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.
Note
The pattern and the generated URL must be in URL-encoded form. No automatic conversion is applied.
Sources of Resources
This is custom documentation. For more information, please visit the SAP Help Portal 2
1/18/2023
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 elds 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 elds, a new group or a table is displayed. You can
de ne 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 Type (Enter for additional elements) Description / Expression
elements)
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.
Interface (Interface)
To Service (ToService)
To Party (ToParty)
De ne REST Operation
Operation Source
Operation Source
This is custom documentation. For more information, please visit the SAP Help Portal 3
1/18/2023
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-speci c element by selection from
the Binding Element list.
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 eld for each
operation. If more than one value of the de ned source is associated with an operation, you can de ne 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.
De ne 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.
De ne 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 speci ed by the Character Set
source and a value (if applicable). You have the following options:
Use a xed Manual Value and provide a Character Set Name (default is UTF-8)
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 con gured in the Escape sequence
option.
De ne Operation Rules
Specify how XI operations map to REST resources by mapping the name of the incoming operation/message type back
to adapter-speci c 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
This is custom documentation. For more information, please visit the SAP Help Portal 4
1/18/2023
The REST resource by the Variable that holds the information and its value
De ne 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
Result
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-speci c 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-speci c 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 nd 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.
This is custom documentation. For more information, please visit the SAP Help Portal 5