Updated 13 October 2020: Flow and screenshots changed due to updates in user interfaces.

In this blog post I will share with you, end-to-end, how to develop a native cross-platform mobile app that makes use of a protected back-end service running on Cloud Foundry. Besides building the mobile app with our Mobile Development Kit (MDK), we will also create an OData service from scratch and deploy this as a protected service.

In November last year, I’ve shared how to do this in SAP Web IDE Full-Stack. As we are planning to move our Mobile Back-end Tools extension to SAP Business Application Studio, I have created this new blog post in which we will no longer use the SAP Cloud Platform Neo landscape. For Mobile Development Kit we now have an editor in SAP Business Application Studio as well. With this, the transition from Neo to Cloud Foundry is almost complete.

Prerequisites

For this blog post we will be using a new trial account. If you have access to a canary or productive account, you can skip most of the setup here and open SAP Business Application Studio.

To start using your trial account, open https://cockpit.hanatrial.ondemand.com. Go ahead and ‘Sign in’ if you already have an account, or register for a new one. Once you have access, go ahead and click the “Enter Your Trial Account” button.In contrast to my previous blog post on this topic, we will be solely using SAP Cloud Platform on Cloud Foundry, running at one of the hyperscalers. For the trial landscape, this is likely to be at Amazon Web Services. When entering your trial account, you will see this popup dialog asking you to select the nearest region. Take note that the trial landscape has limited locations to choose from. For productive use, SAP Cloud Platform is available in more regions.After selecting the region, your trial account will be set up. Wait for this process to finish and click ‘Continue’.Your trial account will be now be set up. Wait for this process to finish and click ‘Continue’. What will show up next, is the SAP Cloud Platform Cockpit. Here, please select the trial subaccount.

On the subaccount overview page, select Subscriptions and select SAP Business Application Studio.Select Subscribe.

Once SAP Business Application Studio is available, go back to the subaccount overview page, select Security > Role Collections.Select ‘New Role Collection’. Provide a name for this role collection and Save it.Select the role collection you’ve just created, and select ‘Add Role’.Select the Application Identifier related to app-studio and pick the Role Template ‘Business_Application_Studio_Developer’, and Role ‘Developer’.

In the subaccount overview page, select Security > Trust Configuration. Click on the default IdP. In the Role Collection Assignment, enter your email address and click “Show Assignments”. Click Assign Role Collection and select the Role Collection you’ve created earlier and click Assign Role Collection.

Go back to the subaccount overview page, select Subscriptions and select SAP Business Application Studio.Click the “Go to Application” link. Click OK to confirm the privacy statement.What is shown next is the landing page of SAP Business Application Studio where you manage Dev Spaces.

Note: if SAP Business Application Studio doesn’t open and you see “access denied”, then please check your trust configuration and make sure the Business_Application_Studio_Developer role template is enabled for your user. You might have to re-login in SAP Business Application Studio before these configuration settings take effect.

SAP Business Application Studio

Welcome to the next generation of SAP Web IDE. This integrated development environment will look and feel a lot more like Visual Studio Code.Select the ‘Create Dev Space’ button to create your first development environment.Provide a name for the Dev Space and select ‘SAP Cloud Platform Mobile Services’ as the kind of application to create. Select ‘Create Dev Space’.Select the link on the newly created Dev Space, which will open the environment.At the bottom left, you will see a message indicating that “The organization and space in Cloud Foundry have not been set.”. Click on this.

The Command Palette appears, where you need provide information.Here, you can press ‘enter’ to select the default value, or select a different endpoint if you want to make use of a different Cloud Foundry landscape for deployment.

Next, you’ll need to provide your Cloud Foundry credentials (email and password). After this, you’ll need to select the organization and space. If you are part of multiple organizations, please select the correct one here (e.g. trial).

Creating the OData service

In the menu, select Terminal. A terminal will open. Create a new folder in the folder ‘projects’ by entering

mkdir projects/openSAPNew

In the menu, select File > Open Workspace … and double click on the folder you’ve just created. Once you select Open, the workspace will be loaded.

In the menu, select View > Find Command and type MBTSelect the option to create a new OData CSDL document (metadata)Select OData Version 2.0, as version 4.0 is not supported for offline apps at this point.Set the namespace alias nameProvide a file nameThis will create the specified file in your workspace and open it in the code editor.

Right-click on the file and select open with CSDL editor.This will open the CSDL editor, a graphical modeller for creating and editing CSDL files. This is exactly the same editor as available in SAP Web IDE Full-Stack.

You can now create a OData service model from scratch by adding entities, (navigation) properties, complex types and data methods. I will skip this here, as this blog post would become quite lengthy. Instead, we’ll reuse a model used in the openSAP course “Build Mobile Application with SAP Cloud Platform Mobile Service”.

