Skip to Content
Technical Articles
Author's profile photo Matthias Schmalz

Designing UI5 Apps for SAP Launchpad Service – Part 2

Content Navigation

Part 1: A simple UI5 app that runs in the SAP Launchpad Service

Part 2: Multiple Apps with a Shared Reuse Library (Current page)

Part 3: Splitting bigger projects

Multiple Apps with a Shared Reuse Library

In part 1 you have learned how to build and deploy a single app. In this 2nd part this is now extended to multiple apps that share a reuse library with common code.
The library contains a control as well as a reuse component.

The sample code can be found in the GitHub repository.

Deployed Content

Let’s have a look at how the deployment looks now and what has changed. The needed service instances haven’t changed at all, but more HTML5 apps are now deployed to the same app host:

Both apps depend on the reuse library, which is expressed in their manifest.json file under sap.ui5/dependencies. The reuse library contains an embedded manifest.json for the component.

MTA Project Structure

The mta.yaml of the project has been enhanced slightly. Two more modules for the 2nd app and the library are added and they are linked to the UI deployer module:

The UI5 Library

The library only contains the bare minimum to demonstrate relevant aspects. Here it contains a sample reusable control and an embedded reusable component. Of course there could also be other reusable content like base classes, etc.

Build

The UI5 library is also built with UI5 Tooling. The build is controlled the same way as the apps via the package.json and the ui5-deploy.yaml.
In the ui5-deploy.yaml and the manifest.json the type is now set to library.

For libraries the builder requires a different project structure. Instead of a webapp folder there must be a folder structure starting with src and followed by the library namespace that contains the source files. Example: src/btp/samples/multiple/apps/lib.

Instead of a Component.js file the library contains the files library.js and .library to define the library metadata.

The build produces a library-preload.js file that packages all minified files including the sources of the reuse component. No dedicated Component-preload.js is produced.

Routings

The xs-app.json file only contains a route to serve its own sources.
This lib doesn’t use an own OData service, but this would be possible for the embedded component. In that case you would have to create a corresponding route here.

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

The lib doesn’t need to be started standalone and therefore has no ui5.yaml with a local middleware.
Note that if you want to build unit test pages for the library you might need a local test environment for it as well in the same way as for the apps.

App Descriptor

It has a manifest.json file that defines a unique sap.app/id and the sap.app/type library for it. There are no inbounds and no services defined, but the embeds property lists the subfolder of the embedded reuse component

"sap.app": {
    "id": "btp.samples.multiple.apps.lib",
    "type": "library",
    "i18n": "i18n/i18n.properties",
    "title": "{{title}}",
    "applicationVersion": {
        "version": "1.0.0"
    },
    "embeds":["comp/reuse"]
}

It also specifies sap.cloud/service with the same service name as for the apps. This way it will also be bound to the single XSUAA instance.

"sap.cloud": {
    "public": true,
    "service": "btp.samples.multiple.apps"
}

The Embedded Component

The component is located in the comp/reuse subfolder. It is kept simple and only contains a Main view that renders a simple button in the Main.view.xml file. It doesn’t declare any models or use any OData services but this would be possible in the same way as for an application.

The manifest.json defines type as component and an ID which is constructed including the parent library ID and the relative path inside. This is needed to avoid any issues with module path resolution.
It declares the embeddedBy property with the path to the embedding library. This is an important indicator for the platform that the preload package of the component is part of the library preload package. Without it, there might be an unnecessary request at startup which ends with a 404 Not Found error.

{
    "_version": "1.32.0",
    "sap.app": {
        "id": "btp.samples.multiple.apps.lib.comp.reuse",
        "type": "component",
        "i18n": "i18n/i18n.properties",
        "title": "{{appTitle}}",
        "description": "{{appDescription}}",
        "applicationVersion": {
            "version": "1.0.0"
        },
        "embeddedBy": "../../"
    }
}

There is no need to specify the sap.cloud node here. This will be inherited from the manifest.json of the lib.

The UI5 Apps

For the apps (app1 and app2) there are only small changes.

In the manifest.json of the first app the dependency to the library has been added.

"sap.ui5": {
    "dependencies": {
        "minUI5Version": "1.95.0",
        "libs": {
            "sap.ui.core": {},
            "sap.m": {},
            "sap.f": {},
            "btp.samples.multiple.apps.lib": {}
        }
    }
}

There are no resourceRoots URLs defined here, because these depend on the way how the apps are started. 

 

The Master.view.xml uses the library by adding the Reuse control.

