Skip to content

Enabling OData for Your Own Project

Prerequisites for Enabling OData for Your Own Project

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 that require full permissions are unavailable. See the Wizard screen topics for more information about account restrictions.

Procedure

  1. Launch the Wizard and follow the prompts to create a library module configured with connections to the SAP Business Technology Platform and OData services.

  2. Open your project using Android Studio.

  3. Right-click on your project and select Generate Proxy Classes from the pop-up context menu.

  4. Follow the steps in the Wizard, as described below:

    1. Maintain a mobile services connection.
    2. Create or reuse mobile services application configurations.
    3. Add OData services.

Maintain a Mobile Services Connection

Configure the connection to your instance of the SAP Mobile Services (also known as the 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.

Note

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.

Note

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.

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

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

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

  2. 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, including 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.

  1. Click 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 ID (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 SAP Business Technology Platform environment.
  • The Application ID 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 SAP Business Technology Platform 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, 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 Business Technology Platform.

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

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

  3. 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. Click 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 that the ID is unique.
  3. Click 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 Developer Portal or on the SAP Business Accelerator 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 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.

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

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

Adding a Destination Using OData APIs From a Hosted Site

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 Adding OData Services

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

The API Management wizard opens.

API management

  1. From the Select an API Management Account page, select either SAP Business Accelerator Hub or 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 Developer Portal 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.
  2. Click Next to proceed to the Select an API Product page.

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

  1. Select an API product from the list and click Next.

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

  2. Select the API to be used in the application and click Next.

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

  3. Select either Sandbox Version or Production Version from the Service to Use list.

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

    1. Enter the API key that you acquired from the API owner.
  5. If you chose the Sandbox version, enter your username and password, then select Get API Key to retrieve the API key.

  6. 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 click Add. The new destination appears in the Destinations list on the OData Services page.

Uploading the Local Metadata XML File for a Specific Destination

To use a local metadata definition to generate an app, upload the local metadata XML file for a specific destination directly. Click Select... in the row of the specific destination and then browse your local file system to upload a valid metadata file.

OData services

Next Steps

Click Finish in OData Services page to generate your new library module for OData proxy classes.

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

Note

If the Wizard failed to download metadata from the configured destinations during module 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:

Warning

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 odataproxyclasses library module is created in your Android Studio project. In order to make this new module visible in Android view, you have to sync the project with gradle files.

Sync Project

Click Sync Project with Gradle Files. This new module will be shown in the Android view when this sync process is completed.

OData Proxy Classes Library Module

The Wizard automatically generates lots 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.

Note

If the Wizard failed to build the odataproxyclasses module during module generation, make sure that the mavenLocal() repository has been configured in your project-level build.gradle file.

Once the odataproxyclasses module is created, you can add the dependency in your application module to consume those generated proxy classes. You can also configure and administer your app from the SAP mobile service cockpit as needed.


Last update: February 20, 2023