Skip to content

Creating Apps with the Wizard

Launch the Wizard and follow the prompts to create a starter app configured with connections to the SAP Business Technology Platform and OData services. You can also use the Wizard to enable features such as logging and push notifications on your generated app.

You require an SAP Business Technology Platform account with administrator privileges to create or edit configuration settings on the SAP Business Technology Platform. If your account does not have administrator privileges, the Wizard controls requiring full permissions are unavailable. See the Wizard screen topics for more information about account restrictions.


  1. From the Android Studio Welcome screen, select Start a new SAP Business Technology Platform Android project.

    You can also start the Wizard by opening Android Studio and selecting File > New > New SAP Business Technology Platform Android project.

  2. Follow the steps in the Wizard described below:

    1. Maintaining mobile services connection.
    2. Creating or reusing mobile services application configurations.
    3. Adding OData services.
    4. Specifying Android project properties.
    5. Adding mobile services features.

Maintaining Mobile Services Connections

Configure the connection to your instance of the SAP Mobile Services, also known as Server Connection.

Server Configuration

You can save your server connection settings to reuse the next time you launch the Wizard. If you have previously saved connection settings, select Accounts and select your server connection settings from the Accounts List.

To complete this page, you'll need to provide the following:

  • The Admin API and Admin UI URLs for your instance of the SAP Business Technology Platform
  • The authentication method, either Basic or SAML
  • The username and password for an SAP Business Technology Platform account

You can find the Admin API and Admin UI URLs on the Important Links page of the SAP mobile service cockpit. To access this page, log in to the SAP Business Technology Platform, navigate to the mobile services service, then select the Important Links link on the bottom of the left navigation pane.

The Wizard supports both Basic authentication and SAML authentication using SAP Identity and Authentication Service or Microsoft Active Directory Federation Services (AD FS). SAML support provides a "headless" implementation: the user must still provide a username and password and is not presented with a web view.


Please note that SAML functionality has been tested using the defaults for the SAML form. Customizations to the SAML form, such as changing the input field IDs, may cause authentication to fail. In the event of a problem, contact SAP Support for assistance.


The Wizard will display a message prompting the user to upgrade the H2 database if the existing H2 database version is lower than required.

  1. Copy the Admin API URL from the Important Links page and paste it in the Admin API URL field.

    This URL is used to access the SAP mobile service cockpit API. When you provide the API URL, the Wizard autofills the Admin UI URL field with the standard default value.

  2. Verify that the autofilled URL in the Admin UI URL field matches the Admin UI URL as displayed on the Important Links page. If required, modify the value in the field.

  3. Select the required authentication method, either Basic or SAML, from the Authentication Type list.

    This is the authentication method that the Wizard uses to connect to the platform to retrieve settings such as application definitions and OData service destination profiles.

  4. Type the username and password for your SAP Business Technology Platform account in the Username and Password fields.

  5. To save these settings for reuse, select the Save Account Information check box.

    When you select this check box, the Wizard autofills the Account Name field with your account name. This value is used to identify the account profile in the Accounts List.

    On first use of the Wizard, you are prompted to enable or disable a passcode for encrypting the data passed to the SAP Business Technology Platform.

    To enable a passcode, select Enable and set a passcode. The passcode must be at least eight characters with at least one capital letter and one number. If you select Disable, the Wizard generates a passcode for encryption.

    If you set a passcode, you'll be prompted to provide it whenever you start the Wizard if your saved data is to be used.

    You can enable or disable a passcode later using the configuration icon in the upper right corner of the Accounts dialog.

  6. Select Next to proceed to the Cloud Configuration page.

    The Wizard connects to SAP Business Technology Platform to verify the settings.

Creating or Reusing Mobile Services Application Configurations

Configure your app on the SAP Business Technology Platform.

Cloud configuration

You can:

  • Create a new application definition for your app on the SAP Business Technology Platform. (If you do not have administrator privileges, the Create option is unavailable.)
  • Use an existing app definition
  • Create a sample app using a predefined server connection configuration. The Sample method is the easiest way to generate an app with the least user input. You only need to provide a name for your app. All other configuration settings, such as destination configuration, are completed automatically using the ESPM sample service.

Creating a New App Definition

