Consuming Your First Synchronous RESTful Service -...

Former Member · ‎05-26-2015

Introduction

This is the third part of a mini-series blog about how to build a basic SAP-to-REST synchronous interface scenario. The blog's first part can be found here: Consuming Your First Synchronous RESTful Service - Step-by-Step - Introduction. This part is to build all Enterprise Service Repository objects (design-time objects). The objects we will be building are shown in the PI dashed box in this diagram:

Let's get to work

Creating ESR Objects:

The objects will be created in the following order: Data Types, Message Types, Service Interfaces, Message Mappings, then Operation Mappings.
Start the "Enterprise Service Builder" by clicking the link on the NW Process Integration page shown above (transaction SXMB_IFR).
Once the tool starts, you need to import the SWCV we created above. This needs to be done only once.
- Click the "Create Object" button or select it from menu option: Object -> Create. Note that this is how you start the creation of any object in ESR.

In the "Create Object" pop-up screen, expand the "Work Areas" node and select object type Software Component Version. Then, in the details section, select the "Import from SLD" radiobutton then click the "Display" button.

Search for the SWCV created earlier, select it, and then click the "Import" button.

Once the SWCV is imported, verify the information and click the "Create" button.

In the SWCV details screen, you need to do two things: select a language and create a namespace. The PI Best Practices Naming Conventions document talks in details about how many namespaces you should create and the reasoning behind that. For the purposes of this blog, we will create only one namespace that will be used for all ESR objects.

Now, you should see the SWCV in the Design Objects menu. From there, all other objects will be created.

Now, we need to create data types that will "describe" what the data looks like.
- We need to know what types of data we will be sending from the SAP ECC system and what types of data we will be receiving back. Again, for our blog, the SAP ECC system will send a zip code and will want the response of the RESTful service sent back. Calling Google's map API rest service http://maps.googleapis.com/maps/api/geocode/json?address=10001 will return back a JSON message that looks like the below screenshot. You need to notice three things: the zip code in the rest service parameter list, the "results" tag, and the "status" tag. The first is the service request while the other two are the response we will be reading back. Usually, you create two data types for a request (DT1 and DT2 from the ESR Objects diagram above). The first one is for the data that goes from the sender to the PI system and the other is for the data that goes from the PI system to the receiver system. Similarly, you usually create two response data types (DT3 and DT4 from the ESR Objects diagram above). Optionally, you can create error data types (two of them as well) for transferring error details.

To create a data element, you can click the "Create Object" button (just like you did when you imported the SWCV) or you can simply right-click the newly created name space then select the "New" option.

Create a data type for the zip code field by selecting the "Data Type" option in the "Interface Objects" node. Enter the data type name and namespace (namespace will be defaulted if you created the object by right-clicking the namespace). Then, click the "Create" button.

In the data type details screen, select the first line. Then, click the "Insert New Lines" button and select the "Insert Subelement" option.

Type "zipcode" in the name field and type "xsd:string" in the type field. You can also select the XSD type from the field's value help list. Then, click the "Save" button.

Now, we need to create a data type for the response of the rest service.

In the data type details screen, insert two new subelements: "results" & "status." Both are of type "xsd:string." Notice that you need to use the names of the JSON/XML tags that you want to read. Hint:if you want to completely use XML mapping in PI, you need to build the exact XML structure with the appropriate nesting in the data type that will be used for transferring data from the rest service to the PI system.

Great! All the data types that we need are created now as you can see on the left side of the above screenshot.

The next step is to create message types that will carry the data described by the above data types.
- Again, just like with data types, you usually create two request message types (from the sender to PI and from PI to the receiver: MT1 and MT2 from the ESR Objects diagram above) and two response message types (from the receiver to PI and from PI to the sender: MT3 and MT4 from the ESR Objects diagram above). However, for simplicity, we will use one message type for the request and one message type for the response.
- Right-click the namespace to select the "New" option. Then, expand the "Interface Objects" node to select the "Message Type" object. Type a message type name for the request zip code then click the "Create" button.

In the message type details screen, type the name of the zip code data type (or select it from the value help menu). You will notice the data type fields will be displayed automatically in the message type structure section.

Similarly, create a message type for the response location details.

Save the message type and verify the message types exist under the namespace.

Now, we need to create the outbound (sender -> PI) and inbound (PI -> receiver) interfaces (OBI and IBI from the ESR Objects diagram above).
- Click the "Create New Object" button or right-click the namespace then select the "New" option. In the pop-up screen, expand node "Interface Objects" and select the "Service Interface" object type. Type the outbound service interface name and click the "Create" button.

In the details screen, make sure the interface category is "Outbound" and the mode is "Synchronous." Then, type the request and response message types (that we created earlier) in the appropriate fields. You can also select them from the field's value help menu. Then, click the "Save" button. You can enter a "fault" message type, but we will ignore that for this blog.

Similarly, start the creation of the inbound service interface.

In the details screen, make sure the interface category is "Inbound" and the mode is "Synchronous." Then, type or select the request and response message types (just like in the outbound service interface). Then, click the "Save" button.

Verify the service interfaces are now created in the namespace.

Now, it is type to create message mappings for the request and response (MM1 and MM2 from the ESR Objects diagram above).
- Click the "Create New Object" button or right-click the namespace then select the "New" option. In the pop-up screen, expand node "Mapping Objects" and select "Message Mapping." Type in a message mapping name then click the "Create" button.

In the message mapping details, click the "Select Mapping" button in both the "source" and "target" sections. Select the same message type as shown in the screenshot.

Once both message types are visible in the grid area, you need to map the source field (zipcode) to the target field (zipcode). You can either drag-and-drop the source field onto the target field or add both fields to the mapping area (by double-clicking) then map the fields there. You should have something that looks like the screenshot below.

Similarly, create a message mapping for the response.

Similarly, select the response message types.

Map the "results" and "status" fields to the "results" and "status" fields.

Drag and drop the "results" field into the lower mapping area. Then, right-click the "results" icon and select the "Return as XML" option (which should show now as checked).

Then, in the lower toolbar, select "Text" from the function drop down list.

Now, drag and drop the "trim" function to the mapping area. Map the source "results" to the "trim" function. Then, the output of the "trim" function should be mapped to the target "results" field.

Finally, verify the message mapping objects are created in the namespace.

The last object to be created in the ESR is the Operation Mapping object (object OM from the ESR Objects diagram above).
- Click the "Create New Object" button or right-click the namespace then select the "New" option.Expand the "Mapping Objects" node and select the "Operation Mapping" object type. Type an operation mapping name and click the "Create" button.

Select the outbound service interface in the source operation section and the inbound service interface in the target operation section. Then, click the "Read Operations" button.