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 Cloud 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 Cloud Platform account with administrator privileges to create or edit configuration settings on the SAP Cloud Platform. If your account does not have administrator privileges, Wizard controls requiring full permissions are unavailable. See the Wizard screen topics for more information about account restrictions.

Procedure

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

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

  2. Follow the steps in the Wizard described below:

    1. Maintain your Mobile Services connection
    2. Create or reuse 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 Cloud Platform Mobile Services.

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 Cloud Platform
  • The authentication method, either Basic or SAML
  • The username and password for an SAP Cloud Platform account

You can find the Admin API and Admin UI URLs on the Important Links page of the SAP Cloud Platform Mobile Services cockpit. To access this page, log in to the SAP Cloud 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 IDP 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.

Note

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.

  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 mobile services 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 auto-filled 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 Cloud 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 Cloud 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 Cloud Platform to verify the settings.

Creating and Reusing New Mobile Services Application Configurations

Configure your app on the SAP Cloud Platform.

Cloud configuration

You can:

  • Create a new application definition for your app on the SAP Cloud 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.
  • The Application Identifier is a unique application identifier in reverse-domain notation. An app ID:

    • Can contain up to 64 characters
    • 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, com.sap.mobile.app1.

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 Cloud 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 .

    Note

    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 one, and has 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 Cloud Platform Mobile Services 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 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 Cloud Platform Mobile Services documentation.

You can also configure your app to consume OData services, referred to as "OData APIs", that are hosted on the SAP Cloud Platform API Management service's Developer Portal or on the SAP API Business Hub.

Note

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 API Business 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.

    Note

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

  4. 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 API Business Hub or the SAP Cloud Platform Developer Portal.

The SAP API Business Hub is a central API catalog available to developers who are building apps, extensions, and process integration with SAP Cloud Platform. See the SAP API Business 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 Cloud Platform. See the SAP Cloud Platform API Management documentation for more information.

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

To access APIs on the production service of either the SAP API Business 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 API Business 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.

    menu

  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 choose the target language, either Java or Kotlin, for your generated app.

  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. From the Target Language area, select either Java or Kotlin for your generated app.

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

Adding Mobile Services Features

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

Project configuration

Adding Discovery Service

The SAP 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 Cloud 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.

Note

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-sevices.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. To use the Discovery Service to deliver initial configuration during onboarding, enable Use Discovery Service as Configuration Provider.

    If you disable this option, the app uses the File Provider to provide initial configuration.

  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.

    Note

    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.

  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 Cloud Platform, select Enable Upload.

  5. To include code in your generated app for collecting app usage information and uploading it to the SAP Cloud 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.

    Important

    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 Cloud Platform to register your app and send your app configuration settings.

    Note

    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:

    Warning

    The following Destination(s) might be misconfigured, which can result in a non-working application. Please check the related settings in the admin 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 Cloud Platform 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 Cloud Platform Mobile Services 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 Cloud 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 Cloud Platform Mobile Services 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.

Onboarding Flow

At the first start of the application the following Welcome screen is displayed.

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.

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. 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

Unlock

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 prompted 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": "https://mobileservices-youraccount.hana.ondemand.com", "grantType": "authorization_code" }
        ],
        "oauth2.tokenEndpoint": "https://mobileservices-youraccount.hana.ondemand.com/oauth2/api/v1/token",
        "oauth2.authorizationEndpoint": "https://mobileservices-youraccount.hana.ondemand.com/oauth2/api/v1/authorize",
        "oauth2.endUserUI": "https://mobileservices-youraccount.hana.ondemand.com"
        },
    "requireOtp": false
    }],
    "serviceURL" : "https://mobileservices-youraccount.hana.ondemand.com",
    "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 re-generation or modification after the current app is reset or reinstalled.


Last update: October 21, 2020