When defining a new app, observe the following rules for the Application Name and Application Identifier (app ID):

  • The Application Name can contain alphanumeric characters, spaces, underscores, and periods, and can be a maximum of 80 characters for the scenario where the app will be created in a Neo environment.
  • The Application Identifier is a unique application identifier in reverse-domain notation. An app ID:

    • Can contain up to 64 characters for the scenario where the app will be created in a Neo environment
    • Must start with an alphabetic character
    • Can contain only alphanumeric characters, underscores, and periods (no spaces). Note that the app ID cannot begin with a period, and cannot contain two consecutive periods
    • Cannot be any of these case-sensitive keywords: Admin, AdminData, Push, smp_cloud, resource, test-resources, resources, Scheduler, odata, applications, Connections, public, lcm

    SAP recommends you assign IDs that contain a minimum of two (non-consecutive) periods, for example,

To create a new application definition:

  1. Select the Create tab.
  2. Enter a name for your application in the Application Name field.
  3. Enter an app ID in the Application Identifier field.

    The Wizard registers the application with this ID in the mobile service. The generated client application uses this ID when sending requests to the SAP Business Technology Platform.

  4. Select one of the following methods for authenticating users of your new app from the Authentication Type list: None (app users are not required to log in to the app), Basic (default), OAuth2, or SAML.


    No sensitive data is stored on the device. Users must enter credentials each time they restart the app.

    The generated app uses the SDK’s Secure Store. If a passcode policy is set for the created application, the user can set one up or use a default passcode, and then will have to enter the credentials only at first start, and then, after that, use the passcode. The data will be encrypted on the device.

  5. (Optional) To set additional settings for your new app, select the Go to cockpit link to open the SAP mobile service cockpit in a browser.

  6. Click Next to proceed to the OData Services page.

Using an Existing App Definition

  1. Select the Use Existing tab.
  2. Select the application ID from the Application ID list.
  3. Select Next to proceed to the OData Services page.

Creating a Sample App

  1. Select the Sample tab.
  2. If necessary, modify the default app ID in the Application ID field to ensure the ID is unique.
  3. Select Next to proceed to the OData Services page.

Adding OData Services

Specify the destination of your OData services. A destination is a connection to a data source.

OData services

If you are creating a new application, you'll need to add a destination. If you are basing your application on an existing application definition, there should already be existing destinations in the Connections list.

To add a new destination, you'll need the network details for the connection, including the OData endpoint URL, the proxy type, the URL rewrite mode, and the authentication type. Contact your network administrator to determine the correct settings for the destination. For more information, see Defining Connectivity in the SAP Mobile Services documentation.

You can also configure your app to consume OData services, referred to as "OData APIs", that are hosted on the SAP Developer Portal or on the SAP Business Accelerator Hub.


If you do not have administrator privileges, the Add, Remove, and Edit buttons are unavailable. If you are creating a sample app, the Add and Remove buttons are unavailable.

  1. Choose an existing destination from the list or select Add to add a new destination.

    You can also add a destination that uses OData services hosted on a Developer Portal or the SAP Business Accelerator Hub. Select Add new from API Management and provide connection details as required. See "Adding a Destination Using OData APIs from a Hosted Site" below for more information.

  2. If you chose to add a new destination, choose an existing destination from the Add Existing tab or define a destination from the Create tab.

  3. To create a new destination, specify the following:

    • Name – The name of the back-end endpoint, which is automatically filled in for the destination.
    • Back-end URL – The OData endpoint URL.
    • Proxy Type – Either OnPremise or Internet.
    • URL Rewrite Mode – Configured to determine where to rewrite the URL.
    • Maximum Connections – The number of allowed parallel connections.
    • Authentication Type – The authentication type used between the mobile service and the OData endpoint.
    • Custom Headers – Key-value pairs defined for static HTTP headers.


    The new destination is created on the server after you select Finish at the end of the wizard.

  4. If you want to upload the local metadata XML file for a specific destination, click Select... in the row of that destination, and then browse your local file system to upload a valid metadata file.

    OData services

  5. Select Next to proceed to the Android Studio Project page.

Adding a Destination Using OData APIs From a Hosted Site

Add a destination to OData services using APIs hosted on the SAP Business Accelerator Hub or the SAP Business Technology Platform Developer Portal.

