Introduction

SAP Cloud Platform – SCP offers multiple options for developing and consuming applications. You will probably hear the following terms:

• SaaS –Software as a Service: enables software consumption using subscription and without a development environment
• PaaS – Platform as a Service: enables software development (and consumption)
• IaaS – Infrastructure as a Service: enables to running your cloud application in the cloud infrastructure of choice – e.g.: Amazon, Google Cloud, Open Stack, Azure or private clouds

The SAP Cloud Platform Programming Model, enables you to develop cloud applications easily supporting multiple provisioning channels.

Let’s get started.

Overview

A Business Solution in the SAP Cloud Platform world is represented by a set of one or more MTAs (multi-target application). An MTA may include several modules that use different software languages/technologies.

Single MTA modelling enables the creation of a single MTAR archive that can be easily deployed as a packaged solution into multiple landscapes.

Multiple MTA modelling is more appropriate for products developed by multiple teams with separate sub-component lifecycles (e.g. backend & frontend).

In this document, I will mainly describe the development process for a single MTA project focusing on the HTML5 applications and FLP Content Development leveraging the recently released Portal and HTML5 Application Repository services.

Development Process

A typical development process includes the following steps:

1. Development and testing in SAP Web IDE

• Create a new MTA project
• Develop one or more Fiori/HTML5 application modules
• Develop the backend application modules (if backend is in CF)
• Develop the database modules (HDI)
• Add an FLP module (SAP Fiori Launchpad) referring to your Fiori/HTML5 applications
• Model your CDM (common data model) content for FLP
• Run the application modules in preview mode
• Run the application modules in CF (without deploying)
• Deploy to a CF test space to test integration with other services (e.g.: XSUAA or Destination and Connectivity in case integration to non-SAP Cloud Platform Services like S/4HANA ODATA Services is required)
• Develop automated tests
• Push to Git

2. Develop your continuous delivery process

While developing your continuous delivery process you will need to build your mtar using the  Multitarget Application Archive Builder

3. Administer your Destinations in Cockpit

• See Connectivity in SAP Cloud Platform

4. Create and assign role collections to users

• See XSUAA Security

A picture of the development process is depicted here:

Application Development and Runtime

SCP Applications Building Blocks

To develop applications in SAP Cloud Platform, you need to be familiar with their main building blocks. A short description is provided here. In the following chapters, we will deep dive into the modelling and the implementation will be described in more detail.

High Level Architecture

In the following high-level architecture diagram, you can see how the main development components interact with each other.

HTML5 Application Repository Service

A Fiori/HTML5 application consists mainly of static files (html, css, json, etc.) and Javascript files. Typically, it also interacts with one or more backend applications that deliver business data.

Unlike classic CF applications that run on the server side, HTML5 applications are a set of runtime objects that should be stored in a permanent storage and eventually served to the browser, where they run.

The HTML5 Application Repository service enables storing and serving HTML5 application content in an optimized manner.

Main Features – Added Value

Application Lifecycle

• Multi-Version Support and Content Lifecycle
  • Multi-version support for Fiori/HTML5 applications
  • Fiori/HTML5 applications can co-exist in runtime and be available to different end-users of the application that consume backends with different versions
  • Standardized content lifecycle process
• Metadata and Discovery API
  • Fiori/HTML Application metadata provider for Design and Runtime. e.g. used by the SAP Fiori Launchpad
• Performance, Resilience and Decoupling
  • Provisioning of static resources with optimized caching support
  • Content update without downtimes
  • Decoupling from platform specific storage services

Integration Flows Support

• Multiple HTML5 Applications and Business Service UIs Served by a Single Approuter
  • Routes  configuration file (xs-app.json) is now part of the HTML5 application, enabling decoupling the lifecycle of single applications from the Application Router
  • Application Router still supports a central xs-app.json file for non HTML5 Application Repository applications routing (e.g,.: SAP Analytics)
  • HTML5 applications can be uploaded via multiple MTAs without Application Router down times
• Business Service UI Integration
  • Customer or Partner SaaS Applications will be able to consume Business Services UIs. The FLP2.0 is for instance a Business Service which provides a Launchpad Site UI. SAP will provide further Business Services soon supporting this concept.
  • FLEX service can replicate HTML5 applications’ specific content for optimization and personalization