For this blog post I will use the same OData service as used in the openSAP course. Please go ahead and download the file openSAPNew.zip. Extract the zip file, and drag and drop the file called com.opensap.mobile.canteen.csdl.xml onto the workspace explorer in SAP Business Application Studio. This will upload the local file into your workspace.

Clicking on the file com.opensap.mobile.canteen.csdl.xml will open the graphical modeller. Feel free to modify the CSDL file to your needs, by adding entities and properties.In contrast to SAP Web IDE Full-Stack, we need another configuration step to ensure we can convert the CSDL file into a data service. In SAP Business Application Studio you are able to tailor this to your needs. Let’s first create a tasks.json file to handle the project.

Hit keyboard shortcut ‘F1’ to open the Command Palette and enter MBT. Select Create tasks.json and enter the application name. Hint: type slowly, as this tends to lag.Provide a version number.Select the style of the OData service. Use Java EE style.Select database type. For this blog post I’ll use In-Memory, mainly because the free trial account doesn’t offer you much else to choose from. On the paid accounts you will be able to use PostgreSQL or SAP HANA, or SAP ASE (Neo only).Choose the target folder and keep the default.

Choose whether you want to add MTA support. For this blog post, we’ll go with ‘No’ so that the OData service will be generated in the workspace folder.Next, choose the metadata file you are planning to use. This will be the com.opensap.mobile.canteen.csdl.xml file.Next, you need to provide the local Java server path.

Select the default tomcat location in SAP Business Application Studio.

Based on your input, a new file is created: .vscode/tasks.json. You can tailor this file to your needs, depending on your landscape, database, authentication method to be used, etc.

Now, let’s generate the OData service.

Hit F1 again, type Task and then select Task: Run Task in the Command Palette.Select csdl-to-war-local for local Tomcat deployment within the SAP Business Application Studio Dev Space. After a few seconds a terminal opens and a build is started. After generating and building the service, the resulting WAR file is deployed locally and the service is automatically detected. To keep the service running, please do not close the terminal tab.Click “Expose and Open” and provide a name for the port you are opening.

After this, a new browser tab will show the output of the generated service. You can now test your service and modify the url to execute specific queries.After testing your OData service locally and confirming it works, let’s deploy the application to Cloud Foundry. We’ll use the csdl-to-war-cf task for this. By default, this task enables debugging. However, on a Cloud Foundry trial landscape it is not possible to set up an ssh tunnel to your application. This is a trial limitation. If you want to debug your app deployed on CF, you’ll need to use a non-trial account.

Comment out the line that enables debugging in the tasks.json file. In addition, we add the requirement to use XSUAA security for accessing the app by uncommenting the “-login” option “XSUAA”.Hit F1, type Task and select Task: Run Task in the Command Palette. Select csdl-to-war-cf.A terminal will open, the service source code is generated and a build is started. Once done, a connection with your Cloud Foundry account will be set up and the application is deployed and started.

Note: In case the deployment fails with message “The app cannot be mapped to route <your route> because the route exists in a different space”, please rename the application to a more unique name.

Copy the routes link and paste it into a new browser tab. This will result in a HTTP error ‘401’ (unauthorized).We will not see any login UI asking for credential here because the service we’ve created doesn’t provide this. So let’s create a mobile app that does this for us, and shows us the data as well.

Creating the MDK Mobile App configuration in SAP Cloud Platform Mobile Services

Go to the SAP Cloud Platform Cockpit and select the Service Marketplace in your ‘dev’ space and search for Mobile.Select Mobile Services.Click the Support link, which will bring you to the Mobile Services Admin Cockpit. You might have to select an Organization and Space. If this is the case, select your trial org and dev space.Select the big + button to create a new app. Provide the basic app information.Click Next and Assign Features for Mobile Development Kit Application.Click Finish. Your MDK application is created.Now that we have created the mobile application configuration, let’s go back to the SAP Cloud Platform cockpit, select the ‘dev’ space, and select the Service Instances. Click the instance <your-app-id>-xsuaa. Click the button ‘Bind Application’.

Select your OData service application. To configure the binding parameters, we need to upload a JSON file (copy/paste is also possible here..).

In the SAP Business Application Studio workspace, you will find a generated file called xs-security.json, which contains the role templates and scopes. Notice the ‘Service user role’ with name ‘Everyone’. This role is not explicitly defined in the SAP Cloud Platform cockpit, but everyone with access to the account will also be able access to the OData Services. Anyone else is blocked. If you need more strict control on who is able to access the service, then you need to change the role-templates and scopes here and configure the role collections and trust configuration in the SAP Cloud Platform cockpit for your subaccount. An example of this is provided in my previous blog post.Download this xs-security.json file to your local machine.