The SAP Business Accelerator Hub is a central API catalog available to developers who are building apps, extensions, and process integration with SAP Business Technology Platform. See the SAP Business Accelerator Hub documentation for more information.

The Developer Portal is a platform for application developers for building, publishing, and consuming APIs. Every API Management customer is provided with a Developer Portal on the SAP Business Technology Platform. See the SAP Business Technology Platform API Management documentation for more information.

The SAP Business Accelerator Hub may include both a sandbox and a production service. To access APIs on the sandbox service, you'll need an SAP Business Accelerator Hub account in order to retrieve an API key.

To access APIs on the production service of either the SAP Business Accelerator Hub or the Developer Portal, you'll need to get the back-end URL for the API and request an API key from the API owner. To access APIs from the Developer Portal, you'll need a developer account.

Procedure for OData

  1. From the OData Services page of the Wizard, select Add new from API Management.

    The API Management wizard opens.

    API management

  2. From the Select an API Management account page, select either SAP Business Accelerator Hub or Use Developer Portal.

    If you chose to use the Developer Portal, specify the following:

    • Name of the Developer Portal – (Optional) To save your settings for reuse, provide a name for this profile and select the Save Account Information check box.

      This name is used to identify the profile in the Accounts List available from Developer Portals. * URL of the Developer Portal – The URL of your Developer Portal. You can obtain this URL from the API Management service cockpit. * Username and Password – The credentials of the Developer account associated with the Developer Portal.

  3. Select Next to proceed to the Select an API Product page.

    The Wizard retrieves all API products that have at least one OData API.

  4. Select an API product from the list and select Next.

    The Wizard opens the Select an Artifact page and displays all OData APIs associated with the selected product.

  5. Select the API to be used in the application and select Next.

    The Wizard displays the Provide Additional Details for the Selected API page.


  6. Select either Sandbox version or Production version from the Service to Use list.

  7. If you chose the Production version:

    1. Select the required service URL format from the Service URL list.
    2. Specify any required values in the fields provided to construct the back-end URL.

      The required properties may include account short name, appname, host and port, SSL host, and so on.

    3. Enter the API key that you acquired from the API owner.

  8. If you chose the Sandbox version, enter your username and password, then select Get API Key to retrieve the API key.

  9. Select Finish to save the destination and close the wizard.

    The new destination URL appears in the Add/Create New Destination dialog. Review the default settings and then select Add. The new destination appears in the Destinations list on the OData Services page.

Specifying Android Project Properties

Specify a name for your project as well as the project namespace and location.

You can also use this page to select the UI framework in which your app will be generated, either the traditional Views-based framework or the Jetpack Compose-based framework.

Project configuration

  1. Type a name for your project in the Project Name field. The name cannot contain special characters except for the underscore (_) character.

    When you type a name, the Wizard appends the project name to the end of the project namespace.

  2. If required, type another unique ID for your project in the Project Namespace field.

    The project namespace cannot contain spaces or special characters.

  3. Type a path for your project in the Project Location field.

    You can also select a path and folder for your project using the browse (...) button.

  4. The generated app is based on the Kotlin language.

  5. From the UI Framework area, select either Views-based UI or Jetpack Compose-based UI for your generated app.

  6. Select Next to proceed to the Project Features page.

Adding Mobile Services Features

Use this page to configure SAP Business Technology Platform and device features such as Discovery Service, push notification, and logging.

Project configuration

Adding Discovery Service

The Discovery Service simplifies the user onboarding process by letting you distribute initial configuration data to a mobile app.

If you enable the Discovery Service, the app is published to the Discovery Service during app generation. The service domain is then downloaded from the server and generated into the application.

If the app was previously published, it is republished using the default configuration options.

During onboarding, your app users are prompted to enter their email address or a short code. Once they have done so, the app downloads the required initial configuration.

To use a short code, you must configure the Discovery Service on the SAP Business Technology Platform. See Discovery Service Overview for more information.

If you decide not to use the Discovery Service, the Wizard creates a JSON file containing app configuration and includes it with the app during generation. During onboarding, the app uses the File Provider to read the JSON file and configure the app.


Discovery Service is not supported on Cloud Foundry. If your account is on the Cloud Foundry platform, the Use Discovery Service for Application Bootstrapping check box is disabled.

Adding Push Notifications

