Skip to content

Migration Overview

In this document we discuss two different migration scenarios. The first is about migration from SAP Mobile Platform to SAP Mobile Services and the second is about migration from the Neo environment to the Cloud Foundry environment.

Migration From SAP Mobile Platform

The SAP Mobile Services can be considered the successor of the SAP Mobile Platform. For customers who want to migrate to mobile services it is often challenging to get started. The following overview provides guidance to start planning the migration.

This is an example of a typical SAP Mobile Platform solution architecture:

SAP Mobile Platform Solution Architecture

On the left hand side, the internet is shown. Here's where the mobile apps run on different devices. In order to connect to the on-premises landscape, devices must be able to cross the DMZ (demilitarized zone) to access SAP Mobile Platform. Access is typically configured with rules in the reverse proxy and load balancers, or with the Relay Server - a component of SAP Mobile Platform. In order to retrieve data from business systems, SAP Mobile Platform connects to them either via SAP Gateway or directly if appropriate. While this looks relatively straightforward, complexity increases when introducing the development, quality and productive landscapes, and the database systems needed to support SAP Mobile Platform.

As you can see, the footprint of SAP Mobile Platform can be large.

Migration to SAP Mobile Services offers a lot of advantages:

  • Reduced on-premises infrastructure, resulting in less maintenance cost
  • Faster access to innovations, allowing more engagement and robust mobile solutions
  • Easier scalability, enabling faster expansion of successful mobile solutions
  • Leveraging synergies between other cloud services, widening the scope of mobile apps

Current on-premises infrastructure needs to be closely maintained. This includes updating SAP Mobile Platform with latest Service Patches, maintaining database backups and applying database patches, updates of new operating systems versions. In addition, a typical landscape of SAP Mobile Platform consists of a development, quality (and potential staging) and production landscape. All these, often virtualized, systems needs to be kept operational. In addition to this, a local SAP Mobile Platform installation needs to be connected to the outside world, typically via a reverse proxy or the Relay Server. These components needs to be maintained as well. All these infrastructure components can be substituted with SAP Mobile Services.

The innovation cycle on SAP Mobile Services is much faster than on SAP Mobile Platform. The nature of a cloud product allows the seamless introduction of patches and new features to all customer simultaneously; for on-premises software, each customer must manage the upgrade cycle. When upgrades are not kept current, access to new innovations is preempted. Over the years, this has resulted in many features not being available on SAP Mobile Platform. Here are some examples of features not being available on SAP Mobile Platform, but on mobile services:

  • SAP Mobile Cards
  • Mobile Development Kit
  • SAP BTP SDK for Android
  • SAP BTP SDK for iOS
  • App catalog
  • Cloud build server
  • Usage analytics

Due to the nature of SAP Mobile Services, scalability of mobile solutions is provided by SAP using state-of-the-art, cloud native design patterns and highly automated system landscapes. In case of SAP Mobile Services, customers can entrust SAP to deliver the resources needed to operate mobile services to its full potential.

The last benefit for cloud customers in this context is that mobile services is one offering of SAP Business Technology Platform, but one that can leverage other services to extend its capabilities and benefit from other services innovation cycle as well.

Example 1: Your cloud account uses SAP Identity and Authentication Service in order to authenticate your users on a mobile device. By introducing two-factor authentication(2FA) to your identity service all your mobile apps can leverage this feature as well - with no changes on your mobile solution.

Example 2: You use SAP Document Center to store, manage and share company-wide documents. By connecting mobile services with the SAP Document Center you can provide access to the document repository from within your mobile application.

Migration Project

The migration project can be divided into four steps:

  • Assessment
  • Landscape Migration
  • Application Migration
  • Cloud Excellence


In order to create a migration plan, you need to assess the currently used technologies running on SAP Mobile Platform.

SAP Mobile Platform consists of different technologies:

  • OData
  • Mobile Business Objects (MBO)
  • Agentry
  • Integration Gateway

Each technology stack has a different migration strategy.


