PI REST Adapter – Using dynamic attributes

[alex_bundschuh]

This blog is part of a collection of blog entries that shows architectural concepts and configuration of the SAP PI REST Adapter. We also added some sample scenarios to make it easier for you to understand how your scenario can be implemented using the PI REST Adapter.

If you haven’t done so far, best is to start with the very first blog PI Rest Adapter - Don't be afraid within the blog series covering the concepts of the REST adapter. A complete list of all blog entries can be accessed from here PI REST Adapter - Blog Overview.

The current blog shows you along a sample scenario which kind of dynamic attributes are supported and how you can use them.

Scenario

Referring to the flight scenario that we have introduced in the previous blogs PI REST Adapter – JSON to XML conversion and PI REST Adapter – Defining a dynamic endpoint, we will do further enhancements by using the dynamic adapter specific message attributes of the REST adapter. If you haven’t done so far, you should first read the previous blogs to make yourself familiar with the scenario. In short, we provide a RESTful service in order to read different kind of flight information. Within PI, the calls are routed to either function modules BAPI_FLIGHT_GETDETAIL or BAPI_FLIGHT_CHECKAVAILABILITY.

In this blog, we would like to introduce a GET variable mode to distinguish between an expert and a default usage of the service. In the expert mode, in addition to the flight details we add the information of the return table of the function modules to the response of the service call.

To recall, this is how the respective Integration Flow looks like:

Configuring the REST sender channel

In the SAP Process Integration Designer perspective of the NetWeaver Developer Studio (NWDS), we open the existing Integration Flow, and double-click on the sender channel of type REST to open the channel editor. Switch to the REST Resources tab below the Adapter-Specific tab. The rest of the settings remain unchanged.

We can use dynamic attributes to store information of the service call which we then can be used to control the message flow. The REST adapter comes with a set of predefined adapter specific message attributes such as resource, service, and id which are commonly used among RESTful services. In addition to the predefined attributes you can also define custom attributes which are then added to the header of the PI message.

First, we would like to define the resource as constant value flights. Add a new dynamic attribute REST Resource (resource) from the Dynamic Attribute drop down menu, select Manual Value as Value Source, and enter flights into the Static Value field.



Next, we would like to define two IDs based on the JSON payload, one for the airline identity, and one for the connection number. Add a new dynamic attribute REST ID (id) from the Dynamic Attribute drop down menu, select JSON Content Element from the Value Source drop down menu, and enter the respective JSON Element from the JSON payload, here FlightDetails.AirlineID. Proceed accordingly for the JSON element FlightDetails.ConnID.



Finally, we define a custom attribute called mode. Select --- Custom Attribute --- from the Dynamic Attribute drop down menu, enter the Custom Attribute Name mode, select GET Variable from the Value Source drop down menu, and enter the GET Variable Name mode. Though I have chosen here the same name, the custom attribute name and the GET variable name do not have to be identical. Note, that you must not add the GET variable to the url pattern, in our example it remains /{service_part}.

Enhancing the mapping of the response

Based on the mode attribute, we either like to add the return table to the response or not. So, we need to change the message mapping of the response message. Within the mapping, we need to access the dynamic attribute. I have created a user defined function getASMA to read the value of the dynamic attribute which we will use in the mapping:

@LibraryMethod(title="getASMA", description="get adapter specific message attribute", category="UDFPool", type=ExecutionType.SINGLE_VALUE

     public String getASMA (

       @Argument(title="") String namespace,

@Argument(title="") String attribute,

             Container container)  throws StreamTransformationException{

            Map<String, Object> all = container.getInputHeader().getAll();

            DynamicConfiguration dynConf = (DynamicConfiguration)all.get(StreamTransformationConstants.DYNAMIC_CONFIGURATION);

            DynamicConfigurationKey key = DynamicConfigurationKey.create( namespace, attribute);

            String value = dynConf.get(key);

                          return value;

     }

From the Integration Flow, you can double click on the operation mapping to navigate to the respective message mapping in the ESR. Expand the source and target structure, and define a new field mapping for the node return. The target node return should be created if the attribute mode equals expert. As you can see from the figure below, we first call the user defined function getASMA. As input parameter of the function I pass the key of the attribute, in our case name mode with namespace http://sap.com/xi/XI/System/REST. The output value of the getASMA function is compared with the constant value expert using standard function equalsS. In case of boolean true, the node is created. Below the return node, the child nodes need to be mapped from the respective nodes of the source structure.

Running the scenario

For testing the scenario we use the Advanced REST Client Application in the Google Chrome browser. The endpoint URL of your RESTful service starts with http://<host>:<port>/RESTAdapter with host and port of the SAP PI system, followed by what you have defined in the sender channel, here /demo/flight/<service>. Since we have defined a GET variable, we need to add the GET variable to the URL. Let’s stick here to the checkavail service.

First, I call the service with the default mode info. The URL is as follows: http://<host>:<port>/RESTAdapter/demo/flight/checkavail?mode=info



The response is as follows:



Let’s change the date of the flight details intentionally to a flight that does not exist, and call the service with the expert mode. The URL is as follows: http://<host>:<port>/RESTAdapter/demo/flight/checkavail?mode=expert



In the response you can see that the return items have been added.



You can access the dynamic attributes values from the DynamicConfiguration message header. In the message monitor, select the corresponding message, switch to tab Message Content, and open the DynamicConfiguration message header.



Here you can see additional attribute values that we have added.



I hope this blog was helpful to understand the various options that you have to define dynamic attributes within the SAP PI REST adapter. If you like to learn more, check out the other blogs in the series, accessible from the main blog PI REST Adapter - Blog Overview.