Push notifications require Firebase. To configure your app to use Firebase, create a Firebase account, configure Push service for your app, and download the JSON file (google-services.json) containing the push configuration.

You must also configure the server to use push. See Android Push Notifications for more information.

Procedure for Push

  1. Under Activation Options, select one of the following:

    • Generate AppConfig.json - Generates the sap_mobile_services.json file, which includes onboarding information. The user will not see the QR code scan or Discovery Service screens during the onboarding flow.
    • Scan onboarding QR code - Support Unsigned QR check box and Support Unsigned QR Code check box are enabled.
      • Support Signed QR Code - The signed QR code feature allows users to sign the QR code for onboarding using a private key.
      • Support Unsigned QR Code - The user will use QR code-based onboarding.
    • Use Discovery Service as Configuration Provider - Uses the Discovery Service to deliver the initial configuration during onboarding.
  2. Under OData, select either:

    • Online - Generates an online-only app
    • Offline - Generates an app that supports offline operation. This includes the ability to initialize and create the offline store, upload changes made on the client to the back end, and refresh the offline store as needed.
  3. To generate UI for the app, select Create a sample user experience for the selected OData destination.

    The Destination field displays the destination configured in the OData Services page. If there is more than one destination configured, the destinations are provided in a list. If required, select a destination from the list.


    If you clear this check box, the Wizard generates a project with only basic functionality, such as onboarding and proxy classes, but without code for UI, logging, or push notifications.

    Onboarding screens are still present, but the UI is replaced with a very simple "Hello world," which the user can replace or customize.

    If you select a destination from the list where the metadata file was uploaded locally and defined with client-only entities, the Wizard won't generate any UI for those client-only entities, but the corresponding proxy classes will still be generated for them.

  4. To allow your generated app to log information during runtime, select Enable Logging.

    Logging information is stored on the app. To upload stored logs to the SAP Business Technology Platform, select Enable Upload.

  5. To include code in your generated app for collecting app usage information and uploading it to the SAP Business Technology Platform, select Include Usage.

    When this check box is enabled, the Wizard generates an app with the corresponding code and enables the usage feature on the server. However, usage information is only collected and uploaded if the app user provides consent to usage collection during onboarding. Furthermore, the user can withdraw this consent at any time using the Settings screen.

  6. To have your generated app accept push notifications, select Enable Push, then upload the google-services.json file that you obtained from the Firebase website.


    The package name in the JSON file must match the project namespace.

  7. Select Finish to generate your new app.

    The Wizard connects to the SAP Business Technology Platform to register your app and send your app configuration settings.


    If the Wizard failed to download metadata from the configured destinations during application generation, it will open a dialog and ask you to upload an OData metadata file from your local file system, and the following warning message will be shown when the generated project opens in Android Studio:


    The following Destination(s) might be misconfigured, which can result in a non-working application. Please check the related settings in the SAP mobile service cockpit: [app ID]

    The generated application opens in Android Studio. It starts with a Welcome screen followed by the onboarding or Logon screen. After a successful logon, the application lists the OData Service collections that are available. You can select each entity to see its details.

    The Wizard automatically generates hundreds of lines of source code. For example, it uses the OData service definition to generate specific functions and calls to retrieve data from the SAP Mobile Services for each entity type, allowing the application to communicate with the back-end system using only the generated code.

    As a part of project generation, the Wizard also generates a WizardAppReadme file that provides an overview of the generated application and its architecture.

    See also Generated Application for more information.

Next Steps

Once you've generated your app, customize it as required. You can also configure and administer your app from the SAP mobile service cockpit as needed.

Generated Application

The generated application provides complete create-read-update-delete (CRUD) access to OData service data behind the selected application of the SAP Business Technology Platform server. It includes the Fiori logon screens for onboarding to the server and the OData and Foundation libraries that are used to consume the service.

The generated application presents a top level that provides a list of entity sets from the OData service. From here, you can navigate down to access the list of entities for a given set where you can select one of the entities to open a details view.

On the relevant screens, you can execute create, update, and delete operations.

The application can handle push messages and upload log records to the server. It can also upload client usage data to the server if the feature is enabled in the SAP mobile service cockpit and the user has agreed to allow tracking usage. Please note that these features are optional: they are only present in the app if the corresponding check boxes were selected during generation.

Build APKs with Different Build Variants

