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.
I have reached the step where the app is built in SAP Mobile Secure. When I click the Finish button the build process starts but ends up in the build failing (it shows Failed under the State column for the app). What can be the reason the build fails? Also where can I check the logs of why the build of the app failed?
There is a log file that is generated that can be downloaded and viewed that shows more information on the failure. Depending on that log file, you can post the information and we can see if we can determine the cause of the fails.
I see the below in the build logs file on failure.
[2017-07-14 09:00:29.96913] [ET] [5968882da36f5::p-user@trial-p-usertrial] Build failed for [ANDROID] [ErrorCode: 40001] [ErrorStatus: RESOURCE COLLECTION FAILED]
Kindly refer to the trouble shooting guide in the following location to help you troubleshoot the problem.
https://help.sap.com/viewer/p/SAP_HANA_CLOUD_PLATFORM_MOBILE_SERVICE_FOR_SAP_FIORI
I’m not sure I understand what I should do to correct this error.
Does the Reference App Run successfully before you build the application in Fiori Mobile Service? There are a couple things that can cause this issue. If FMS is not able to find the proper destinations based on the manifest.json file it will fail to get the "resources" form your environment. It's likely there is just something not quite right in the App Descriptor file. If the application runs standalone, as in able to run when you right click on the project in WebIDE and select Run As and chose Fiori Sandbox, or even deploy it to Cloud Platform and then run it after deploying it to the launchpad, if these work we will need to look into it further.
Thanks for your response!
I confirm that the reference app works perfectly before building the app in the FMS. I am able to run it successfully in Fiori Sandbox mode, I've even integrated it to a Fiori Launchpad type site on the Cloud Portaland it runs fine from there too.
I looked through your logs and nothing stands out. I do see the Resource Collection issue, but there isn't a specific reason for that. It's good that the app itself works, this means one of two issues:
You can post your manifest file here, or if you are able you can log a support ticket with the component MOB-FM and someone will be able to work with you directly.
I have been able to build a few demo apps in the past using the Fiori Mobile Service. But you have pointed me in the right direction by mentioning the Advanced Configuration File which led me to review this file again.
It turns out that while deploying the reference app from Web IDE to the Cloud Platform I had changed the default name of the app from nwepmrefappsextpoapv to mmpoapprove but in the ACF JSON file in the properties cloudComponentId and url I did not make the necessary change in the app name. Once I changed the required values and uploaded the ACF my app was built successfully.
I really appreciate your time in providing me with your valuable inputs!
Hi MArk,
Is there any documentation from SAP on how to implement the flush and refresh for the Cloud Platform SMP scenario? I've been looking everywhere and I've only been able to find very basic information about this. For instance all I've found regarding the sap.mobile namespace for the manifest.json file has been this:
https://help.sap.com/viewer/0ce0b8c56fa74dd897fffda8407e8272/7.5.6/en-US/7701636d088147569d99b4f08d418bd9.html
It would be greatly appreciated if you or anyone else from SAP can point us to a guide that explains all the features of Fiori Mobile for Cloud Platform and how to implement them.
Best Regards,
Hi Mark
I have followed all the steps and successfully using (project from sample application – Approve Purchase Order) using Fiori mobile cloud build service. I have successfully tested it online , but the offline capability still doesn’t work, and I also don’t see that the initial “local store being provisioned” step. Below are my lines of code have added for your reference, kindly help
Scenario.js
jQuery.sap.declare(“nw.epm.refapps.purchaseorders.approve.offline.Scenario”);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 () {
}};
manifest.json(added just above sap.ui″)
“sap.mobile”: { “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” } } ] }
ACF file
{{ “applications”:[ { “id”:”nw.epm.refapps.purchaseorders.approve”, “cloudComponentId”:”nwepmrefappsextpoapvsub”, “url”: “/sap/fiori/nwepmrefappsextpoapv”, “scenario”:true }], “appconfig”:{ “offline”:true } }
Kindly advice
Thanks
Delete the scenario.js file and also the reference to scenario in the maniftest.json, you should no longer need these files.