Step by Step with the SAP Cloud Platform SDK for Android — Part 6c — Using ILOData

Previous (Using a Foreground Service when Syncing) Home Next (Remembering Credentials)

ILOData is a command line based tool that lets you execute OData requests and queries against an offline store. It functions as an offline OData client, without the need for an application. Therefore, it’s a good tool to use to test data from the backend system, as well as verify app behavior. If a client has a problem with some entries on their device, the offline store from the device can be retrieved using the sendStore method and then ILOData can be used to query the database. To read about ILOData and how it can be used for troubleshooting, see Troubleshooting with ILOData.

The following instructions demonstrate a few examples of how ILOData can be used.
Create an Offline Store
Querying Entities
Creating Entities
Syncing
Creating an Entity with an Error
Querying the Error Archive

Create an Offline Store

Run Command Prompt for Windows, or Terminal for Mac.

In the terminal window, connect to the service using the following command. Make sure you fill in the YOUR_USER_NAME and PASSWORD fields.

C:\SAP\AndroidSDK\tools\ilodata\bin\ilodata host=hcpms-<YOUR_USER_NAME>trial.hanatrial.ondemand.com defining_query=Customers username=<YOUR_USER_NAME> password=<PASSWORD> port=443 custom_header=X-SMP-APPID:com.sap.stepbystep "custom_cookie=BIGipServer~jpaas_folder~hcpms.hanatrial.ondemand.com:\!SlLrMkUXLay97gg08AYQbXf7c9YJWgXZdn6Ptuh/ZiuwyJm6vsnPZfopjpY8FcoZlDsdEoxbuRK6QfE=" enable_https=yes service_root=https://hcpms-<YOUR_USER_NAME>trial.hanatrial.ondemand.com/com.sap.edm.sampleservice.v2 store_path=c:\temp

In the screenshot, the password value has been removed.

For the full list of command line options you can pass to ILOData, see Options.

The cookie value was obtained by using the browser to make a request to the OData backend URL and using a browser such as Chrome or Firefox browser’s debugger (F12 to show) to examine the value returned by the server as shown below.
For the full list of ILOData commands, see Commands.

Querying Entities

Now that you’ve created and connected to the local offline store, perform a get request.
```
get Customers
```
You will be shown a list of the customer records in the offline store.
The entities that have been stored offline are the ones specified in the defining queries. These can be examined by entering the following command.
```
printDefiningQueries
```

Creating Entities

Now, create a customer.

post Customers FirstName=John LastName=Smith

Examine the output. You should see HTTP 201: Created, which indicates that the command has successfully created the entity. You should also notice that the entity shown on the screen matches what you created, and that there is a visible property isLocal which is true. This is because the entity has been created locally and hasn’t been synced with the backend yet. Upon syncing, the entity will no longer be “local”.

It is also possible to add a filter to view the locally modified entities.
```
get Customers?$filter=sap.islocal()
```
or via
```
printRequestQueue
```

Syncing

To sync your local changes with the backend, issue an upload command, followed by a download.
Now perform a get query on the customers again, but this time, add the orderby clause help find our new entry.
```
get Customers?$orderby=LastName
```
Now you should be able to scroll through the entries (which have been sorted) and find the one that was just created. The next time an app connected to this service performs a sync, they will receive this new entry.
As an alternative to scrolling through the entries to find the new ones, the SDK provides a filter to only show entries that have been updated or inserted since the last download.
```
get Customers?$filter=sap.upsertedlastdownload()
```

Creating an Entity with an Error

An easy way to create an entity with an error is simply uploading a SalesOrderItem with the quantity property set to 0. This is invalid because there is no reason to be creating a sales order with no quantity. This is an example where the backend OData service has an extra check that the local store does not have. Enter the following command.
```
post SalesOrderItems Quantity=0
```
You should be given an HTTP 201: Created status, and ILOData will show you the newly created entity.
There are no errors yet because the entity hasn’t faced the backend validations yet. To attempt to apply this entity to the backend, perform an upload followed by a download as before.
Now use either of the below commands to see the state of the entity.
```
get SalesOrderItems
```
or
```
get SalesOrderItems?$filter=sap.inerrorstate()
```
You can see that not only has the entity not been saved to the backend (isLocal is still true), but also the entity is in the “error state”.

Querying the Error Archive

The details of any conflicts that occur during a sync can be viewed through the ErrorArchive. The Error Archive gives a more in-depth description of what actually caused the problem and why entities are in the error state. It can also hold information unrelated to entities, such as HTTP error codes and messages.

To query the ErrorArchive, use the below command.
```
get ErrorArchive
```
You will be shown a list of errors that have occurred.
To solve this problem, you can either update the entity using the patch command, or simply delete the entity. To do either, copy the “uri” field from the “__metadata” object in the returned JSON from the get SalesOrderItems command.
Then, either patch it or delete it.
In either case, the output of the command should be HTTP 204: No Content and after performing another upload/download, followed by a query to the error archive, there should be no errors remaining.
For more information on delete, patch, and other commands, see ILOData Commands.
You can see that the error archive gives specific details about the problem rather than just telling you an entity is in the error state. It can be a powerful tool for identifying problems with your uploads/downloads. For more information, see Accessing the ErrorArchive and Handling Failed Requests.