Approve Purchase Order Offline for Mobile

You’ve pushed out the SAP Fiori Approve Purchase Order to your enterprise and everyone is thrilled.  They love the interface and the ease of use and they have even run it on their Mobile Device in the browser.  Now that they have been using it, they ask if they can do approvals offline.  Your answer is, “Of Course.”

Now you have to figure out how to make that happen.

In this post I’m going to show you one way to go about it.  This first post will give you a starting point to easily create an offline store and show that your Approvals will be on the device even when you don’t have a connection.

In future posts I will go into some further details on how you can enhance the application to use offline functionality such as Refresh, Flush and Sync.  Offline is a broad topic and you should familiarize yourself with it more by reading the following blog post.  As you will see it’s not as easy as saying, I want my app to work in offline, there is a lot of consideration that goes into how to handle things like updates, creates, conflicts, etc.  The idea of this post is to give you a getting started place.

Throughout this post I will assume that you are familiar with the mobile service for SAP Fiori and also that you have Approve Purchase Order running in your environment.  If you haven’t used the mobile service for SAP Fiori please read this tutorial as a getting started guide.

You can also take a look at this post that shows you how to implement the same offline feature discussed in this post, but using the public Northwind oData Service instead, it also goes into some details of some of the architecture and concepts of offline.

For my setup I will be using a Trial Account and the Approve Purchase Order app hosted in my trial Fiori Cloud Portal where the app is connected to a working backend where the destination was configured with my HANA Cloud Connector.  The template that we use in this post is an SAP Fiori Reference App which you can find further information on here; SAP Fiori Reference App Library.  For the back-end communication, the app uses the OData service EPM_REF_APP_PO_APV_SRV.  You will need this in your environment to go through the tutorial step by step, however you can adapt much of the main point of this post, working with offline data, to your existing Purchase Order Approval application, or for that matter many Fiori based apps.

Development Environment for the back-end:

• GW software component: SAP_GWFND 740
• Gateway Service Builder: transaction SEGW
• Gateway project name: EPM_REF_APPS_PO_APV
• ABAP package: S_EPM_REF_APPS_PO_APV_ODATA

In my case I didn’t make any change to the Approve Purchase Order application.  If you have already imported the project into WebIDE and made modifications the next several steps won’t apply to you as you can move onto modifying the manifest.json and adding offline support to your project.

Start by using the Approve Purchase Order Sample Application.  This application is based on UI5 1.30, you will need to make sure your environment will support this.

From WebIDE select File->New->Project from Sample Application

Select the Approve Purchase Orders Template and then accept the agreement.  You will then have the project in WebIDE and can begin to make the changes.

Once the project is ready you will need to make changes to point the destination to the your back-end services.  The application uses a target name of “RefAppsBackend” for the destination.  You can either create this Destination in your SAP Cloud Platform account or you can use an existing destination.  Since you should already have the application running it’s more than likely you have the Destination already created.  In this example, my Destination is the one named “FIA”

For more information on creating a destination you can look at the documentation found here or a quick tutorial can be found here.

Once you have the name of your destination, go back to WebIDE and in your project and open up the Application Descriptor in the code editor, this will be the file neo-app.json.  This file provides the integration details between the user interface and the back-end.  For more information on the App Descriptor file go here.  There will be two of these, one at the root of the project and one under the webapp folder.  We will modify both, but start with the one at the root of the project first.  You will want to change the name to match your destination.

In my case change this to FIA

Save the file and then open the other neo-app.json file under the webapp folder.  In this file we need to change SAP_Gateway to the FIA destination.

Change the name and then save the file.

At this point you can test your project by right clicking on the project name and selecting Run As->SAP Fiori Launchpad Sandbox.  This will allow you to make sure you have changed all the names to point to your destinations and move to the next step of deploying the application.  If the names are not correct you will see a similar error that tells you that your reference destination is incorrect.

If you see this error, make sure to check your App Descriptor files as that is the only place that you should need to make changes for testing in the Sandbox.  Once you’ve tested you can deploy the application to SAP Cloud Platform.

Right click on the project name and select Deploy->Deploy to SAP Cloud Platform.  Note, each time you make a change to your project you will need to save it and Deploy to SAP Cloud Platform.

