Make Sure Your Offline Works Right
Developing an offline mobile app is not always as straightforward as initially thought. During the various stages of app development there is sometimes a time to step back and take a close look into a system behaviour. Often we call this “debugging”. Debugging code is pretty well known for all the supported platform of the SAP Mobile Platform SDK – it is just code. But in an offline application you also want to check the data transferred to your device as well as the configuration you set on the server.
The SAP Mobile Platform SDK provides a simple command line tool, which is able to simulate an offline application, perform the initial sync, refresh and flush as well as the usual data operations like POST, PUT, MERGE and so on. With the help of this tool you can easily make sure that your OData service is performing correctly, that your server settings are correct and you can simulate client data modifications without using app code to do the same.
Wow, this sounds great, but where is this tool and how can I use it?
Once you have installed the SAP Mobile Platform SDK you can find it in
$ ~/SAP/MobileSDK3/Tools/bin
and it is called ilodata.
If you have installed the SDK into another path, you’ll need to search accordingly. Oh, and on Windows it called ilodata.exe.
On your Mac you would first make it an executable by typing:
$ chmod +x ./ilodata
For your convenience I’d recommend to create a symlink in /usr/local/bin by
$ sudo ln -s ~/SAP/MobileSDK3/Tools/bin/ilodata /usr/local/bin/ilodata
Now navigate your user’s directory and create a new folder or create the directory wherever you think would it would be appropriate. Here create an empty working directory and navigate into it and start ilodata:
$ mkdir offlinedebug
$ cd offlinedebug
$ ilodata
Oh what was that… I can’t read that fast. So let’s scroll up again and read the text together:
Interactive Local OData Tool Version 17.0.3.4520
USAGE:
ilodata.exe -?|--help|[option=name [option=name ...]]
Interactive Local OData (ILOData) lets you execute OData queries against an UL database.If the database exists, ILOData will just use it. If not, it will do a refresh to create the database. To do a refresh, at least defining_request and serviceRoot must be set. If no defining requests are specified on the command line and no store exists, the user will be prompted to enter defining requests before ILOData opens the store.
Many of the options correspond to settings in the Offline Store Options.
Please see the Offline OData SDK API documentation for additional details
…
Ok, now we know that ilodata stands for Interactive OData. That sounds promising, but how to get started?
In order to use ilodata you need to provide exactly the same configuration parameter we use for creating an offline store (Don’t worry if you don’t know the parameters, we’ll come to them in a minute).
But the text above holds some valuable information. First, it explains how to add options to the command line by using the option=name syntax. Second, it tells us that it is using version 17 and this has a deeper meaning, that I’ll explain later. And finally it points us to the documentation and to make it more comfortable for you here’s the direct link to SAP Help
Don’t click it now, just stay with me a bit longer, please.
Before we can use ilodata we need to have a proper server setting in place – you may know that the offline capabilities are mainly managed by the server and therefore we can’t leave him behind. A minimal App setting in your HANA Cloud Platform mobile service for development and operations should suffice. So open the mobile service Admin Cockpit and create an app config with the name OfflineApp and point its primary connection to http://services.odata.org/V2/northwind/Northwind.svc/ and set Proxy Type to Internet. It does not matter if you have chosen a native or hybrid app in this case. Please choose None as the security configuration. (ilodata works with credential-based authentication as well as with certification based security, but for debugging purposes we can often turn off the security)
| APPID | OfflineApp |
| Primary Back-end URL | http://services.odata.org/V2/northwind/Northwind.svc/ |
| Proxy Type | Internet |
| Security Configuration | None |
This is how your App overview screen should look like:
Now that we have a server configuration we need to create an APPCID (Application Connection) for this app. We can do this with curl (you may want to use Postman for Google Chrome or use any other tool that can create HTTP request for you)
$ curl -X POST https://hcpms-{SCNUSER}trial.hanatrial.ondemand.com/odata/applications/v4/OfflineApp/Connections -d '{}' -c hcpmscookie.txt -v -H "Content-Type: application/json"
You need to substitute your SCN username into {SCNUSER} above.
Once you execute this, you’ll get a lot of xml back, but for now we can just ignore this and just have a look into the hcpmscookie.txt file:
$ cat hcpmscookie.txt
Copy the APPCID GUID value into another text file or keep in your clipboard. Of course, if you are really really smart, you just can just memorize it. We need it now.
In a typical debugging situation, you don’t need to do all the steps, you would probably already have an APPCID and an app configuration on mobile services for development and operations.
Now, let’s use ilodata:
$ ilodata service_root=OfflineApp host=hcpms-{SCNUSER}trial.hanatrial.ondemand.com store_name=products defining_request=Products port=443 enable_https=yes appcid={APPCID} enable_debug_logging=true
Uh, that’s not trivial. Let’s quickly discuss all the options:
First, service_root should point to the OData Service Document. It does by being the APPID we defined earlier.
The host is pretty straightforward, it’s the server URL. Please make sure you substitute {SCNUSER} with you SCN username.
The store_name will reference your local UltraLite database.
You can have more than one defining_request, just use the option defining_request again to have more than one. The parameter itself refers to an OData collection name, no slashes.
Port is the server port of the host, on HCP it’s always 443.
When the port is 443, you should set enable_https to yes as seen above. Appcid defines the registration id we just found in the hcpmscookie.txt, I’m pretty sure you remember.
The last option enable_debug_logging is set to true, it’s self-explanatory.
If you execute the command, you’ll see a lot of things going on (well, only if you are not behind a proxy – make sure you have “unproxied” internet access to use ilodata), but the last lines should look like this:
…
Perform the reapply ...
Commit the download ...
Refresh complete.
Store state: Open
ILOData >
That’s it. Now you have created an offline store which you can query and modify.
Try :
ILOData > get Products
ILOData > help
ILOData > exit
Not bad, but this is not the end of the story. In your directory you’ll find to .db files:
- products.rq.udb and products.udb. The first holds all modifications from CUD operations, which you can “flush” to the server, while the later holds all the “refresh” data – everything you read from the server. Of course you can copy your devices db files into the folder and check their content with ilodata (in case of encrypted stores you need to somehow know the secret key and pass it as store_key parameter).
I hope this tool will help you in times where you really need to dig into your data and get a better understanding of what’s going on under the hood.
Now, it’s time to check the help document.
Have Fun,
Martin
- SAP Managed Tags:
