Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Showing results for 
Search instead for 
Did you mean: 
CarlosRoggan
Product and Topic Expert
Product and Topic Expert

This  blog is about Integration Gateway in SAP Mobile Platform 3.0.

Since SP05 release, Integration Gateway supports REST services as data source.

You can now expose any REST service as OData service through Integration Gateway.

With this blog, I’d like to help you understand what has to be done.

And why.

This is kind of introduction, please stay tuned for the upcoming posts which will cover more details.

Prerequisites

  • SAP Mobile Platform 3.0 SP05 (SMP) installation.
  • Eclipse Kepler with SAP Mobile Platform Tools installed
    check this blog for help
  • Basic knowledge about SMP and Integration Gateway
    Check this blog for some introduction

Overview

  1. REST service as data source
  2. Create OData Implementation Project
  3. Create OData Model
  4. Bind data source
  5. Create Custom Code
  6. Implement the Custom Code
  7. Deploy
  8. Runtime

1. REST service as data source

Within the internet, there are lots of free REST based webservices that can be used for testing and demoing.

I’ve found a suitable one, which is free, doesn’t require registration and returns the payload in XML.

We’ll use it in the following example.

  Home: http://www.gisgraphy.com/

  Example REST call: http://services.gisgraphy.com/street/streetsearch?lat=52.52&lng=13.41

Try it out.

Please note:

Within the title of this blog, I’ve promised to keep this tutorial VERY simple.

We’ll do so by completely ignoring the response of the REST service.

It doesn’t need to make sense, it is only used for understanding the REST data source in Integration Gateway.

2. Create OData Implementation Project

Start Eclipse, change to the OData Perspective: Window -> Open Perspective -> Other… -> OData

Create a new OData Implementation Project: File > New > SAP Mobile Platform Odata Implementation Project

Provide an arbitrary name for  the project and the model.

Choose the “Target Runtime Server” as “SAP Mobile Platform 3.0 SP5” (should be preselected)

3. Create OData Model

After creation of the OData Implementation Project, the graphical OData modelling tool is opened.

If not, open it with a double-click on the <your_name>.odata file

Create an EntityType and rename it to “Street”

Create one additional property with name “StreetName”

Note:

our OData model has nothing to do with the REST service, as we're going to ignore the REST response.

At this point, we have all information that we’ll need later:

  • REST service URL
  • EntityType name
  • EntitySet name
  • Property names

4. Bind data source

Within the “Project Explorer”, select the <your_name>.odatasrv file, open the context menu and choose “Select Data Source”.

We have only one EntitySet, so it is already selected.

We’re going to implement the QUERY operation, so this has to be selected (if not already preselected)

Mark the checkbox for “REST Service”

Press “Next”.

Now we have to enter the “relative request URL”.

At this point, we have to understand:

We have a full URL for a service that returns data: http://services.gisgraphy.com/street/streetsearch?lat=52.52&lng=13.41

We split the full URL into 2 segments:

  1. The host URL
    http://services.gisgraphy.com
    -> it will be specified in SMP as destination for the (future) OData service
    -> it doesn’t have trailing slash.
  2. The relative URL
    /street/streetsearch?lat=52.52&lng=13.41
    -> it is entered in this wizard page.
    -> it is required to have the leading slash.

Now paste the relative URL into the wizard and press “Finish”

5. Create Custom Code

Within the “Project Explorer”, expand the <your_name>.odatasrv node and open the context menu on the “Query” node

Choose “Define Custom Code” and in the subsequent popup, select “Groovy”

Press “Finish”, the script file is created and is opened in an editor.

I recommend to follow the few steps described here in order to improve the development experience with Groovy.

6. Implement the Custom Code

This is finally the main section of this blog.

What are we required to do here?

We have 2 callback methods:

processRequestData()

    ->We ignore it in this blog.

processResponseData()

    ->We focus on this one.

We have to understand:

When a user invokes the (future) OData service on SMP, the request goes to SMP and to the Integration Gateway component.

Integration Gateway knows to which data source to connect in order to fulfill the request.

The data source returns the desired data.

Now Integration Gateway has to take this structured data and re-structure it in the proper OData structure, before returning it to the user.

And this is the pain point in the case of REST data source:

it is structured, but HOW?

There’s no spec on which Integration Gateway can rely.

And this is why we, the implementers of the OData project, come into the game:

We are supposed to understand the structure of data of the REST service that we want to use.

We are supposed to help Integration Gateway to convert the structure of the REST service into the structure of our OData service.

We are supposed to implement this in the custom code.

The method “processResponseData() is invoked by the Integration Gateway Framework right after it has received the response from the REST service.

In this method, we have to

1) retrieve the response body of the REST service.

2) convert it

3) return it

Let’s have a closer look

6.1 The REST response

The method processResponseData() has a parameter called “message” which is of type com.sap.gateway.ip.core.customdev.util.Message

This object provides access to the REST response via the following statement:


String restResponse = message.getBody().toString();












6.2 Conversion

Let’s be optimistic for now and assume that the call to the REST service has been successful.

In this case, we get a long string which contains the response that is returned if we call the REST service directly:

http://services.gisgraphy.com/street/streetsearch?lat=52.52&lng=13.41

In our script, we have to manipulate this string in order to convert it to the desired structure.

But I’ve promised to be very simple, so let’s just ignore the REST response in this tutorial.

Let’s focus only on returning the correct structure.

Let’s do a hack that is allowed for educational purpose;-)

Let’s hardcode the return-structure.

6.3 The return structure

To be short:

Integration Gateway doesn’t require from us that we do the full conversion of the REST-response to an OData-response.

Integration Gateway will provide the correct OData format that complies with the spec.

What we have to do is:

-> provide the data in the structure that Integration Gateway expects.

I really mean EXACTLY in the structure that Integration Gateway expects.

Don’t worry, it is easy:


EntitySet


    Entity


          Property
















Since we are in a QUERY operation, we have to provide the correct entity set name.

Furthermore, a QUERY returns a list, so there can be one or more (or zero) entity types:


EntitySet


    Entity1


          Property


          Property


          Property


    Entity2


          Property


          Property


          Property


    ...
















Even more precise, see here the expected structure in the expected format.

The format is in our example xml, because the the chosen REST service returns xml.

BTW, it has to be valid xml, with values and closing tags (otherwise we get an error at runtime)


<EntitySetName>


    <EntityName1>


          <PropertyName1>“value of property1”</PropertyName1>


          <PropertyName2>“value of property2”</PropertyName2>


          <PropertyName3>“value of property3”</PropertyName3>


    </EntityName1>


    <EntityName2>


          <PropertyName1>“value of property1”</PropertyName1>


        <PropertyName2>“value of property2”</PropertyName2>


          <PropertyName3>“value of property3”</PropertyName3>


    </EntityName2>


</EntitySetName>
















Up to here it has been the generic description.

Now let's pllay it to our concrete example.

Look at the OData model that you’ve created in the graphical editor:

See it?

These are the names which you have to provide in the return structure.

I recommend using copy&paste in order to be sure to avoid tedious errors at runtime.

Now let’s build the response string for our example.

We copy the names from our odata model and paste them into our script file.

The expected structure would look like this:


<StreetSet>


    <Street>


          <StreetID>1234567</StreetID>


          <StreetName>MainStreet</StreetName>


    </Street>


</StreetSet>
















Note:

I don’t need to mention, that the names of the properties etc have to be correct.

I mean, really correct, including the right case.

Now let’s add the following code to our Groovy script:


message.setBody(


            "<StreetSet>"+


                    "<Street>"+


                          "<StreetID>1234567</StreetID>"+


                          "<StreetName>MainStreet</StreetName>"+


                    "</Street>"+


            "</StreetSet>");
















This is our hardcoded payload in the expected structure, according to our OData model.

We still need to specify the format of the payload in the respective header.


message.setHeader("Content-Type", new String("xml"));
















and don’t forget to add the import statements:


import com.sap.gateway.ip.core.customdev.logging.LogMessage


import com.sap.gateway.ip.core.customdev.util.Message
















We’re done.

For your reference, here's the full (dummy) implementation of our mehtod:


def Message processResponseData(message) {
    String restResponse = message.getBody().toString();
    message.setBody(
        "<StreetSet>"+
            "<Street>"+
                "<StreetID>1234567</StreetID>"+
                "<StreetName>MainStreet</StreetName>"+
            "</Street>"+
        "</StreetSet>");
    message.setHeader("Content-Type", new String("xml"));
    return message;
}








Don’t forget to save the file.

7. Deploy

Within the Project Explorer, select your project and from the context menu choose “Generate and Deploy Integration Content”.

You may specify some service details as desired and press “OK”.

After you get the success popup,

you can proceed and have a look in the Gateway Management Cockpit on the SMP server

Of course, here we assume that the SMP is configured in your Eclipse.

If not, you have to do so.

Go to Window -> Preferences -> SAP Mobile Platform Tools -> Server

And specify the details:

8. Runtime

Open the Gateway Management Cockpit at e.g. https://localhost:8083/gateway/cockpit

You might need to press “Refresh” to see your service.

Before invoking it, we need to configure the destination.

As we’ve learned above, we’ve split the full URL of our REST service into 2 segments.

The second segment is kept in the service implementation, that's what we've done above.

The first segment has to be configured as destination in our SMP.

Let’s quickly do that.

In the Gateway Management Cockpit, press the “Destinations” tab and click on “New Destination”.

Provide an arbitrary name for the destination.

The type is HTTP

The URL is the host URL that we’ve split above: http://services.gisgraphy.com

Authentication is not required for the REST service that we've chosen.

Note:

if you’re a keyboard user, you might get crazy because e.g <arrow left> will move the cursor to the previous input field, instead of moving the cursor inside the field to the previous character.

In case you didn’t know: you have to press F2 to edit the content of the current input field.

Yes, sir!

Save the destination.

Result should be a success popup.

You can now select the new destination  in the table, then press “Test Connection”.

Note:

The “Connection Test” is not 100% reliable, in the sense that it might report that the connection test fails, even though the connection is OK.

As we’ve seen above, for the REST data source, we have to split the URL. It can be the case that the first segment, the host, doesn’t respond as desired to the “Connection Test”, but it works fine for the full URL at runtime.

Note:

Depending on your entwork, it might be necessary to add proxy settings to your SMP server.

This is done at

https://<your_server>:8083/Admin/

In the “Settings”-tab and “System” sub-tab

Next, you have to assign this destination to your service.

Go back to the “Services” tab, click on your service in order to go to the details screen.

Click the “Add Destination” button and assign your new destination to your service:

Press OK.

Now you can click the hyperlink in the section “Service Access”:

The service document is opened.

Here you can see the one EntitySet that we’ve specified in our OData model:

This step should really always work fine.

Because until now we haven’t dealt with any backend-data-source-connection.

Next step is to invoke the EntitySet at:

https://localhost:8083/gateway/odata/SAP/REST_PROJECT_VERY_SIMPLE;v=1/StreetSet

(as usual, you have to adapt the sample URL to your SMP-installation)

The result is our hardcoded payload:

That’s it.

We’ve understood how the REST data source has to be implemented.

We’re now prepared for real implementation – and real headaches…;-)

BTW: I've attached the OData model and the custom script file for your convenience.

20 Comments