This migration path is the most common one, specifically for all Kapsel and SAP Fiori Client based projects. All SAP Mobile Platform SDK 3.2 solutions, based on OData fall into this category, namely Kapsel, custom SAP Fiori Client, native iOS, Android and Windows SDKs. These solutions are API compatible with SAP Mobile Services.

Migration of mobile solutions based on Mobile Business Object (MBO) technology requires a bit more effort. Firstly, the MBO data model needs to be translated into an OData service. You can read the detailed instructions about this in MBO Migration. Then, the data access layer in the mobile app needs to be adjusted to connect to the OData service instead of using the Object API provided by the MBO. The effort needed for this step can't be assessed here, since it depends heavily on the customer solution. It could be that it is better to rewrite the app, either with the Mobile Development Kit or even with the SAP BTP SDK for iOS or SAP BTP SDK for Android.

In case of Agentry-based solutions like SAP Work Manager or SAP Inventory Manager, the migration path is to reuse the exiting application with SAP Work Manager, cloud edition or SAP Inventory Manager, cloud edition, respectively. In this case, migration is straightforward as cloud products allow running the existing, customized on-premises version on an Agentry Cloud Edition (ACE) based infrastructure. Prerequisite to this path include:

  • Migrating a license to a cloud edition
  • Upgrading to the latest Work Manager (6.4.1+) or Inventory Manager (4.3.1+) version before migration

Important is that all customer customization can be carried over and local Agentry installation and maintenance can be shut down after migration.

Integration Gateway in SAP Mobile Platform was a way to map non OData data sources to an OData service. This functionality has been replaced by the Mobile Back-End Tools. You can find more information about it in Installing the Tools. There is no way to carry over the mappings, but recreating the mapping in Mobile Back-End Tools is a very straightforward task and the needed effort should be minimal.

Here's a table to compare all the options at a glance:

Technology Replacement in mobile services Migration Effort Migration Strategy
OData Reuse SMP SDK, or new SDKs Low Re-deploy
MBO Native, MDK, Mobile Back-End Tools Medium-High Adapt
SAP Work Manager/Inventory Manager SAP Work Manager, cloud edition or SAP Inventory Manager, cloud edition Medium Adapt and reuse
Integration Gateway Mobile Back-End Tools Low Re-develop

Landscape Migration

In the next phase you would plan and execute the landscape migration.

As you can see in the Solution Architecture overview, mobile services is different to SAP Mobile Platform.

Creating the SAP Mobile Services landscape can be roughly divided into these steps:

  • Creating Organizations, Accounts, Sub-Accounts and Spaces
  • Installing SAP Business Technology Platform SAP Cloud Connector
  • Configuring Identity Provider
  • Recreation of mobile specific configuration

While there is no need for a Relay Server or reverse proxy, SAP Business Technology Platform needs to be enabled to connect to the on-premises network. In order to achieve this, SAP Business Technology Platform comes with the SAP Cloud Connector. This is an on-premises software component that will establish connection from within the customers network to the SAP Business Technology Platform accounts of the customer. This secure connection can then be leveraged by all SAP Business Technology Platform services, not only mobile services. This SAP Cloud Connector will then be the only remaining on-premises component on customer side, lowering the system footprint significantly. After installing the SAP Cloud Connector component, administration tasks involve allowing local resources and configuring principle propagation to on-premise data sources. This task is not mobile-specific, and only needs to be done once. You can find more information about SAP Cloud Connector in the documentation

Cloud Foundry has a robust design to reflect organizations, team and spaces. It's important to understand these concepts before creating your own setup. You can find more information about this in SAP Business Technology Platform documentation. In general, you would use spaces to reflect development, quality and productive areas. Depending on your requirements this could also be designed differently.