• SAP Fiori Launchpad Integration
  • FLP 2.0 is bound to the Application Router and integrated just as any other Business Service
  • FLP 2.0 runtime interact with the Application Router to request static UI resources from HTML5 Application Repository and to route request towards applications or Business Services

Service Plans

app-host service plan – Paid

• A service instance of this plan is required to upload content into HTML5 Application Repository
• With a single instance it is possible to upload multiple HTML5 applications
• Payment by storage (MB) – it is bundled to the Application Runtime service, it means that for a specific amount of Application Runtime quota a certain amount of HTML5 Application Repository service storage is granted.

app-runtime service plan – Free

• A service instance of this plan is required to read content from HTML5 Application Repository
• With a single instance it is possible to read all the HTML5 applications uploaded from the same space

Design Time – Creating “app-host” Plan Service Instance

An app-host service instance can be created in two ways:

1. Explicitly by using the cf create-service statement in CF CLI
2. Implicitly, when using cf deploy to deploy an mtar that has a resource using service html5-apps-repo with plan app-host

Size Limit

An app-host service instance has a size limit. This means that you cannot upload content that exceeds this size limit. Note that the unzipped total size is checked.

In addition, the size limit of an instance is reduced from the quota assigned to the subaccount mapped to the organization in which you create the app-host service instance.

During deletion of the app-host service instance, all uploaded content is automatically deleted, and the quota consumption is decreased accordingly.

An instance of the app-host service plan is created with a default size limit of 2 MB.

By providing a configuration parameter, you can define a higher size limit that can be up to 100 MB. It is also possible to increase the current size limit. Decreasing the size limit is currently not supported.

For example:

• cf create-service html5-apps-repo app-host my-app-host -c app-host-config.json
• cf update-service my-app-host -c app-host-config.json

Where app-host-config.json file is:

{
  "sizeLimit": 5
}

Create app-host Service Instance Flow

HTML5 Application Deployer

HTML5 Application Deployer is an npm module provided by SAP that is consumed as a dependency in a UI deployer application. This application must be part of your project in order to upload content to the HTML5 Application Repository service.

The UI deployer application should be bound to an html5-apps-repo service instance with plan app-host to enable the uploading.

The applications to be deployed should be placed as sub-directories or zip archives in a resources folder (if not zipped, HTML5 Application Deployer will zip them).

An HTML5 application deployed to HTML5 Application Repository must have two main files at root level: manifest.json and xs-app.json.

Fiori/HTML5 Application manifest.json file

The manifest.json file is a standard application descriptor in all Fiori/HTML5 applications. Nevertheless, you can also deploy a non-Fiori or even a non-SAPUI5 application into HTML5 Application Repository. If the latter is the case, you have to provide a minimal manifest.json file with the following attributes:

• sap.app.id: the application name that will be used in the first segment of the Application Router url. Note that in the url, the appName should be used without the dots.
• sap.app.applicationVersion.version: the application version in format xx.xx.xx. It can be provided in the Application Router url as well. If not provided, the latest version will be used.
• sap.cloud.service: the name of the Business Service – only required for HTML5 Applications exposed by Business Services.
• sap.cloud.public: if set to true the HTML5 Application will be exposed to consumers from other spaces than the one from which the HTML5 Application was deployed. Currently it only applies to Business Services.
• dataSources.mainService.uri: this is not really required by HTML5 Application Repository.  However, it is important to know that this path must be relative (no slash in the beginning of the path).

Local HTML5 Application manifest.json

{
  “sap.app”: {
    “id”:“com.acme.appbasic.salesorders”,
    “applicationVersion": {
        “version”: “1.0.0”
    },
    "dataSources": {
       "mainService":{
          "uri" : "odata/v2/salesorders",
          "type": "OData"
    }
  }
}

In this case the Application Router url will be:

https://myapprouter.cf.hana.com/comacme.appbasicsalesorders/index.html

In case the HTML5 application is exposed by a Business Service, additional attributes defining the service name and UI visibility should be provided.

Business Service HTML5 Application manifest.json