<mvc:View
	controllerName="btp.samples.multiple.apps.app1.controller.Master"
	xmlns="sap.m"
	xmlns:semantic="sap.f.semantic"
	xmlns:mvc="sap.ui.core.mvc"
    xmlns:lib="btp.samples.multiple.apps.lib">

            <!-- Reuse control from shared lib -->
            <lib:controls.Reuse text="App1" />

</mvc:View>

 

In the manifest.json of the 2nd app there is also a component usage for the reuse component.

    "sap.ui5": {
        "dependencies": {
            "minUI5Version": "1.95.0",
            "libs": {
                "sap.ui.core": {},
                "sap.m": {},
                "sap.f": {},
                "btp.samples.multiple.apps.lib": {}
            }
        },
        "componentUsages": {
            "resuse": {
                "name": "btp.samples.multiple.apps.lib.comp.reuse",
                "settings": {},
                "componentData": {},
                "lazy": false
            }
        }
}

 

In the Master.view.xml there is a component container that shows the component usage.

<mvc:View
	controllerName="btp.samples.multiple.apps.app2.controller.Master"
	xmlns="sap.m"
	xmlns:semantic="sap.f.semantic"
	xmlns:core="sap.ui.core"
    xmlns:mvc="sap.ui.core.mvc"
    xmlns:lib="btp.samples.multiple.apps.lib">
        <semantic:titleContent>
            <Image id="titleImage" />
            <!-- Reuse control from shared lib -->
            <lib:controls.Reuse text="App2" />
            <core:ComponentContainer usage="resuse" manifest="true" async="true" />
        </semantic:titleContent>
</mvc:View>

Routings

The xs-app.json files of the apps haven’t changed. There is no route for the library added because the library will be accessed directly and not via the apps.

However the ui5.yaml files that define the server for the local run have been enhanced.
They define the entire isolated test environment for an app and therefore also need a route mapping for the static sources of the lib.

server:
  customMiddleware:
  - name: fiori-tools-servestatic
    afterMiddleware: compression
    configuration:
      paths:
        - path: /btpsamplesmultipleapps.btpsamplesmultipleappslib
          src: "../lib/src/btp/samples/multiple/apps/lib"

Again to start the local test just run the start or start-local script in one of the package.json files.

Running the Deployed Apps

Deploying the App

Build and deploy the single MTA project in the same way as before.

Running Standalone

After the deployment the apps can be run standalone from their index.html via the managed approuter. Again you can find them in the SAP BTP cockpit on the HTML5 Applications page under your subaccount.

The index.html need to define a resource mapping for the library to tell UI5 where to find the resources. Unfortunately this can’t be hardcoded here, because of the destination guid which is a part of the URL. The guid and the service name are the same as for the index.html but the library ID is at the end.

 

Since there is no way to specify this as a relative URL, there is a small piece of code to calculate it:

<script id="sap-ui-bootstrap"
	src="https://ui5.sap.com/resources/sap-ui-cachebuster/sap-ui-core.js"
	data-sap-ui-theme="sap_fiori_3"
	data-sap-ui-resourceroots='{
		"btp.samples.multiple.apps.app1": "./"
	}'
        data-sap-ui-libraries="sap.m"
        data-sap-ui-oninit="module:sap/ui/core/ComponentSupport"
		data-sap-ui-compatVersion="edge"
		data-sap-ui-async="true"
		data-sap-ui-preload="async"
		data-sap-ui-frameOptions="trusted">
</script>
<script>
    let parts = window.location.pathname.split('/');
    let destinationGuid = (parts.length > 2) ?  parts[1].split(".")[0] + "." : "";
    sap.ui.loader.config({paths:{"btp/samples/multiple/apps/lib": `/${destinationGuid}btpsamplesmultipleapps.btpsamplesmultipleappslib`}});
</script>

The script also contains a condition to support the local run. Here the paths are also different, and a different relative path is needed.

Running in the Launchpad Service

To run the apps in the launchpad, synchronize the html5 provider in the launchpad configuration and configure the apps. Afterwards you can run the new apps in a similar way as before.
Here the platform will provide the URLs to access the apps and the library.

If you check the ui5AppInfo.json that is used to start the app you can find the additional dependencies for the library. The reuse component doesn’t appear here, because it is embedded in the library and all paths can be derived from it.