The Identity Provide (IDP) is the authority to grant access to your solutions running on SAP Business Technology Platform. There are plenty options to choose an IDP. In case of SAP Business Technology Platform trial accounts, the IDP is SAP Identity and Authentication Service, which manages all the S- and P-Users and allows Single-Sign-On for all SAP resources. Customers will use their own IDP and can either use the SAP Business Technology Platform Identity Authentication service or connect their existing IDP. This task is not mobile specific and only needs to be done once. The mobile services will leverage the IDP automatically. More information about Authentication on SAP Business Technology Platform can be found in the documentation

Actual administration of Mobile Service takes place on the "space" level. Here, mobile services provides an administration cockpit very similar to the administration cockpit of SAP Mobile Platform. The task during migration is to re-create all application configurations from SAP Mobile Platform in the SAP mobile service cockpit. Even though there is no import/export functionality available, this task is rather trivial and should not take more than a couple of minutes. How application configuration will be created is documented here.

Application Migration

Right after the new landscape has been established, all mobile apps needs to be adjusted to connect to SAP Mobile Services. Usually, it is enough to change the target URL in the mobile solution, depending on the security settings minor changes could be necessary in that area as well.

Major code changes are usually not necessary, however a completely seamless migration is not possible, due to the environmental differences between SAP Mobile Platform and SAP Mobile Services. A migration affects both the local architecture and the user experience. The following table describes the source and corresponding target landscape for an SAP Mobile Platform application.

Premigration Landscape (SAP Mobile Platform) Postmigration Landscape (SAP Mobile Services)
SAP Cloud Connector
SAP Mobile Platform 3.x installed SAP Mobile Services installed
SAP Gateway provides OData services for the mobile application to be migrated (on-premise) SAP Gateway provides OData services for the mobile applications to be migrated (on-premise)
Mobile applications are hybrid Android, iOS, or Windows 8.1 applications, which use the Mobile Application Framework (MAF) Logon plug-in. Mobile applications are hybrid Android, iOS, or Windows 8.1 applications, which use the Mobile Application Framework (MAF) Logon plug-in.
Mobile user authentication uses basic HTTP against the SAP Gateway system on-premise and external OData services. Mobile user authentication uses basic HTTP against the SAP Gateway system on-premise and external OData services.

Keep in mind that application migration is not possible for:

  • Agentry-based applications

  • Mobiliser-based applications

  • Mobile applications that require custom OSGi bundles; in this scenario, you must migrate the code-base bundle to SAP Business Technology Platform mobile service for app and device management.

  • Applications that are based on mobile business object (MBO) technology

  • Applications that use custom OSGi authentication modules Short Message Service (SMS) based applications

Cloud Excellence

Due to the different nature of on-premises and software, after migration to cloud environments tasks and responsibilities of administrators change. While previously, administrators where responsible to update SAP Mobile Platform with service packs and patches, provide hardware resources, manage database update all this is now managed by SAP behind the scenes and administrators don't need to bother anymore. Nevertheless, that does not mean administrators are no longer needed. The focus for administrators in the context of SAP Mobile Services is more to make sure that deployment and operations is automated as well as automated test for all mobile applications are in place and functional. This is a continuous process and it is OK when not all operational steps are fully automated right after the migration, but it should be the objective to achieve this over time.

Migration From Neo to Cloud Foundry Environment

Migration from SAP Mobile Services Neo to Cloud Foundry environment is another migration scenario. The steps in this scenario are very similar to the landscape migration mentioned above:

  • Creating Organizations, Accounts, Sub-Accounts and Spaces
  • Installing SAP Business Technology Platform SAP Cloud Connector
  • Configuring Identity Provider
  • Recreation of mobile specific configuration
  • Adjusting the mobile application

Neo account structure differs from the Cloud Foundry concept, and must be carefully translated into the concepts of organizations, sub-accounts and spaces.

SAP Cloud Connector setup must be copied to point to the Cloud Foundry accounts.

Identity provider settings need to be replicated. Overall the security concept of Cloud Foundry differs significantly from Neo environments and a complete discussion of this topic out of scope here. Documentation of security concepts can be found here.

