Update 18.12.2013
The approach described in this whitepaper is not needed anymore since as of Service Pack 7 SAP NetWeaver Gateway supports a delta query protocol.
Therefore you should rather have a look at the following two more recent documents:
How to Implement Basic Delta Query Support in SAP NetWeaver Gateway
and
How To Enable Delta Queries using Syclo Exchange Framework and SAP NetWeaver Gateway
Additional upcoming whitepapers will be listed in our SCN Wiki:
Development - Technologies - SCN Wiki
Best Regards,
Andre
Overview
Nowadays the OData services provided by SAP NetWeaver Gateway are widely used in mobile online scenarios with or without SUP in between. For example the productivity apps by SAP are mainly build using SAP NetWeaver Gateway OData services. But there are common scenarios where online is not good enough, where you need your data in your app even if you are not in range of any wireless connection. In these kind of scenarios you need an offline synchronization engine which is provided by the Mobile Business Object pattern in the http://scn.sap.com/community/mobile. If you already have created an "online" OData service and want to create an offline app leveraging your existing services you will probably find this document very useful.
This document describes step by step how to create an MBO that reads its data from an SAP NetWeaver Gateway OData service to create an offline app.
As prerequisite you should know the basics about SAP NetWeaver Gateway and it's OData services and you should have a basic understanding of the MBO model in SUP.
Also you should have a local copy of the Sybase Unwired Workspace to create your MBO and you need a current Visual Studio installation.
Steps
- Create a new Mobile Project
- Create a REST Connection Profile in the Sybase Workspace
- Generate an XSD file based on the XML that you want to read from the OData service
- Create an OData MBO
- Deploy MBO
- Further Steps (Use MBO in HWC Application or Generate Code)
The SAP NetWeaver Gateway sample service
The SAP NetWeaver Gateway sample service used in our How-To-Guide is located on the ES-Workplace. The service document can be retrieved using the following URL:
https://gw.esworkplace.sap.com/sap/opu/odata/sap/ZCD204_EPM_DEMO_SRV/?$format=xml
The login credentials which are needed are the following:
user name : GW@ESW
password: ESW4GW
The service provides access to 4 entities: SalesOrders, SalesOrderItems, Products and BusinessPartners. In our sample we provide access to the Busines Partners collection
https://gw.esworkplace.sap.com/sap/opu/odata/sap/ZCD204_EPM_DEMO_SRV/BusinessPartners
through the MBO protocol.
We have to download the resultset retrieved from the OData service as an XML file from which we will generate an XSD file as described later in this whitepaper.
Create a new Mobile Project
The creation of the mobile project is really an easy goal to accomplish.
Within the Mobile Workspace click on File > New > Mobile Application Project. This will open a dialog wizard to create a new mobile project.
Give your project a name like you see in the following screenshot:
Click Finish
Creating a REST Web Service Connection Profile
Next step would be to make your OData backend service available in the Mobile Workspace. To do so we create a so called "Connection Profile" in the Enterprise Explorer view, typically located in the lower left part of the Mobile Workspace. This is your Enterprise Exporer:
Now right-click the REST Web Service folder and click New. A dialog appears which will guide you through the creation process. The first dialog asks for a name of the Connection Profile:
Name the Connection Profile as seen in the screenshot or choose your own name. Click Next.
Now we have to define Base URL which defines where your Service is located. Then you can define a list of different resources that are available under this service. For this demonstration you choose the Base URL of:
http://gw.esworkplace.sap.com/sap/opu/odata/sap/ZCD204_EPM_DEMO_SRV
and the template
/BusinessPartners
as seen in the screenshot below. It is called template because you can add placeholders to it which can be populated with values at runtime. Typically you would use Personalization Key for that.
Just click Finish. That's it. Nothing more to do here.
Creating the XSD file
In order to create your MBO you have to provide an XSD Schema definition so that SUP knows which response it should expect for a specific request. To create this XSD we call our service in a browsers adress bar and save the response as source on our local machine as an xml file as described earlier.
The xsd file can now be created from the xml response of the OData service using the tool xsd.exe from Microsoft that comes for example with Visual Studio.
1. Start the Visual Studio Command Prompt and navigate to the folder where you have downloaded the xml-file of the collection
C:\temp>xsd BusinessPartners.xml
Microsoft (R) Xml Schemas/DataTypes support utility
[Microsoft (R) .NET Framework, Version 4.0.30319.1]
Copyright (C) Microsoft Corporation. All rights reserved.
Writing file 'C:\temp\BusinessPartners.xsd'.
Looking at the files that have been created we observe that actually 3 files have been created:
BusinessPartners.xml
BusinessPartners.xsd
BusinessPartners_app1.xsd
BusinessPartners_app2.xsd
You'll need these files in the next step.
Create an OData MBO
Now that we have prepared everything we can start to model our oData-based MBO. To do so, locate the MBO icon in the Palete. Click it once and then click on the white modeling pane which is labeled Mobile Application Diagram or MAD for short. A dialog will appear and on its first page you define the name of the MBO. Like this:
Click Next.
The next screen asks for the backend type you want to connect to. Since we want to connect to an OData backend which is obviously REST based we choose the REST Webservice and click Next.
Now we have to define the request and the response in the next screen:
As we already have chosen the Connection Profile the Resource Base URL is already fixed. Next to choose is the URI template that should define the operation you want wo invoke. Also choose the HTTP method that should be used to invoke the resource. In this case it is 200. Make sure you chose that method that is expected by your service.
The tabs Representation defines the expected request and response bodies for this request. The HTTP Header tab lets you define additional HTTP headers if your service requires it. We will examine the Authentication tab later.
We have to define the response first so click on the Edit button right at the end of the Respons row. This will open this dialog:
When this dialog appears, click the Browse button and select your BusinessPartners.xsd that we created previously. Confirm that action using the Load Elements button. In the dropdown left to the button, you will see now a rather long list with all possible root elements. Choose the feed element.
The list at the bottom represents a list of XSL transformation that will be applied to the service response to map it to MBO attributes. For now, just select the row and click the Edit button. This screen will appear:
First, check the radio box Generate.... Then uncheck every pre-checked element in the treeview. Scroll down to the properties element and select every attribute you want to map to your MBO attributes. Just make sure that it looks similar like in the screen above. Click OK to close the dialog. Back on the previous dialog you can now select the Authentication tab and provide the credentials for this service:
The username is "GW@ESW", the password is "ESW4GW".
Click Preview if you want to test your service. Otherwise click Finish.
Now your Mobile Application Diagram now should look like this:
This is it. Use your REST based MBO like every other MBO you create. During deployment don't forget to copy/create the Connection Profile for your service.
Now you can create synchronized native applications that reads data from an OData datasource.
Hint: Obviously all the attributes are String(300) which is not a valid approach. Please adjust the datatypes as needed.
Congratulations.
Authors
