Configure the REST Transport Connector¶
The REST Sender makes it possible to send messages to REST endpoints using JSON format and the HTTP/HTTPS protocol.
Contents¶
- Common parameters
- REST Sender specific parameters
- How to call a REST endpoint using REST Connector
- Configure REST Sender for SSL Server Authentication (https)
REST Sender specific parameters¶
- ACCEPTED_CODES
Comma or semicolon separated list of response HTTP codes for which the sender will return response body rather than throwing an exception. The actual response code is saved to Application Context with nameHTTP_RESPONSE_CODE
. - DEFAULT_RESP_ENCODING
If the response is not binary and not an XML document with valid encoding specification in the XML header, this encoding will be used to decode received response. Default is UTF-8. - TRACE_PATH
Defines the path where the trace logs (i.e. the request and response) of the sender will be created. If not specified there will be no trace logs created.
Additional parameters are specified on Routing Address for Destination Type REST.
How to call a REST endpoint using REST Connector¶
Request Method¶
When a REST call is initiated from PL/SQL logic that will be received by the middle tier via PL/SQL access provider. When a REST call is initiated through an inbound flow, the request method can be set in the REST type Routing Address. If the Http Method is set as 'NONE' in Address window then the default method is taken as 'POST'.
If HTTP Method is set from both places (PL/SQL and REST Address window), then the value set from PL/SQL is only taken.
IFS REST Sender supports below HTTP request methods.
-
GET: Can be used to put a GET request to a REST end point >>.
-
POST: Can be used to put a POST request to a REST end point. This is used in situations where you want to send data to a REST endpoint and receive a response based on the data that you have sent. The request contains a request body and the Content-Type HTTP header indicates the type of the data >>.
-
PUT: The PUT method replaces all current representations of the target resource with the request payload. This method can be used to add a new resource to the REST endpoint. The resource can take the form of a record structure or it can be binary (BLOB) data >>.
-
PATCH: The PATCH method is used to apply partial modifications to a resource endpoint.
Note: PATCH method is implemented in a way with "X-HTTP-Method-Override" request header parameter but some endpoints do not accept this header. For such you can use a new HTTP Method introduced as 'PATCH_NO-X' to be set from PL/SQL side to use with such endpoints.
- DELETE: The DELETE method deletes the specified resource >>.
How to construct the request URI¶
A REST service exposes multiple REST resources which are identified by the resource URI. When configuring the Address for the REST service you may only specify the root URL of the REST service. The complete URI of the REST resource is constructed by concatenating the root URL specified in the Address with the rest of the URI supplied using the PL/SQL code. When specifying the root URL in the Address configuration place holders are added to the URL. These can be anywhere in the URL string. The values for these place holders must be specified using the REST Sender PLSQL API (plsql_rest_sender_API).
Example: In the Address configuration Root URL is given as: http://<server>:<port>/myRestService/{parameter1}
When a call to a resource in this REST service is initiated from the PL/SQL logic the value for {parameter1} should be passed. This value should be the rest of the URI of the resource we need to access.
url := PLSQLAP_DOCUMENT_API.New_Document('url_params');
PLSQLAP_DOCUMENT_API.Add_Attribute(url,'parameter1','/myResource');
plsql_rest_sender_API.Call_Rest_EndPoint_Empty_Body2(
rest_service_ => 'MY_REST_SERVICE',
url_params_ => url,
callbackcallback_func_ => 'callback_fn',
http_method_ => 'GET',arams_ => header);
How to specify query parameters¶
A REST resource URL can contain query parameters.
As shown in the previous section the URL passed from the PL/SQL logic can contain the query parameters.
Example:
url := PLSQLAP_DOCUMENT_API.New_Document('url_params');
PLSQLAP_DOCUMENT_API.Add_Attribute(url,'parameter1','/myResource?value1=abc&value2=xyz');
Another way to specify the query parameters is to pass them from the PL/SQL logic strainght away.
Example:
url := PLSQLAP_DOCUMENT_API.New_Document('url_params');
PLSQLAP_DOCUMENT_API.Add_Attribute(url,'parameter1','/myResource');
Query_params := PLSQLAP_DOCUMENT_API.New_Document('QUERY_PARAMETERS');
PLSQLAP_DOCUMENT_API.Add_Attribute(Query_params,'value1', 'abc');
PLSQLAP_DOCUMENT_API.Add_Attribute(Query_params,'value2', 'xyz');
plsql_rest_sender_API.Call_Rest_EndPoint_Empty_Body2(
rest_service_ =>'MY_REST_SERVICE',
url_params_ => url,
callback_func_ =>'callback_fn',
http_method_ => 'GET',
http_req_headers_ =>'Content-Type:application/json',
query_parameters_ => Query_params);
How to specify Request headers¶
The HTTP request sent to the REST resource may require additional HTTP headers. There is lots of flexibility in defining these headers.
Define the headers in the Address configuration:¶
This can be done using the field Additional Header Parameters. You can directly specify the header with the value or use place holders to denote the header and the value. Define one header parameter and value per line using <parameter>=<value> format. If you have used place holders to denote the header parameter and value the actual strings that should replace the place holders have to be set in the PL/SQL logic.
Example:
Additional Header Parameters |
---|
Accept-Language={value1} |
{header1}={value2} |
header := PLSQLAP_DOCUMENT_API.New_Document('header_params');
PLSQLAP_DOCUMENT_API.Add_Attribute(header,'value1', 'en-US');
PLSQLAP_DOCUMENT_API.Add_Attribute(header,'header1', 'Accept-Encoding');
PLSQLAP_DOCUMENT_API.Add_Attribute(header,'value2', 'gzip, deflate, br');
plsql_rest_sender_API.Call_Rest_EndPoint_Empty_Body2(rest_service_ =>'My_REST_SERVICE',
url_params_ => url,
callback_func_ => 'callback_fn',
http_method_ => 'GET',
header_params_ => header);
Define the headers using PL/SQL code:¶
Specify the additional header information in the PL/SQL code that is used to initiate the REST request. Use the parameter http_req_headers_. Add the request headers and values as a comma separated list.
Example:
plsql_rest_sender_API.Call_Rest_EndPoint_Empty_Body2(rest_service_ =>'MY_REST_APP',
url_params_ => Url_params,
callback_func_ => 'callback_fn',
http_method_ => 'POST',
http_req_headers_ => 'Content-Type:application/json, Accept-Encoding: gzip',
query_parameters_ => Query_params);
How to authenticate with the REST service¶
REST service endpoints may use various authentication schemes to protect the REST resources. The REST Sender support the following authentication mechanisms at present.
Basic authentication:¶
From the drop down "Authentication Method" select Basic..Provide the login details. The entered user id and password will be base 64 encoded and include in the Authorization header of the HTTP request.
Bearer token authentication:¶
Many REST services provide an API key that can be used for authentication with the REST service e.g.: Paypal rest API. From the Authentication Method select Bearer and input the API key. The API key will be included in the Authorization header.
Azure Shared key:¶
This authentication method is used when you want to access the Azure Blob REST endpoint s to access and do operations using Azure Blob Storage. The "Shared Key" authorization as defined in Microsoft Documentation is used here. The REST Connect Sender implementation takes care of constructing the Shared Key using the information provided. When Azure Shared Key is selected as the authentication mechanism the API Key input field is displayed. Enter your Azure Storage Account's key value here. This can be obtained from the Azure Portal.
OAuth2.0 Client Credentials¶
If the REST endpoint is protected using OAuth2.0 Client Credentials flow use this authentication mechanism.
Input filed | Value |
---|---|
Client Id | Client Id given when registering with the Identity provider |
Client Secret | Client Secret given when registering with the Identity provider |
Token Endpoint | Url of the Token endpoint that should be accessed to obtain the token. |
Token Endpoint Parameters | This can be used to set optional url parameters for the token endpoint. This can be given as Key Value pairs seperated by a comma if there are multiple parameters. Example: (Parameter1=Value1, Parameter2=Value2) |
Resource | Url of the protected resource. This can be left blank if not required by the Identity provider. |
When the REST endpoint is accessed, first a call to the Token endpoint will be made with the client credentials and the resource. The token endpoint will respond with an access token. This access token will be used as a Bearer token when the call to the REST endpoint is made.
OAuth2.0 ROPC¶
If the REST endpoint is protected using OAuth2.0 Resource Owner Password Credentials flow use this authentication mechanism.
Input filed | Value |
---|---|
User Id | User Id of the registered user. |
Password | Password obtained when registering. |
Client Id | Client ID given when registering with the identity provider. |
Client Secret | Client Secret given when registering with the identity provider. |
Token Endpoint | Url of the Token endpoint that should be accessed to obtain the token. |
Token Endpoint Parameters | This can be used to set optional url parameters for the token endpoint. This can be given as Key Value pairs seperated by a comma if there are multiple parameters. Example: (Parameter1=Value1, Parameter2=Value2) |
When the REST endpoint is accessed, first a call to the Token endpoint will be made with the credentials provided. The token endpoint will respond with an access token. This access token will be used as a Bearer token when the call to the REST endpoint is made.
Getting a Response back to the PL/SQL Business Logic¶
The business logic that initiated the REST call might be interested in the response returned by the REST call. It is possible to get the result back by using response chaining to a PL/SQL method. Then using a callback function or a procedure the response can be processed as required by the application.
First create a new routing address of destination type PL/SQL. The PL/SQL Address Package Method must be the common callback function plsql_rest_sender_API.REST_Common_Callback.
In the routing rule that handles the REST request the REST endpoint must be given as the destination address of Chain Link 1. Add the PL/SQL Address (plsql_rest_sender_API.REST_Common_Callback) as the Chain Link 2. With this configuration the response from the first destination will be available as input to the second destination. So the response of the REST request will be available as a CLOB object to plsql_rest_sender_API.REST_Common_Callback function. From there the response will be sent to the callback function or procedure which was defined as the parameter callback_func_.
Plsql_rest_sender_API.Call_Rest_EndPoint(..) has the argument callback_func_ using which you can define the callback function that you want to invoke based on your business logic. When a response is received for the REST call the result will be converted to a CLOB and will be available as an input to this call back function. The application_message_id of the application message will also be available as an input for the call back. In addition to that if it is required a key_ref value which is a list of keys for the business object and the fnd_user who initiated the request can also be passed.
The callback function can have the following signatures depending on how much information is required to continue the application flow.
The default signature of the callback function/procedure:¶
This is the default signature of a function or a procedure. The procedure or function should have a CLOB input parameter for the response and a VARCHAR2 parameter for the application_message_id:
PROCEDURE REST_callback_Test (xml_ CLOB, app_msg_id_ VARCHAR2)
If response CLOB, application_message_id and key_ref are expected:¶
The procedure or function should have a CLOB input parameter for the response, VARCHAR2 parameters for the application_message_id and the key_ref.
PROCEDURE REST_callback_Test (xml_ CLOB, app_msg_id_ VARCHAR2, key_ref_ VARCHAR2)
If response CLOB, application_message_id, key_ref and fnd_user are expected:¶
The procedure or function should have a CLOB input parameter for the response, VARCHAR2 parameters for the application_message_id, key_ref and the fnd_user.
PROCEDURE REST_callback_Test (xml_ CLOB, app_msg_id_ VARCHAR2, key_ref_ VARCHAR2, fnd_user_ VARCHAR2)
A sample callback function is given below:
PROCEDURE REST_callback_Test (xml_ CLOB, app_msg_id_ VARCHAR2, key_ref_ VARCHAR2) IS
cnt_ NUMBER;
ins_stmt VARCHAR2(200);
BEGIN
cnt_ := 0;
SELECT COUNT(*) INTO cnt_ from user_tables WHERE table_name= 'REST_TEST_TAB';
IF cnt_ = 0 THEN
EXECUTE IMMEDIATE 'create table REST_TEST_TAB (app_id NUMBER, result CLOB, lu_name VARCHAR2, key_ref VARCHAR2)';
END IF;
ins_stmt := 'INSERT INTO REST_TEST_TAB VALUES (:app_id1, :result1, :key_ref)';
EXECUTE IMMEDIATE ins_stmt USING app_msg_id_, xml_, key_ref_;
END REST_callback_Test;
Getting the HTTP Response Code and the HTTP Response header fields with the response¶
If it is required it is possible to get the HTTP response code and the HTTP response headers back to the business logic along with the response. To get the response details back you have to set the parameter incld_resp_info_ to TRUE when initiating the REST call using plsql_rest_sender_API.Call_Rest_EndPoint or plsql_rest_sender_API.Call_Rest_EndPoint_Empty_Body Then the HTTP response code and the HTTP headers returned with the HTTP resonse will be available to be used by the callback function. To recieve these information the callback function should be written with parameters that would accept the response code and headers as VARCHAR2 variables. An example signature is given below:
PROCEDURE REST_callback_Test(xml_ CLOB, app_msg_id_ VARCHAR2, rep_code_ VARCHAR2, headers_ VARCHAR2)
Getting notifications about the failed messages¶
When a REST endpoint is invoked from the PL/SQL business logic it may be necessary to get notifications of failed messages back to the business logic. The procedures plsql_rest_sender_API.Call_Rest_EndPoint and plsql_rest_sender_API.Call_Rest_EndPoint_Empty_Body has two parameters where you can specify whether you would like to get the failed notifications and the PL/SQL procedure that should be called when a failure occurs. The parameters are fail_notfiy_ and failed_callback_fun_.If you set the fail_notfiy_ to be TRUE it is mandatory to give a procedure to failed_callback_fun_.
Setting accepted response codes from PL/SQL logic¶
Normally a REST call is considered to be successfully completed when a response code of 200 is returned with the response. It is possible to set additional response codes to be accepted as successful responses by specifying them when the REST sender is configured (Solution Manager > Integration > IFS Connect > Setup IFS Connect > Connect Senders > REST sender instance). However these codes will apply to all the REST sender addresses that you create using the sender instance.
It may be required to set additional accepted rresponse codes per request based on the functionality. This can be done by setting the accepted_res_codes_ parameter when calling plsql_rest_sender_API.Call_Rest_EndPoint or plsql_rest_sender_API.Call_Rest_EndPoint_Empty_Body
Message Payload and the transformers¶
The message payload can be a type_record or a text containing the XML structure. This payload will be transformed to a JSON message structure before sending it to the REST endpoint.
Two default transformers can be used for this XML to JSON transformation.
- IFS_XML_TO_JSON Transformer
- IFS_XML_TO_JSON-GENERIC
- CDATA_FROM_XML Transformer
- MODEL_BASED_XML_TO_JSON Transformer
IFS_XML_TO_JSON Transformer¶
This transformer will convert the XML record structure in to the JSON record structure. The data type of each attribute will be used by this transformer when converting XML to JSON.
IFS_XML_TO_JSON-GENERIC¶
This tranformer will transform an XML record that does not contain data type information into a JSON document
CDATA_FROM_XML Transformer¶
This transformer will retrieve the value in a CDATA field of a XML. This enables JSON structure to directly send from PL/SQL logic by putting it inside a CDATA field of a XML file.
MODEL_BASED_XML_TO_JSON Transformer¶
This transformer can be used to convert XML to JSON based on the structures we create in projections while identifying correct data types of attributes and arrays.
Since it’s model based, it needs the projection and structure name as input. So these information has to be given as inputs to the transformer.
If you are working with projection type routing address, these inputs will be automatically taken from the routing address itself (from Projection Resource field).
If you use this transformer with any other routing address type, you have to provide that information with the input XML itself as below.
<?xml version = "1.0" encoding = "UTF-8" standalone = "yes"?>
<TransformerRequest>
<Params>
<Projection>ProjectionName</Projection>
<Type>STRUCTURE</Type>
<Name>StructureName</Name>
</Params>
<Data>
<YOUR_XML_DATA>
</Data>
</TransformerRequest>
Configure REST Sender for SSL Server Authentication (https)¶
Server Authentication means that client (REST Sender) will not authenticate itself, but it will require that the server it connects to authenticates itself.
Server Authentication is the most common mode of SSL / TLS operation. If you are uncertain what kind of SSL mode you should configure, this is probably what you want to configure.
Whenever REST Sender attempts to connect to an external service over SSL (https protocol), it will only be able to connect to it if it can trust the certificate loaded there. As REST Sender is a Java application, the way trust is handled is that you have a keystore
(typically <java_home>/jre/lib/security/cacerts) or also known as the trust store. This contains a list of all the known CA certificates and Java will only trust certificates that are signed by those CA certificate or public certificates that exist within that keystore
.
So if you intend to access an external service via HTTPS and a self-signed certificate or a certificate that is not signed by a CA authority is being used to secure the external service, you'll need to import the certificate to your keystore
.