The mobile services provide a similar, but not identical, administration cockpit in Cloud Foundry. The concepts are the same, but due to underlying technical differences, some tasks have been moved into different places in the SAP mobile service cockpit. For instance, application security is no longer configured by assigning a "Security" feature to a mobile app, but configured through an application-level tab. Administrators must get familiar with the subtle differences, but this usually does not take much time or need dedicated training.

Finally, the mobile application must be adjusted to connect to the Cloud Foundry environment. Usually it is enough to change the target URL in the application, but there may be changes necessary to reflect differences in the security setup. Some features are not supported for mobile services on Cloud Foundry. The sections that follow identify some differences with Cloud Foundry.

Missing Functionality in SAP Mobile Services Cloud Foundry

  • Mobile Application security configuration does not support "No Authentication". All interaction from a mobile application must be made in an authenticated manner.

    As an alternative, SAP Mobile Services on Cloud Foundry provides the security configuration "API Key Only" which uses a common API Key per application for all users connecting to SAP Mobile Services and does not require user-specific authentication.

  • Mobile Application security configuration does not support certificate based authentication. SAP Business Technology Platform Cloud Foundry does not support establishing an SSL connection using client certificates (mutual authentication). You can still leverage certificates deployed to mobile applications with your identity provider of choice. Please use authentication methods OAuth (preferred) or SAML in the security configuration. The user authentication occurs in a Web View, which can present the certificate to the identity provider if requested. This avoids the need for any user input, while still leveraging an existing certificate infrastructure.

  • One-time passcodes in combination with Basic Authentication is not supported. Instead you can configure one-time passcodes with two-factor authentication right in SAP Business Technology Platform Identity Authentication Service. This is supported for the mobile services authentication methods SAML and OAuth.

  • Secure login server is not supported.

  • Document repository is not supported.

    As an alternative, you can create a destination to a back-end system using existing Cloud Foundry service instances. See Creating a Destination with Existing Service Instances, and search for "Document service instances" to learn more.

SAP Mobile Services Cockpit Changes

If you are familiar with the SAP mobile service cockpit, you will find that there are several differences in the mobile services Cloud Foundry cockpit. The major changes are:

  • Access to SAP mobile service cockpit is authenticated with the SAP Identity and Authentication Service (Default identity provider). The Trust Configuration from the Cloud sub-account is only used at runtime (when a user connects through a mobile application).

  • Destinations are no longer configured at the global level, but at the application level.

  • Network traces are configured and accessed as a feature at the application level. The feature must be added to the mobile application for which you want to capture network traffic.

  • Mobile Application Alerts are configured and accessed at the application level. The feature must be added to the mobile application for which you want to send alerts).

  • The list of onboarded users and devices is part of the Mobile Settings Exchange feature (mandatory feature for each mobile application). You can see the list of registered users and devices in this feature under User Registrations.

  • There is no more global log configuration page. Instead you can enable detailed event logs for each mobile application and feature separately. When enabled, DEBUG and INFO event log messages are logged and available under Analytics Logs (similar to Neo).

  • The Security configuration of a mobile application is no longer handled as a feature, but as a separate mobile application tab.

  • Test push messages are now triggered from within the Mobile Push Notification feature of a mobile application.

  • To enable basic authentication you need to establish trust between mobile services and the sub-account. This must be done once for each Space in which mobile services is used, and configured for supporting Basic authentication. For information about establishing trust, see Configuring Trust for Basic Authentication

  • Uploaded client logs (mobile application logs) are now accessed from with the Mobile Client Log Upload feature of a mobile application.

  • Test users are no longer marked inside SAP mobile service cockpit as such, but must be mapped to the BetaTestUser role in the SAP Business Technology Platform cockpit (under Security > Trust)

Migration of Mobile Application Configurations

Once you become familiar with some of the changes in SAP mobile service cockpit operations, replicating mobile application configurations between Neo and Cloud Foundry should be straightforward. Ideally, replicate a few applications and accounts manually to become familiar with the SAP mobile service cockpit.