{
  "sap.app": {
              "id": "com.sap.appbasic.country.list",
               "applicationVersion": {
                     "version": "1.0.0"
                },
               "dataSources": {
                     "mainService": {
                          "uri" : "odata/v2/countryservice",
                          "type": "OData"
                     }
                }
   },
   "sap.cloud": {
         "public" : true,
         "service": "com.sap.appbasic.country"
   }
}

In this case the Application Router url will be:

https://myapprouter.cf.hana.com/comsapappbasiccountry.comsapappbasiccountrylist/index.html

xs-app.json

The xs-app.json file is used by Application Router to determine the reverse proxy dispatching logic.

An xs-app.json for a local HTML5 application may look as follows:

Local HTML5 Application xs-app.json

{
  "authenticationMethod": "route",
  "routes": [
    {
      "source": "^/odata/v2/(.*)$",
      "target": "$1",
      "destination": "mybackend"
    },
    {
      "source": "^(/.*)$",
      "target": "$1",
      "service": "html5-apps-repo-rt",
      "authenticationType": "xsuaa"
    }
  ]
}

The last route provides access to HTML5 Application Repository runtime to retrieve the static content.

In case the xs-app.json refers to an HTML5 application provided by a Business Service, the data provider will be the Business Service. In addition, you can define a specific endpoint for the service.

An xs-app.json for an HTML5 application provided by a Business Service may look as follows:

Business Service HTML5 Application xs-app.json

{
  "authenticationMethod": "route",
  "routes": [
    {
      "source": "^/odata/v2/(.*)$",
      "target": "$1",
      "service": "com.sap.appbasic.country",
      "endpoint": "countryservice"
    },
    {
      "source": "^(/.*)$",
      "target": "$1",
      "service": "html5-apps-repo-rt"
    }
  ]
}

Deploy/Redeploy

Note that during re-deploy the previous content is completely replaced by the new content. Currently there is no delta upload support.

In case you try to upload a large application (e.g.: > 20 MB), the cf healthcheck default timeout of 60 seconds might be reached. In such a case, cf will try to re-start the deployer which will lead to a new upload. For this new upload request, the HTML5 Application Repository design time will return a 409 response type with the message “deploy in process”. To solve this issue, you can increase the default cf healthcheck timeout to a maximum of 180 seconds or disable it. For more information, see cf health checks.

Deploy-Redeploy Content

Application Router – Approuter

The Application Router application is a node.js application that depends (via package.json) on the @sap/approuter module, which provides authentication, authorization and applications routing functionality.

A valid MTAR should contain a single Application Router which is used to handle the interaction with HTML5 Application Repository and all the relating Technical, Business and Backend Services.

The MTA Application Router dynamically serves HTML5 applications from HTML5 Application Repository and processes the corresponding routing information of the applications defined in the xs-app.json file, which is also stored in HTML5 Application Repository.

Application Router assumes that the first path segment contains an application key in the following format:

https://<approuterhost>/<businessServicePrefix>.<applicationName-applicationVersion>/<path to file>

• businessServicePrefix (optional): used in case the HTML5 Application is provided by a Business Service. It should match the sap.cloud.service attribute in Business Service credentials without the dots.
• applicationName (mandatory): It should match the manifest.json app.id without the dots.
• applicationVersion (optional): if no application version provided HTML5 Application Repository will return the latest version. It is use-full in case you want to keep more than one version in HTML5 Application Repository for backward compatibility reasons.

Routing functionality is supported in two levels:

1. On the HTML5 application level: supported by HTML5 App xs-app.json routing file
   Routes on this level are used to route requests to current HTML5 App static content and backend resources
2. On the Application Router level: supported by an xs-app.json routing file directly below the Application Router root folder
   Routes on the Application Router level are used to route requests to non HTML5 Application Repository resources. For example: SAP Cloud Analytics, external static content, etc.

During runtime the following routing flow takes place:

1. If businessServicePrefix exists, Application Router will fetch its app-host-id
2. Using appKey, Application Router tries to fetch the HTML5 application’s xs-app.json from HTML5 Application Repository.
3. If 404 is returned, this means that HTML5 Application Repository app does not contain an xs-app.json file and this is an error
4. If 503 is returned, this means that there is no such application and Application Router processes the request using a central xs-app.json.
5. If the request does not match any route in the central xs-app.sjon, 404 is returned