{
  "name": "btp.samples.multiple.apps.app2",
  "url": "/b7f4982c-02d4-4c24-a4f6-5f23ff2f8aef.btpsamplesmultipleapps.btpsamplesmultipleappsapp2/~060222132517+0000~/",
  "manifest": true,
  "asyncHints": {
    "libs": [
      {
        "name": "sap.m",
        "lazy": false
      },
      {
        "name": "btp.samples.multiple.apps.lib",
        "url": {
          "url": "/b7f4982c-02d4-4c24-a4f6-5f23ff2f8aef.btpsamplesmultipleapps.btpsamplesmultipleappslib/~060222132517+0000~/",
          "final": true
        },
        "lazy": false
      },
      {
        "name": "sap.f",
        "lazy": false
      },
      {
        "name": "sap.ui.fl",
        "lazy": false
      }
    ],
    "components": []
  },
  "messages": [],
  "version": "1.0.0"
}

Next Steps

Now you are ready to build multiple apps and move common parts of them into a reusable library.
However, everything is still contained in the same MTA project. In bigger projects, you might need to split this into smaller parts in order to achieve independent lifecycles and split responsibilities.
Please check out Part 3 of this blog for this.

Assigned Tags

      23 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi all,

      Part 3 has now been published as well.

      Best regards
      Matthias

      Author's profile photo Arvin Li
      Arvin Li

      Hi Matthias,

      How to configure the library in the local launchpad site?

      Best Regards,

      Arvin

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi Arvin,

      thank you for the question.
      I have enhanced the samples and added the missing files the the start-local scripts to run the local launchpad. The test/flpSandbox.html file also contains the resource mapping for the library. Since this is only used for testing from the workspace, the paths could be hardcoded here.

      Best regards
      Matthias

      Author's profile photo Asia Shaikh
      Asia Shaikh

      Hi,
      I have followed the steps and added the app on BTP cloud portal.The reusable UI is seen but its related CSS ,i18n and Odata services are going into SDK resource path and getting following error:

      https://sapui5.hana.ondemand.com/1.100.0/resources/com/test/testapp/css/style.css

      regards,
      Asia

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi Asia,

      where and how do you specify the URLs for these resources?
      For paths in the manifest.json it is important to always use relative links. They must not contain a host name and must not have a leading /
      If you calculate URLs in the source code, the final path has to be resolved relative to the app (see the mentioned sample for an image in part 1).

      However in your case it seems like UI5 resolves a resource path based on an unknown namespace and therefore points to the UI5 dist layer resources.
      Please verify the the sap.app/id in the manifest.json fits to the used module names. In your sample the id should be "com.test.testapp".

      Best regards

      Matthias

      Author's profile photo Asia Shaikh
      Asia Shaikh

      Hi Matthias,

       

      Its correct, com.test.testapp is app id.I am not specifying the hardcoded path.

       

      regards,

      Asia

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi Asia,

      so where have you entered the URLs and what is the exact value?

      Best regards
      Matthias

      Author's profile photo Asia Shaikh
      Asia Shaikh

      Hi Matthias,

      I am not defining urls.

      CSS ,i18 and datasource i defined in manifest.json.

      Can i manually harcode my portal site url somewhere in manifest,mta.yaml to make it work?

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi Asia,
      what you enter in the manifest.json is also an URL, but you would provide a relative one.
      So which value have to entered there?
      Regards Matthias

      Author's profile photo Asia Shaikh
      Asia Shaikh

      Hi Matthias,

      i have not entered any url , just defined view,models, css,datasource,but when i am using reuse component those resourcepath is going into https:sapui5.hana.../sap/opu/sap/odata/...instead of portal site ..https:myportalsite/sap/opu/sap/odata...

      regards,

      Asia Shaikh

      Author's profile photo Asia Shaikh
      Asia Shaikh

      Hi Matthias,

      datasource,css,model is taking https:sapui5.hana../sap/odata/opu/sap/ztestservice instead of https://myportalsite/testservice.testapp/sap/odata/opu/sap/ztestservice

      regards,

      Asia

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      I meant which values have you entered in the manifest?

      Author's profile photo Asia Shaikh
      Asia Shaikh

      Please find below manifest entry:

       

      {
          "_version": "1.32.0",
          "sap.app": {
            "id": "com.umusic.invoicecreditnote",
            "type": "application",
            "i18n": "i18n/i18n.properties",
            "applicationVersion": {
              "version": "0.0.1"
            },
            "title": "{{appTitle}}",
            "description": "{{appDescription}}",
            "dataSources": {
              "mainService": {
                "uri": "/sap/opu/odata/sap/Z_U3INVOICE_BND/",
                "type": "OData",
                "settings": {
                  "odataVersion": "2.0",
                  "localUri": "localService/metadata.xml"
                }
              },
              "testserv": {
                "uri": "/sap/opu/odata/sap/ZUNP_UI_ZSUPPLR_B/",
                "type": "OData",
                "settings": {
                  "odataVersion": "2.0",
                  "localUri": "localService/metadata.xml"
                }
              }
            },
            "crossNavigation": {
              "inbounds": {
                "com-umusic-invoicecreditnote-inbound": {
                  "signature": {
                    "parameters": {},
                    "additionalParameters": "allowed"
                  },
                  "semanticObject": "so_invoicecreditnote",
                  "action": "display",
                  "title": "{{flpTitle}}",
                  "subTitle": "{{flpSubtitle}}",
                  "icon": ""
                }
              }
            }
          },
          "sap.ui": {
            "technology": "UI5",
            "icons": {
              "icon": "",
              "favIcon": "",
              "phone": "",
              "phone@2": "",
              "tablet": "",
              "tablet@2": ""
            },
            "deviceTypes": {
              "desktop": true,
              "tablet": true,
              "phone": true
            }
          },
          "sap.ui5": {
            "flexEnabled": false,
            "dependencies": {
              "minUI5Version": "1.97.2",
              "libs": {
                "sap.ui.core": {},
                "sap.m": {},
                "sap.ui.comp": {},
                "sap.ui.table": {},
                "sap.ui.unified": {},
                "sap.ui.layout": {
                    "lazy": true
                },
                "sap.f": {}
            }
            },
            "contentDensities": {
              "compact": true,
              "cozy": true
            },
            "models": {
              "i18n": {
                "type": "sap.ui.model.resource.ResourceModel",
                "settings": {
                  "bundleName": "com.umusic.invoicecreditnote.i18n.i18n"
                }
              },
              "": {
                "dataSource": "mainService",
                "preload": true,
                "settings": {
                  "defaultBindingMode": "TwoWay",
                  "defaultCountMode": "Inline",
                  "refreshAfterChange": false
                }
              },
              "testservModel": {
                "dataSource":"testserv",
              "preload": true,
              "settings": {
                "defaultBindingMode": "TwoWay",
                "defaultCountMode": "Inline",
                "refreshAfterChange": false
              }
            }
            },
            "resources": {
              "css": [
                {
                  "uri": "css/style.css"
                }
              ]
            },
            "routing": {
              "config": {
                "routerClass": "sap.m.routing.Router",
                "viewType": "XML",
                "async": true,
                "viewPath": "com.umusic.invoicecreditnote.view",
                "controlAggregation": "pages",
                "controlId": "Invapp",
                "clearControlAggregation": false
              },
              "routes": [
                {
                  "name": "Route_DispInvoice",
                  "pattern": "",
                  "target": [
                    "TargetDispInvoice"
                  ]
                },
                {
                  "name": "Routeinvoicecreditnote",
                  "pattern": "{Belnr}",
                  "target": [
                    "Targetinvoicecreditnote"
                  ]
                }
              ],
              "targets": {
                "TargetDispInvoice": {
                  "viewType": "XML",
                  "transition": "slide",
                  "clearControlAggregation": false,
                  "viewId": "DisplayInvoice",
                  "viewName": "DisplayInvoice"
                },
                "Targetinvoicecreditnote": {
                  "viewType": "XML",
                  "transition": "slide",
                  "clearControlAggregation": false,
                  "viewId": "invoicecreditnote",
                  "viewName": "invoicecreditnote"
                }
              }
            },
            "rootView": {
              "viewName": "com.umusic.invoicecreditnote.view.App",
              "type": "XML",
              "async": true
            }
          },
          "sap.cloud": {
            "public": true,
            "service": "invoicecreditnote.services"
          }
        }
      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi Asia,
      at least there is a problem with the OData URLs e.g.
      /sap/opu/odata/sap/Z_U3INVOICE_BND/
      This has a leading slash which only works on ABAP platform but on CF this must be removed i.e.
      sap/opu/odata/sap/Z_U3INVOICE_BND/
      Otherwise it will not resolve correctly.

      The css and i18n urls and module names look correct and should work.
      At least they do not match your first sample which tried to access
      https://sapui5.hana.ondemand.com/1.100.0/resources/com/test/testapp/css/style.css
      This must be caused by a different app.

      Regards Matthias

      Author's profile photo Lidia Sarasua
      Lidia Sarasua

      Hi Matthias,

      Thank you very much for such detailed post.

      This example contains all three "projects" (app1, app2 and library) within one single git repository and they are all built together within a single MTA to be deployed at once.

      Would it be possible to achieve the same functionalities with the projects split in 3 different repositories? (one each)

      And would it be possible to build and deploy them separately as well?

      This would be very beneficial if  there are many apps and different teams working on them (e.g. if I only want to make changes in the library, it'd be good if I could just build the library alone and deploy it without all the other apps, same for the other individual apps)

      Best regards,

      Lidia

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi Lidia,

      please check out part 3 of the blog. This shows how to split into multiple MTAs which can be deployed independently.

      My samples all reside in one single Github repository but this is a simplification I have done and not needed. Usually you would split each MTA project into an own Github repository.

      Best regards
      Matthias

      Author's profile photo Jyotsna Singam
      Jyotsna Singam

      Hi Matthias,

      Thank you for the wonderful blog! We have a scenario where we aren't using destination content module and Launchpad service. Our destination, xsuaa and required services are bound to standalone app router. Is destination content module mandatory for having resuable libraries? How does it work in case of standalone app router? Kindly, help with your inputs.

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi Jyotsna,

      it depends on whether you are using the Portal service as well and are binding this to your app router in order to render a launchpad.
      In this case the Portal service provides similar functionalities. The rules are quite similar in this case, but instead of service destinations you have to bind the html5 repo and xsuaa instances to your app router and the FLP content deployer. However this is outside the scope of this blog.

      In case you are not using Portal at all, you are on your own.
      In this case you have to calculate runtime URLs to bind your reuse libs to your apps on your own.

      Best regards
      Matthias

      Author's profile photo Matheus Brasil
      Matheus Brasil

      Hello Matthias Schmalz ,

      thank you for your blog. It is really helpful.

       

      I would like to understand how we can reference the URL of the library when the UUID/GUID is generated dynamically in each of the environments that we will deploy.

            {
              "name": "btp.samples.multiple.apps.lib",
              "url": {
                "url": "/b7f4982c-02d4-4c24-a4f6-5f23ff2f8aef.btpsamplesmultipleapps.btpsamplesmultipleappslib/~060222132517+0000~/",
                "final": true
              },
              "lazy": false
            }

       

      I know if the MTA file is changed from INSTANCE to SUBACCOUNT the library will be deployed without the UUID/GUID but how it can impact if we change from a single tenancy to a multi-tenancy environment?

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hello Matheus,

      the GUID is bound to the instance of the destination service that is created by the MTA. As long as the same instance is used the GUID will be stable.
      The GUID only changes if the instance changes e.g. if it is deleted and recreated or if you deploy to another environment (landscape, sub account, ...).
      When switching to multi-tenancy this should not affect the GUID. Only the hostname would change because the tenant subdomain would be added.

      Anyway it is not recommended to hardcode it. Always calculate it dynamically as shown in the code samples above or rely on the platform to inject it.

      Best regards
      Matthias

      Author's profile photo Matheus Brasil
      Matheus Brasil

      Hello Matthias!
      Thank you for your reply.

      The point is I'm trying to use the resourceRoots to assign the library to my main app but if I use the path without the GUID it does not work.

       

              "resourceRoots": {
                  "btp.samples.multiple.apps.lib": "/btpsamplesmultipleapps.btpsamplemultipleappslib/"
              }

       

      Since I'm working with different apps with different MTA, each app deployment creates a new GUID to be part of the path. The logic you provided to get the GUID just works when the apps share the same GUID. I wonder if there is a better way to assign the library using the resourceRoot than the following one:

              "resourceRoots": {
                  "btp.samples.multiple.apps.lib": "/b7f4982c-02d4-4c24-a4f6-5f23ff2f8aef.btpsamplesmultipleapps.btpsamplesmultipleappslib/"
              }

       

      Or are the resourceRoots not necessary for apps that run inside of the Launchpad?

       

       

       

      Thank you for your time,

      BR,
      Matheus Brasil.

      Author's profile photo Matthias Schmalz
      Matthias Schmalz
      Blog Post Author

      Hi Matheus,

      The resourceRoots in the manifest.json are an alternative way, but they are static and you can't calculate the GUIDs here. Therefore it won't work this way.

      Please read the blog post above. It explains how the platform injects the resource roots automatically (Running in the Launchpad Service) and how to calculate it in your index.html (Running Standalone).

      For your scenario with multiple MTAs please refer to part 3 of the blog. It explains how to split projects with shared libraries into multiple MTAs. In the end you will have just one instance of destination service with one common GUID.

      Best regards
      Matthias

      Author's profile photo Matheus Brasil
      Matheus Brasil

      Thank you Matthias Schmalz !
      I'll follow your guidance!

      BR,

      Matheus Brasil.