You can recreate the application manually, or export the application configuration on Neo and import the configuration on Cloud Foundry. The latter process is described in Importing Application Configurations. Please be aware of the caveats described on that page. Typically some manual adjustments are required after you import the application (rarely are adjustments not needed).

Importing Neo Applications

Because of mobile services differences on Neo and Cloud Foundry, only part of application configuration can be imported into Cloud Foundry, and other parts of configuration must be recreated.

  • Application basic info
  • Security feature
  • Client Policy feature
  • Connectivity feature
  • Offline feature
  • Push feature

Before Importing the Application

  • Import customer Identity Provider in Cloud Foundry subaccount.

  • Connect SAP Cloud Connector to Cloud Foundry subaccount, and configure virtual host for back-end servers if using SAP Cloud Connector.

  • If using $mail in Subject Pattern of Principal Propagation in SAP Cloud Connector, change to use $email property. It is recommended to use $name property in Subject Pattern in order to use one SAP Cloud Connector to support both Neo and Cloud Foundry.


Please notice that the value of $name might be different on Neo and Cloud Foundry when using SAP Identity and Authentication Service to authenticate users. Using customer Identity Provider has no such difference.

After Importing the Application

  • Input password or key in "Push" feature if exists.
  • Import app revisions in "App Update" feature if exists.
  • Import client resources in "Client Resource" feature if exists.

Authentication Type

After importing into Cloud Foundry, some manual steps are required for some authentication types. The following table shows the authentication type mapping between Neo and Cloud Foundry, and actions for some.

Authentication Type in Neo Authentication Type Imported into Cloud Foundry Actions
OAuth OAuth N/A
Basic Basic with SAP Identity and Authentication Service N/A
Basic with SCIM/HMSCIM Basic with SAP Identity and Authentication Service Change Authentication Type to "Basic" with the basic back-end server information.
Certificate SAML The mobile services does not support user certificate login because the Cloud Foundry platform does not support it. As an alternative solution, customers can choose to enable user certificate login in their IDP with the SAML authentication type. After modifying device application to use SAML authentication, user login can always use a user certificate from the device. The mobile destination SSO mechanism must also be modified correspondingly.
None SAML The mobile services does not support No Authentication. As an alternative solution, mobile services supports the API Key authentication type, which is very similar to No Authentication type, as of the end of 2020. API Key requires the Device application to use the same authentication type.

Mobile Destination and SSO Mechanism

Some mobile destination properties cannot be exported from Neo, so they must be configured manually after the application is imported into Cloud Foundry.

  • The keystore, or truststore, must be configured manually.

  • Credential properties (such as password, key, clientsecret properties) must be configured manually.

The following table shows the SSO mechanism mapping between Neo and Cloud Foundry, and any actions required for different SSO mechanisms.

SSO Mechanism in Neo SSO Mechanism Imported into Cloud Foundry Actions
No Authentication No Authentication N/A
Basic Authentication Basic Authentication N/A
Principal Propagation SAP Cloud Connector SSO N/A
Application-to-Application SSO Application-to-Application SSO Generate a signing key for the mobile destination, download SAML metadata, and import the metadata into the subaccount on which the back-end service runs.
OAuth2 SAML Bearer Assertion OAuth2 SAML Bearer Assertion Generate a signing key and fill secret properties for the mobile destination, download SAML metadata, and import the metadata into the subaccount on which the back-end service runs.
Client Certificate Authentication No Authentication Configure the keystore.
SAPAssertionSSO No Authentication SAPAssertionSSO is not supported by mobile services on Cloud Foundry, and the customer must choose another SSO mechanism that requires a corresponding back-end server configuration.

User (App) Migration

Mobile applications developed for SAP Mobile Services Neo are generally compatible with the Cloud Foundry counterpart with the aforementioned exceptions.