SAP Web IDE creates the Application Router module during the project creation. Developers should be able to configure non HTML5 Application dependent routes in the central xs-app.json. 

The Application Router is typically bound to the following services :

1. UAA – Authorization and authentication service
2. html-apps-repo runtime (app-runtime)– HTML5 Application Repository runtime, supports access to HTML5 applications stored in HTML5 Application Repository

Consuming HTML5 Application Content

SAP Fiori Launchpad – Portal Services

An SAP Fiori launchpad site is one of the site templates offered by SAP Cloud Platform Portal. A launchpad site displays a home page with tiles and links representing business applications that an end user can launch.

Adding an SAP Fiori launchpad site module to your project, adds a new folder under the mta project, containing the launchpad design time site. The design time site includes all content configuration files, e.g Content Data Model, and relevant translation files.

During deployment, the SAP Fiori launchpad site is created and activated in the project space.

Prerequisite:

Enable the SAP Fiori Launchpad Site feature in SAP Web IDE.

The module will be available in the MTA project, if the MTA project is set-up to use HTML5 Application Repository (a property setting defined in the project creation wizard):

Once the feature is enabled, you can create a SAP Fiori launchpad site module under the MTA:

Note that SAP Portal Services uses internally FLEX (flexibility service) which require a manifest-bundle.zip file. This file is usually generated by SAP Web IDE build process. If you don’t use SAP Web IDE to develop your business solution you must make sure that your build process generates this file. For that is it recommended to use the Multitarget Application Archive Builder.

For more information and how the get started see develop your first Fiori Launchpad Site

SAP Business Services

SAP Business Service describes a SAP concept on how to provide reusable Services on SAP Cloud Platform to accelerate Application Development. SAP Business Services follow some standard principles to ensure a harmonized and efficient consumption by consumers. The concept is implemented currently by SAP provided services only. However, SAP will provide in the near feature the underlying components to enable customer and partners as well to build and provide own Business Services in an efficient way.

As more and more SAP Business Services following these principles will be released over time we would like already to ensure that the consumption will work.

In the past SAP Business Services could only expose APIs for consumption by SaaS Applications. Based on the introduced HTML5 Application Repository and Application Router, SAP Business Services will be able to share UIs as well. This means Consumer SaaS Applications will be able to include Business Service UI into their Launchpad content.

Business Services sharing UIs need to provide the following information in there VCAP_SERVICES as a result of the binding process:

• sap.cloud.service: the name of the service as it appears in xs-app.json (for routing) and in manifest.json files. Note that the same name is used a business service prefix (without the dots).
• endpoints: an array of Business Service endpoints that can be used for routing in xs-app.json. If no endpoints provider Application Router will use the url attribute.
• html5-apps-repo.app-host-id: one or more html5-apps-repo app-host service instance guids separated by a comma. Should be provided if Business Service exposes HTML5 Applications.
• saasregistryenabled: must be provided if the Business Service should be returned as a dependency during the subscription flow.

Business Service Environment Variables in VCAP_SERVICES

"VCAP_SERVICES": {
  "com.sap.appbasic.countries": [
   {
     "html5-apps-repo": {
      "app_host_id": "c1f26930-77e2-4393-93b2-f09006b98b5e"
     },
     "uaa": {
         ....
      },
     “sap.cloud.service”: ”com.sap.appbasic.country”,
     "saasregistryenabled": true,   
     “endpoints": {
        "countryservice": "https://countriesapp.cf.hana.ondemand.com/odata/v2/countryservice"
      }
    },
    "instance_name": "countries",
    "name": "countries",
    "tags": [
     "countries“
    ],  
   }
  ],

Business Service Consumption Diagram

Sample Code

You can git clone this github example to see how to build a business application with native cf push functionality. Follow the steps in readme file and push it to your space.

Related Blogs

https://blogs.sap.com/2018/12/02/token-exchange-from-fiori-launchpad-flp-to-a-business-service-in-sap-cloud-foundry/

https://blogs.sap.com/2018/11/29/develop-a-full-stack-business-application-with-cap/