After binding the xsuaa service instance to your application router, we need to restart the application router. You can easily do this by going to the application’s overview page and select ‘Restart’.Copy the Application Routes URL. We will use this to configure a mobile destination, allowing your mobile app to consume the service.

Go back to your mobile application in SAP Mobile Services. Select the ‘Mobile Connectivity’ in the Assigned Features section on the right.Click the Create button to create a new Mobile Destination.Click next, next, next. For the SSO Mechanism, select Forward Authentication and tick the option to Propagate User Name. Click Next and click Finish.Back in the Mobile Connectivity tab, select the button “Launch in browser” to check whether you can access your service. Take note that ping and data source testing is not possible when Forward Authentication is active (this is different from my initial blog post).

If all was configured correctly, “Launch in browser” should open a new browser tab and display the entities exposed by the service. At a later stage we will need the OData metadata description of this service endpoint for creating the mobile application. Add the parameter $metadata in the url to retrieve the metadata document.
Save this metadata document to a file on your workstation. We’ll need it later.

Creating the MDK mobile offline app in SAP Business Application Studio

Now that we have the OData service up and running, let’s create a cross-platform mobile application with Mobile Development Kit. It is not my intention to create a fancy looking app here. We will simply use an application template that can show the basic functionality, including the capability to continue using the app and the data while the device does not have a network connection.

In SAP Business Application Studio, we open a new terminal and create a folder for our new project.

mkdir /home/user/projects/MDKApp

In the menu, select open Workspace and select the folder we’ve created just now. The new workspace is opened and the welcome page is shown.

Select “New project from template”, pick the MDK Project and click Next.Select the CRUD template type and provide a project and application name.In the next step we set up a connection to SAP Cloud Platform Mobile Services on Cloud Foundry. For this, we to specify the Cloud Foundry endpoint, organization and space.For the Service Configuration, we provide a service name.

And now comes the tricky part where we need deviate from the usual flow. In case of unprotected services, we can use a destination to connect to Mobile Services to find the correct app and endpoint. And with this information, the wizard is able to retrieve the metadata document of the service. However, this doesn’t work for protected services, as we are lacking the correct authentication mechanism.

The workaround is to provide the metadata document manually. Upload the metadata file you’ve saved earlier into your SAP Business Application Studio workspace.In the last step of this wizard, select all the OData Collections available.When finished, open the MDK project in a New Workspace.

You can browse the project and check the page definitions, rules, actions, etc. When you open the Main.page file, you will get an idea of how the applications user interface will look like.

For this blog post, we will not modify anything in the app and deploy the app to SAP Cloud Platform Mobile Services. Right-click on the file Application.app to open the context menu, and select ‘MDK: Deploy’. This will trigger a task to build the application, bundle the app and upload it to Mobile Services.

The MDK application is now ready for consumption in a client app. You can build your own custom client app (with additional features, plugins, etc.) or install a generic client that we have already published in the Apple App Store or Google Play store. The latter is the easiest. Search for SAP Mobile Services Client and install the app on your device.

We now need to ensure the mobile client loads the MDK app we’ve deployed. But how does this generic client app know where to retrieve it?

In SAP Business Application Studio, right-click the file Application.app and select ‘MDK: Show QR Code’ in the context menu. This will create a url that should be opened on the mobile device. The onboarding url contains information about the application, and OAuth configuration settings.

Scan the QR code using your device (or open the Result URL by sending it via email to yourself). This will automatically open the SAP Mobile Services Client on your device.

Select Start for the onboarding process and enter your SAP Cloud Platform credentials.

After successfully logging in, accept the EULA and configure a passcode. Where applicable, you can also enable face id.

Next, you will see the home screen of the MDK client. A popup will appear, asking to confirm “Update now?”. When you confirm this, the application bundle will be downloaded from Mobile Services and stored on your device.

Once the bundle is downloaded, the application will be started and data from your OData service will be downloaded for offline use.

You can drill down to check the entries for each entity, change them, create new and delete them. After making changes, you can sync those changes to the OData service.

This concludes developing the offline native app.

Future optimization to the setup

Reading back the steps explained so far, there are quite a number of things to configure and change. We’ll probably be able to eliminate some of the steps with future releases of our tooling. I’ll update this blog post as soon as these optimizations are available.

Rapid iterations from here onward

At this point you can start changing the app to your needs. You can even add entities and new properties in your data model, redeploy the service, refresh the objects used in the app, modify the app accordingly and deploy a new version. All without actually building, signing and distributing the apps to your device(s). Being able to skip all these tedious tasks makes your development flow much more productive.

I am looking forward to your feedback and can’t wait to see what you’ve built with this.

Happy coding !

Ludo Noens

SAP Digital Workplace – Rapid Application Development