The application status must be reset when transitioning from Neo to Cloud Foundry (similar to transitioning from one Neo landscape to another). This should happen automatically when resetting the application and reconfiguration with a new URL. Users need to ensure that there is no unsynchronized data left in the local Offline databases before the application is reset.

The mobile application URL of Neo and Cloud Foundry is different. In Cloud Foundry, each mobile application has its own, unique host name to which to connect, as shown on the APIs page of an application. Also, the OAuth specific URLs of Neo and Cloud Foundry are different (authorization and token endpoints).

  • In case these URLs are hard-coded in the application binary that is distributed to your users (for example, via public app stores), then you will need to roll out a new version of the application. If this is distributed through a mobile device management tool, it also allows the phased migration of users between Neo and Cloud Foundry, and ability to observe the system before transitioning all users.

  • If the application is configured by scanning a QR code, the QR code reflecting the new configuration can be downloaded from the SAP mobile service cockpit and scanned by users after having the application reset.

  • Applications that use Discovery services to retrieve the onboarding details reload the configuration after the application is reset. New users automatically read the new configuration. This requires you to register the email domain with the new mobile services instance on Cloud Foundry and publish the configuration.

Migration Check-List

The exact steps for migration depend on your overall setup and on the type of application. The following section assumes that all back-ends / endpoints are accessible through SAP Cloud Connector. Other scenarios are also supported but the configuration can be different.

  • Ensure (with information on this page) that mobile services Cloud Foundry supports all your requirements.

  • Enable "mobile services" via Entitlements on your Global Account and assign it to the desired Cloud Foundry sub-account. Refer to the Enabling mobile services for details.

  • Create at least one space in the designated sub-account.

  • (Optional) Connect SAP Cloud Connector to the Cloud Foundry sub-account (the same SAP Cloud Connector can be connected to several SAP Business Technology Platform sub-accounts).

  • Replicate mobile application configuration, either manually or with the export/import feature (see this page for further details).

  • Enable "Detailed Event Logs" on all relevant Features that you are using to make sure to capture any discrepancies early.

  • Run initial tests in the mobile application by changing the URL to point to the new landscape.

  • Verify the Logs in mobile services for any potential problems.

  • Follow QA procedures that are specific to your organization.

  • Migrate a few users manually and make sure the application and back ends are behaving correctly before rolling out a large user base.

  • Plan the roll-out of the application. See further details on this page for the various options. Users must be aware that unsynchronized work (Offline) cannot be carried forward from Neo to Cloud Foundry. The application should be in a synchronized status before reconfiguration.


You can enable mobile services in any number of Cloud Foundry Spaces in a sub-account. Those instances of mobile services are completely isolated from each other.

This can be an appropriate approach to isolate various stages of your development process (dev/test/QA/prod). Keep in mind, however, that certain elements are shared on a sub-account level. This includes connected SAP Cloud Connectors, Identity Providers, and general trust configuration.

In most cases the better approach is to also isolate stages at a sub-account level, as you are familiar with on Neo.

New Feature Comparison for Cloud Foundry and Neo

Many new SAP Mobile Services features are now being added to Cloud Foundry only, and not Neo. Mobile Services (Cloud Foundry) is the mainstream version, and most new features of mobile services will only be available on Cloud Foundry.

Following is a list of features available on Cloud Foundry but not on Neo. The list contains only major runtime features that directly impact mobile application functioning. Most user interface enhancements to SAP mobile service cockpit, including the new analytics dashboard and others, are not covered.

  1. PKCE (Proof Key for Code Exchange) support for OAuth grant flow

  2. Localized push notification messages

  3. Micro App WeChat support (regular / social; China only)

  4. Digitally signed QR code support for onboarding

  5. Offline OData Version 4

  6. Crash log analysis

  7. Client Usage Feedback Service

  8. Augmented Reality

  9. Mobile Transaction Bridge

  10. Cross Context SSO support

  11. App Catalog

  12. Micro App DingTalk support (not available in all countries/regions)

  13. Service Keys support

  14. W3C push support

Last update: July 28, 2022