Technical Articles
Fiori Application Programming Model for Cloud Foundry and ABAP Cloud
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
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:
- Explicitly by using the cf create-service statement in CF CLI
- 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:
- 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 - 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:
- If businessServicePrefix exists, Application Router will fetch its app-host-id
- Using appKey, Application Router tries to fetch the HTML5 application’s xs-app.json from HTML5 Application Repository.
- If 404 is returned, this means that HTML5 Application Repository app does not contain an xs-app.json file and this is an error
- If 503 is returned, this means that there is no such application and Application Router processes the request using a central xs-app.json.
- 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 :
- UAA – Authorization and authentication service
- 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/11/29/develop-a-full-stack-business-application-with-cap/
Hi Sergio, thanks for this informative blog.
I wonder if you should add the tag applicationprogrammingmodel to your blog? That's one that DJ Adams has set up to group APM blogs
I would love to have a sample application on github that has a standalone app router and multiple html5 applications. Do you have anything suitable?
Hi Mike,
I've added the tag.
Creating a business application from SAP webIDE that leads to an mtar file that can be deployed to Cloud Foundry is quite straightforward, see here
I can create a simple example in public github that can be used with cf push. Is that OK?
Can you please fix the URLs that point to SAP internal web sites?
Hi Sergio Rozenszajn,
thank you for your very informative blog.
I have a question to the following part with the xs-app.js-file.
You are using html5-app-repo and the approuter and you have the destination property in here for your backend. I’ve read, that this is not supported in an mta with html5-app-repo. How did you get this running? I tried this on my own in an own application, but I always get an internal server error.
Source for not supported approuter properties in combination with html5 repo: https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/1e0424b4e1d8441ebb245c4d1e6bb0e5.html
What I'm trying to do is to implement a MTA with a html5 and a nodejs module, and later there should be a fiori launchpad site for the app(s) (which makes the html5 app repo mandatory). Can you tell me, how I can access my backend module then?
Best regards,
Paige
All types of destinations (from environment and destination service) are supported in approuter (with or without html5 repo)
Please check in approuter logs the reason for the internal error
Great blog and clear description of the different concepts / parts ... 🙂
I was wondering about the new HTML5 repo and FLP and how to structure our current non-HTML5 MTA.
We currently have 1 MTA which contains HDI, Node and 1 web folder - which holds a dozen UI5 apps in subfolders - they all use common resources like CSS, I18N and have common custom base controller classes, custom UI components, etc ... all that content is sitting in a common subfolder ( with further subfolders ).
Looking at the new model I would assume we would need to move all those apps in seperate HTML5 web app folders in order to be able to reference them as apps from the HTML5 repo and to have them as seperate tiles in FLP ... is this correct ? And if so ... how does one go about having some common resources ... ? Are those also deployed then as a seperate HTML5 app ? How would the referencing then happen ?
Thanks,
Steven
Yes, you can model common resources as own HTML5 Applications and manifest these relations in manifest.json file. If you use FLP the internally used FDC service will generate the so called "transitive closure" file that supports the internal re-use components loading.
If you need to re-use HTML5 Apps across orgs/spaces you have to define them as "public" and expose them as a business service.
Best Regards
Sergio
Thanks Sergio for your response 🙂
Would you have any link towards some documentation where I can find more info on filling in the manifest file for the above and the 'transitive closure' file ?
I tried already deploying a seperate HTML5 app with common resources before your response but when I used them then the generated URL didn't match as the resources where considered local to the consumer app ... prob due to the missing manifest config.
Thanks,
Steven
Hi Sergio,
The storage size seems no more bundled to the Application Runtime service quota, now :
1 Unit of app-host = 1 MB of storage
Correct?
Thank you,
Best Regards,
Sam
Hi Sergio.
Is it possible to overcome size limit/restriction of app-host service instance by any means so that we can deploy HTML5 module/content with more than 100 MB size to HTML5 Application Repository?
Thanks,
Ravindra
Hi Sergio,
Very informative blog.
Can you clarify following scenario a bit more..
We would like to setup multiple mta's.
One mta contains the fiori launchpad module.
Other mta's contain specific ui modules. So instead of including all ui's in the same mta of the flp, we would like to split them over multiple mta's.
Reading all kinds of documentation, this is not possible using the concept of 'cross mta' dependency. Correct?
SAP Business services seams the correct way to do it. But you mention SAP doesn't provide yet tools to build custom business services. What's the current state on this?Is there a way how we can make this work? Or is the only possible solution at the moment, one mta containing everything.
thanks
PV