Once it’s deployed you can select to Register it to your SAP Fiori Launchpad, we won’t go through those steps in this post.

Now onto building it for mobile.  Before creating the mobile application you will want to create the Advanced Configuration File (ACF).  This is needed as you will use it to indicate that this will be an offline application.  For more information on the ACF, go here and read both part 2 and 3.

In it’s current state the Approve Purchase Order app is only ready for online use.  You should consider building the application with the mobile service for SAP Fiori now and make sure it runs correctly before enabling offline.  You can create your ACF JSON file with the following information in order to test it as an online packaged Fiori application.

{
	"applications": [{
		"id": "nw.epm.refapps.purchaseorders.approve",
		"cloudComponentId": "nwepmrefappsextpoapv",
		"url": "/sap/fiori/nwepmrefappsextpoapv",
		"scenario": false
	}],
	"appConfig": {
		"offline": false
	}
}

When creating the application select the option “I want to create a local launchpad with only the apps I want to mobilize”

After you select your Fiori Connection you will need to select the option to use an Advanced Configuration File.  Browse to the JSON file you just created to upload the ACF file.

Proceed through the wizard and build your application adding the configuration to your custom client.  In my sample I’ve name the application “REF App PO Approval” and changed the icon and splash screens, but didn’t change any other settings.  Once the build is complete you will then be able to install it using Mobile Place to test that the app is working as expected while the device is online.

Now let’s make the changes to allow for this to run offline!!

Go back to WebIDE and open the manifest.json file in the code editor.  This should be in the webapp folder of the project.  We need to add the following to the file, add it right before “sap.ui”.  After you place the code, right click in the workspace and select “Beautify” to better format the update you made.

	"sap.mobile": {
		"_version": "1.1.0",
		"scenario": "nw.epm.refapps.purchaseorders.approve.offline.Scenario",
		"definingRequests": {},
		"stores": [
			{
				"name": "PurchaseOrders",
				"serviceRoot": "/sap/opu/odata/sap/EPM_REF_APPS_PO_APV_SRV/",
				"definingRequests": {
					"PurchaseOrders": "/PurchaseOrders",
					"PurchaseOrderItems": "/PurchaseOrderItems"
				}
			}
		]
	},

This tells us a couple things.  sap.mobile tells the app that it can run in offline mode and a local store should be created.  In the “stores” you are telling the application to sync the data for the entities PurchaseOrders and PurchaseOrderItems to the offline store on the device.  You are also giving it a serviceRoot of the odata service.

The other thing that you are adding is the namespace for the scenario file which you will create as well.  In the Scenario file you can use the init function to filter in the data that you want to sync to the offline store.  In our case we will keep it simple and won’t use filtering.  In your project under the webapp folder create a new folder called offline.  In the offline folder add a file called Scenario.js.  Add the following in the file and save.  Deploy the change to SAP Cloud Platform.

jQuery.sap.declare("nw.epm.refapps.purchaseorders.approve.offline.Scenario");
nw.epm.refapps.purchaseorders.approve.offline.Scenario = {
// The init function can be used to manipulate the local launchpad or for an time 
// based sync mechanismus (sync every 5 Minutes).
    init: function () {

	}
};

Last thing that we will update is the ACF file to show that we want to build the application for offline.  Update the scenario and offline from false to true.

{
	"applications": [{
		"id": "nw.epm.refapps.purchaseorders.approve",
		"cloudComponentId": "nwepmrefappsextpoapv",
		"url": "/sap/fiori/nwepmrefappsextpoapv",
		"scenario": true
	}],
	"appConfig": {
		"offline": true
	}
}

Open the application in the mobile service for SAP Fiori and select the Detail control.  You will need to chose the “Select Fiori Application” button and select your connection as you did previously.  You can then browse for the updated ACF JSON file and upload it.

Select Finish and then go to the Platform control and make sure you select Save, and then you can Build All.

Once it’s done building you will be able to go to Mobile Place on your device and install the newest version.

The first time you open the application you will need to be online in order to login and then it will sync the data to the offlinestore.  If you are successful you should see the following dialog on the initial sync.

Once the data is retrieved, the application will be offline enabled.

To test, you can put your device into Airplane Mode and open the application.  You should see your application the same as it appeared when the device was connected to the network.

In future posts we will discuss more about advanced features of offline synchronization.