The generated application defines two different types of product flavors:

  • googlePlayStoreforGlobalMarket, for building APKs targeting global markets.
  • tencentAppStoreforChinaMarket, for building APKs targeting the China market.

Sample Build Variants Configuration

  1. Define flavorDimensions and productFlavors in the module-level build.gradle file inside the android block.

    android {
        defaultConfig {...}
        buildTypes {
        flavorDimensions 'appStore'
        productFlavors {
            create("googlePlayStoreforGlobalMarket") {
                dimension = "appStore"
            create("tencentAppStoreforChinaMarket") {
                dimension = "appStore"

Gradle automatically creates build variants based on the build types and product flavors as follows:

  • googlePlayStoreforGlobalMarketDebug
  • googlePlayStoreforGlobalMarketRelease
  • tencentAppStoreforChinaMarketDebug
  • tencentAppStoreforChinaMarketRelease

Users can choose the appropriate build variant to generate corresponding APKs for different markets. If push notification is enabled, Firebase push notification code will be generated automatically when selecting the googlePlayStoreforGlobalMarketDebug or googlePlayStoreforGlobalMarketRelease build variants. Baidu push notification code will be generated automatically when selecting the tencentAppStoreforChinaMarketDebug or tencentAppStoreforChinaMarketRelease build variants.


Refer to the Developer Guide for detailed information on build variants and product flavors.

Onboarding Flow

Upon initial launch, users will be presented with a series of screens.

  • For the global version of the application, click on the hyperlink for the End User License Agreement and Privacy Statement on the first screen. Users can review these agreements. To proceed, users must check the checkbox indicating their agreement to these terms and enable the Get started button.

Welcome screen Welcome screen

  • For the China version of the application, an End User License Agreement and Privacy Statement dialog will pop up on the initial screen. If the user clicks Agree, the secondary screen will be displayed.

Welcome screen Welcome screen

If the user clicks Disagree, another dialog will pop up requiring confirmation of their disagreement before presenting the third screen where users can either select Demo Mode to try out the demo application or check Agree to start using it. Welcome screen Welcome screen Welcome screen

Tapping the Get Started button triggers the logon flow.

The generated application supports Basic authentication, OAuth2, SAML, or no authentication. The code is generated according to the authentication type of the consumed application, which was set on the server. If the authentication type is Basic, then an Authentication dialog appears.

Authentication screen

After providing the correct credentials, the application receives the client-side configuration policy from the server containing the required passcode policy. If the application requires passcode protection, then a Create Passcode screen is displayed. This screen also contains information about passcode complexity. After a correct passcode is entered, a verification screen is displayed.

Passcode screen

After a passcode is created, the logon flow is complete. The application displays the entity set list that is accessible on the server.

By tapping the menu in the top-right corner, you can open the Settings screen, which allows you to configure and enable settings such as log level, log upload, and client usage collection. Please note that logging and client usage are optional features that are selected in the Wizard during application generation.

From the Settings screen, you can also change the passcode or reset the app, which deletes the credentials of the app and any downloaded data. Please note that setting or removing the passcode is only available if client policies have not been applied to the application or the Passcode Policy feature has not been enabled on the server.

Support Application Themes

Create themes using the SAP Theme Designer. The SAP Horizon Dark / Light theme is used as the base and you can customize the background color and text color. After the theme is ready, you can use it to configure the application using the SAP mobile service cockpit. See the "Managing Application Themes" section for additional information.

When the onboarding process is completed and the application displays the entity set list, the configured theme is applied to the application automatically. First custom_screen If you enable dark mode on the device, the application will be switched to the dark mode defined in the theme. In the following example, you can see the company logo and background color have been replaced with the customized versions. Second custom_screen

Business Logic

First screen

After selecting one of the entity sets, another list is opened containing the entities of the collection.

When the screen width is at least 900 dpi, for example on a tablet in landscape orientation, both the collection and detail screens are visible. In this mode, the right frame contains the Create/Edit/Detail screen, while the left frame contains the list.

When the entity set includes an image, it is loaded. Otherwise, the first letter of the item is displayed.

Second screen

The floating button on the bottom-right corner can be used to create and add a new entity to the set. Tapping it opens a creation screen. Long press to select one item to update or one or more items to delete using buttons on the action bar.

Third screen

By selecting one of the list items, you can open the details view of the given entity and then use the buttons on the action bar to edit or delete it.

On a tablet in landscape view, the details for an item are visible, as is the list. Using the action bar buttons, you can edit or delete the given item. In master-detail view, every frame has its own toolbar.

Additionally, if the entity provides navigation links, you can navigate to another screen to view related entities.

Fourth screen


When you re-open the app after registration, you will be presented with an unlock screen if the app is protected by a user-defined passcode. The generated app supports the retry limit feature, which means that the possible number of failed unlocking attempts is limited. The limit is set on the server as part of the client policy.

The client policy is read after the onboarding is finished and after each successful unlock. If the passcode policy is changed and the current passcode does not meet the requirements, the user is notified to change the passcode.

Unlock screen

Passcode screen

Push Notification

If the push feature is selected in the Wizard during project generation, then the application can receive push notifications. In order to process notifications, the application has to be running. If the app is in the foreground, then the push message appears in a notification dialog over the current activity. If it is in the background, then a notification appears on the system notification bar.

Push notification

Configure App Using sap_mobile_services.json

All application configurations are stored in the sap_mobile_services.json file under the raw resources folder, /app/src/main/res/raw. The following example shows the content of this JSON file.

    "__comment": "When modifying this file, you need to reset or reinstall all current client installations",
    "auth": [{
        "type": "oauth2",
        "config": {
        "oauth2.clients": [
            { "clientID": "9243b4db-6b88-4bc7-943f-743c1f67c857", "redirectURL": "", "grantType": "authorization_code" }
        "oauth2.tokenEndpoint": "",
        "oauth2.authorizationEndpoint": "",
        "oauth2.endUserUI": ""
    "requireOtp": false
    "serviceURL" : "",
    "appID" : "your_application_id",
    "appVersion" : "1.0"

You can easily configure the app by modifying this file. For example, you can modify the 'serviceURL' to migrate the app to another landscape. Or, you can remove 'auth' and 'serviceURL' to make the app determine configuration using Discovery Service. The new configuration will take effect without code regeneration or modification after the current app is reset or reinstalled.

Regenerating Proxy Classes Using the Wizard

Regenerates the proxy classes based on the current back-end metadata. The Wizard attempts to download the latest metadata files from Mobile Services and regenerates the proxy classes based on these files. If no metadata is present, the Wizard does not regenerate or attempt to download the files from SAP Mobile Services.


The Wizard will check the context file that was created during project generation, which defined the required configuration information for regenerating proxy classes. If no context file exists, or it's not valid, the context menu item of Regenerate Proxy Classes will not be shown.

  1. Right-click on the project and select Regenerate Proxy Classes.


    This feature only support apps created with SDK version 3.4 or later.

  2. Enter the passcode if the Enable Secure Store dialog is displayed. The Regenerate Proxy Classes dialog is then displayed. OData services

  3. To upload a local metadata XML file, click Select in the row of the specific destination from the Mobile Services server. OData services
  4. Click Regenerate. The Wizard will download all the latest metadata files from Mobile Services, except for those uploaded from the local file system, and update/add the metadata files to your application project. When all the metadata files are ready, the Wizard builds the proxy classes according to the latest metadata files.


    If the Wizard fails to download the metadata files from Mobile Services, it will display the File browser to support uploading a metadata file from local.

Using Microsoft Active Directory Federation Services for SAML Authentication

If you are using Microsoft Active Directory Federation Services (AD FS) for user authentication, then you will need to add an extra Endpoint to your configured Relying Party Trust in order for the Wizard to authenticate against AD FS.

  1. Open the ADFS Management console and select Relying Party Trusts from the navigation pane.
  2. Select the configured relying party trust and select Properties.
  3. From the Endpoints tab, select Add SAML….
  4. In the Edit Endpoint dialog, edit the endpoint as follows:

    1. From the Endpoint type list, select SAML Assertion Consumer.
    2. From the Binding list, select POST.
    3. Add the Index, which does not exist yet. Do not make this the default.
    4. Add the following as the Trusted URL: https://<AdminAPIURL>/mobileservices/origin/hcpms/application/v1/odata/admin/ApplicationSet/$count
  5. Select OK to save your settings and close the Edit Endpoint dialog.

  6. Select OK to close the Properties dialog.

Last update: June 15, 2023