Skip to Content

The following steps will explain how to provide multi-tenant web applications in an SAP Fiori Launchpad on SAP Cloud Platform Cloud Foundry. We will explain the necessary steps at the example of the application developed with the SAP S/4HANA Cloud SDK in the previous steps of this tutorial.

Note: This post is part of a series. For a complete overview visit the SAP S/4HANA Cloud SDK Overview.

Goal of this blog post

The SAP Fiori Launchpad provides a common entry point to SAP Fiori apps for all users. A Launchpad shell hosts SAP Fiori apps, makes them avaialble as tiles, and provides those apps with navigation, personalization, and other services.

This tutorial will cover how to create a Fiori Launchpad on SAP Cloud Platform Cloud Foundry similar to the screenshot below. The Launchpad will provide the Cost Center Explorer application as one tile that can be launched within the Launchpad. The Launchpad will be deployed on Cloud Foundry and refer to the application hosted on Cloud Foundry at run time. In order to create and configure the Launchpad, we will use the Portal Service on Cloud Platform Neo at design time.

We will describe how a provider of Cloud Platform applications can use the Launchpad to provide a unified entry point to his suite of applications for his customers. We will not consider the use case of a customer of different applications who wants to unify access to those applications on his self-created Launchpad. Stay tuned for updates on the latter use case in the future, once the corresponding functionality becomes available on SAP Cloud Platform Cloud Foundry.

Based on this use case of a single provider with many customers (that is, many tenants), the Launchpad will be multi-tenant: each customer (tenant) is served by the same application, and therein isolated from other tenants. While it is possible to have a dedicated Launchpad for a single tenant, Cloud native Software-as-a-service should be multi-tenant-enabled from the start, which is why we will focus on that scenario in the following.

The tutorial proceeds along the following sections:

  1. Subscribe to the Portal service on Neo
  2. Prepare the Fiori Launchpad in your Cloud Foundry account
  3. Create the Fiori Launchpad in the Portal service on Neo
  4. Configure the Fiori Launchpad
  5. Deploy the Fiori Launchpad to your Cloud Foundry account

Prerequisites

  • You have completed the tutorial step 4 (Call an OData Service).
  • You have completed the tutorial step 9 (Frontend Application) with the microservice approach.
  • You have created an SAP Cloud Platform Cloud Foundry (trial) account as explained in step 3 of this tutorial series and deployed the tutorial application to this account. That is, you have two separate applications in your Cloud Foundry space – one for the backend and a separate one for the frontend.
  • You have created an SAP Cloud Platform Neo (trial) account as for example explained at the beginning of step 2. The Neo account will only be used to access the Fiori Configuration Cockpit. You do not need to have developed or deployed any application on Neo.
  • Step 7 is optional (in fact, the Fiori Launchpad will replace the approuter introduced therein), but is highly recommended in order to protect your application properly and understand the security-related concepts mentioned in the following.

Subscribe to the Portal Service on Neo

The Portal service available on Cloud Platform Neo provides the design time environment to create SAP Fiori Launchpad sites. Enable it for your account on Neo as follows:

  1. Navigate to your Neo account (created in step 2) in the SAP Cloud Platform cockpit, which is typically called <yourUserID>trial. You can also click Go to Neo Trial on the Home page of the cockpit.
  2. In the menu pane on the right, choose Services.
  3. On the service overview page, look for the service called Portal and click on that tile.
  4. On the page for the Portal service, click Enable.
  5. Wait until the service has been enabled for your account.
  6. Click on the link Go to Service. This will launch the SAP Cloud Platform Portal service.
  7. Note down the URL, which will usually start with https://flpportal-<yourNeoAccount>.dispatcher.hanatrial.ondemand.com – the highlighted part of the hostname is the Portal application ID.

Now that you have subscribed to the Portal service on Neo you are ready to design your Launchpad site. As we want to later deploy this Launchpad to Cloud Foundry, we will first create a representation of that Launchpad in Cloud Foundry and return to the Portal service afterwards.

Prepare the Fiori Launchpad site on Cloud Foundry

The SAP Cloud Platform cockpit offers an easy access to Portal sites such as Launchpad sites from Cloud Foundry.

  1. Navigate to your Cloud Foundry account (created in step 3) in the SAP Cloud Platform cockpit, which is typically called <yourUserID>trial. You can also click Go to Cloud Foundry Trial on the Home page of the cockpit.
  2. Navigate to the trial subaccount and therein to the space dev where your backend and frontend application from the previous steps are deployed.
  3. In the menu pane on the right, choose Portal.
  4. Click on New Site. This will launch the dialog that allows us to create a new Portal site. This site will later be hosted in this Cloud Foundry account.
  5. Enter flp-tutorial as the name and a description for the site.
  6. Next, we have to specify the Neo account where we have subscribed to the Portal service in the previous section. Select the region of the Neo account – in this example based on the previous tutorials: Europe (Rot) – Trial – and enter the Portal application ID (visible in the URL of the Portal service, see above), e.g., flpportal-<yourNeoAccount>.
  7. Click on Create.

You should now see a tile representing the just created site that does not yet have any deployed content. The tile gives us a single place to access activities necessary for populating this site, which we will use in the following.

Create the Fiori Launchpad site

So far, we have only created a blank representation of the Launchpad site to-be on Cloud Foundry. Now we will design the actual Launchpad within the Portal service. The just created Portal tile in your Cloud Foundry account gives quick access to the site in the Portal service on Neo.

  1. Click on the edit icon (a pen sign) to navigate to the portal service.
    • Make sure that you don’t block the popup window. Alternatively, you should now also see the just created site if you navigate to the URL of the portal service directly.
  2. You should now see the Dashboard for your site in the Neo Portal service.

Each tile on the Fiori Launchpad will be modeled as an App in the site. We will now create two “apps”: first, the one for our Cost Center application, and second (optionally), a tile that links to an external web page.

Create the Cost Center app tile

From the Dashboard, navigate to the Apps section (part of the Content Management section) via the menu pane on the right. You should see an empty list of apps.

  1. Click on the add icon (a plus sign) to create a new app
  2. Enter the following properties for the new app:
    • App Title: e.g. Cost Center Explorer
    • Semantic Object: e.g. CostCenter
    • Action: e.g. Explore (Semantic object and action could later be used for navigating to your app from other apps within the Launchpad)
    • App Type: SAPUI5
    • Component URL: e.g. /sample (We will again use this value later when defining the route for the frontend destination, so make sure to keep it consistent. It is used to navigate to the frontend application within the shell.)
    • SAPUI5 Component: blog-tutorial (This value has to correspond to the project name used for the frontend application. It is used to locate the central UI5 component of your app. As such, it is also identical to the namespace of the Component.js file of the frontend application.)
  3. Switch to the Catalogs tab, select the checkmark next to Sample Catalog.
  4. Switch to the Groups tab, select the Sample Group.
    • You may first need to add this group to the list by clicking on the add icon, selecting the Sample Group, and clicking OK.
  5. Click Save.

You now have defined your first app that will appear as a tile in the Fiori Launchpad. We still need to configure the Launchpad so that it knows where to find the actual application and how to route requests made to the backend. We will do this in the next section. Before, you can experiment a bit with the visualization of your tile (for example, add an icon to the tile) and preview your Launchpad site using the Site preview icon (a monitor sign) in the top header. You may also want to add a simple tile that launches a URL as explained in the following subsection.

Create the URL tile (optional)

Create a new app similar to the steps above, but with the following properties:

Assign it to the same catalog and group and save the app.

Configure the Fiori Launchpad

So far, we have designed the tiles that appear on the Fiori Launchpad. We have not yet configured how the Launchpad deals with the UI5 app that we have configured. We need to configure this as part of the package that we will later deploy to Cloud Foundry.

  1. Navigate to Services and Tools by choosing the corresponding section in the menu pane on the right of the Portal service.
  2. On the Site Services overview, click on Package Deployer.

This will open the Package Deployer page where we now configure the components of the package as explained in the next subsections in the following order:

  1. xs-app.json: defines the route mapping to frontend and backend destinations on Cloud Foundry
  2. User Account and Authorization (UAA) service: you can either reuse the UAA service instance that you may have created as part of tutorial step 7, or create a new instance.
  3. mtad.yaml: this is the deployment descriptor for the deployment tool on Cloud Foundry. Here, we will define the actual destinations (URLs) of frontend and backend.

Configure xs-app.json

While creating the Cost Center Explorer app tile in the Launchpad, we have defined that the component for this app shall be located at the path /sample. Furthermore, the UI as implemented in step 9 will call our cost centers service at the path /costcenters.

Hence, we need to map source path /sample to the frontend and /costcenters to the backend destination. We will later define as part of the deployment descriptor where frontend and backend are actually located.

To define the route mapping, proceed as follows:

  1. On the Package Deployer page, click on the link xs-app.json to download the xs-app.json file and store it on your local computer.
  2. Open the downloaded file in a text editor and modify it by adding the two routes for frontend and backend. Including the route for themes that is already present in the downloaded file, the xs-app.json should look as follows after adding the two additional routes.
    {
    	"routes": [{
    		"localDir": "themes",
    		"source": "/themes/(.*)",
    		"cacheControl": "public, max-age=31536000,must-revalidate",
    		"target": "$1"
    	},
    	{
    		"source": "^/sample/(.*)",
    		"target": "$1",
    		"destination": "frontend"
    	},
    	{
    		"source": "^/costcenters",
    		"destination": "backend"
    	}]
    }​
  3. Upload the modified xs-app.json file to the Package Deployer page by clicking on the Upload button next to the xs-app.json file and selecting the file that you have just modified.

We have now defined that the Launchpad should route calls to /sample to the destination frontend and just pass on the path after /sample to the target ($1 refers to the first group of the regular expression in source). Calls to /costcenters shall be routed to backend. We will define the actual URL of the destinations as part of the mtad.yaml file below. Before, you need to define the UAA service instance for use as authentication service of your Launchpad site.

Configure UAA service

The User Account and Authentication (UAA) service deals with authentication and authorization of users. Please refer to step 7 of this tutorial series for a detailed explanation.

If you have already created your own instance of the UAA service in your Cloud Foundry space as explained in step 7, you can skip the next subsection and continue with the subsection “Configure UAA service instance for Launchpad” to use that instance for the Launchpad.

Create UAA service instance

If you have not yet created an instance of the UAA service in the space where you will deploy the Launchpad, proceed as follows:

  1. Create a file called xs-security.json in a folder of your choice. We will use this file to configure the UAA service instance. Put the following content into the file and provide a unique xsappname, for example by replacing <USERNAME> with your account name on SAP Cloud Platform Cloud Foundry (e.g. p1234567890trial). With this, we configure that the app will be multi-tenant (tenant-mode: shared) and define a scope and corresponding role-template to be used for authorization.
    {
      "xsappname": "firstapp-<USERNAME>",
      "tenant-mode": "shared",
      "scopes": [
        {
          "name": "$XSAPPNAME.Display",
          "description": "display"
        }
      ],
      "role-templates": [
        {
          "name": "Viewer",
          "description": "Required to view things in our solution",
          "scope-references"     : [
            "$XSAPPNAME.Display"
          ]
        }
      ]
    }​
  2. Run the following commands from your command line in the folder where you placed the xs-security.json file to create a service instance called myuaa and bind it to your backend application (here called firstapp), which you need to restart afterwards. Binding the instance to your backend is necessary to later include proper authorization in this setup.
    cf create-service xsuaa application myuaa -c xs-security.json
    cf bind-service firstapp myuaa
    cf restart firstapp

Configure UAA service instance for Launchpad

Afterwards, proceed as follows in both cases – reuse or newly created service instance:

  1. Click on the Edit button next to UAA Service Name.
  2. Enter the name of your service instance of the XSUAA service on SAP Cloud Platform Cloud Foundry: myuaa if you have followed the instructions above or in step 7.
  3. Click Save.

Configure mtad.yaml

Based on the previous subsections, we have now configured the Launchpad site (independent of the particular space where it will be deployed) and prepared the UAA service in your Cloud Foundry account. The deployment requires further information about the environment in which the Launchpad will be running, for example, where to find the abstract destinations mentioned in the routes of the xs-app.json file. The following figure illustrates the overall architecture of how the requests will be routed and which microservices are involved.

We will provide this and similar information in a file called mtad.yaml:

  1. On the Package Deployer page, click on the link mtad.yaml to download the mtad.yaml file and store it on your local computer.
  2. Open the downloaded file in a text editor to modify it as outlined in the following.
  3. Your Launchpad will have a specific identifier that is already appended to several names in the mtad.yaml file, for example, portal-site-9ba4f1e0-a9e6-11e7-9e2f-6b0f982f8dfd. We will refer to this identifier as <flpID> in the following. In your case, this should always be your specific identifier that you can see in the mtad.yaml file.
  4. Locate the section that defines the module site-entry and add a properties key with the TENANT_HOST_PATTERN as follows. Adapt the TENANT_HOST_PATTERN to the host of the Cloud Foundry region you will be deploying on; the below assumes “Europe – Frankfurt” (eu10).
      - name: site-entry-<flpID>
        type: javascript.nodejs
        path: site-entry/
        properties:
          TENANT_HOST_PATTERN: '(.*)-flp-tutorial.cfapps.eu10.hana.ondemand.com'
        parameters:
          memory: 256M​

    Make sure that properties is indented using spaces on the same level as the path and that the TENANT_HOST_PATTERN is indented by two additional spaces.

  5. Locate the requires list of the site-entry module and add the definition of two destinations tutorial-frontend and tutorial-backend to the end of this list:
      - name: site-entry-<flpID>
        ...
        requires:
          - name: tutorial-frontend
            group: destinations
            properties:
              name: frontend
              url: ~{url}
          - name: tutorial-backend
            group: destinations
            properties:
              name: backend
              url: ~{url}
              forwardAuthToken: true
          - name: site-host-<flpID>
          ...​

    Again, carefully align the indentation using spaces.

  6. Locate the section resources section at the end of the mtad.yaml file and add the two destinations at the end. Provide the URLs to your frontend (e.g., cost-center-frontend-USERNAME.cfapps.eu10.hana.ondemand.com) and backend application (e.g., firstapp-USERNAME.cfapps.eu10.hana.ondemand.com) deployed in the previous steps.
    resources:
      ...
      - name: tutorial-frontend
        properties:
          url: https://<URL-of-frontend>/
      - name: tutorial-backend
        properties:
          url: https://<URL-of-backend>/​
  7. You may want to check that the name of the service instance configured in the previous section appears in the resources section as value of the parameter service-name of the portal-uaa resource. Here, it is called myuaa as defined above:
      - name: portal-uaa
        type: org.cloudfoundry.existing-service
        parameters:
          service-name: myuaa​
  8. Upload the modified mtad.yaml file to the Package Deployer page by clicking on the Upload button next to the mtad.yaml file and selecting the file that you have just modified.
    • For your reference, you can find the complete mtad.yaml file of this example at the end of this blog post.
  9. Click on Download to download the Launchpad package and save the file with the extension .mtar on your local computer.

The .mtar file bundles both the Launchpad that we have defined (apps, catalogs, groups, …) and the additional configuration. Thus, it contains all required information to deploy our Launchpad site to Cloud Foundry, which we will do in the next section.

Deploy the Launchpad to Cloud Foundry

We have now completely configured the Fiori Launchpad and have a deployable .mtar file, so it’s time to deploy the site to our Cloud Foundry account. In the following, we explain how to deploy using the Cloud Platform Cockpit. Please note that there is also a command line tool available to deploy the so-called Multi Target Application (MTA). We explain the usage of the command line tool in the appendix of this blog post.

For the following, you only need the SAP Cloud Platform Cockpit web page.

  • Please make sure that you have at least 384 MB of free memory quota in your space – if you have previously done step 7, you may need to stop the approuter application at least during the deployment. The Fiori Launchpad will provide similar functionality as the approuter*. To stop an application, navigate to the Cloud Foundry space and click on the stop icon (a square within a circle) next to the application.
    • * In our setup we do not use a separate approuter for our application for the sake of simplicity. Placing an approuter between Launchpad and application components can still be beneficial to hide the inner mechanics of the application.
  1. Go to your Portal page in your Cloud Foundry space, where we initially created the representation for our Launchpad site in Cloud Foundry during the section “Prepare the Fiori Launchpad site on Cloud Foundry”.
  2. Click on the deploy icon (an upward pointing arrow sign) of the flp-tutorial tile we created in the second section of this tutorial.
  3. The dialog Deploy Portal Site appears with a field called Portal Site (*.mtar). Next to it, click on Browse… and select the .mtar file on your local file system that you have downloaded in the previous section.
  4. In the dialog, click OK.
  5. The deployment will take some time. Wait for the deployment to finish.
    • If you run into trouble while deploying, carefully check the setup described in the previous sections. Ahead of a new deployment, you need to delete the two applications created during the deployment (site-content-<flpID> and site-entry-<flpId>) and the two service instances (site-client-<flpID> and site-host<flpID>). To do so, navigate to the list of applications in your Cloud Foundry space and click on the delete icon (a trash bin sign). Do the same on the Service Instances overview page.
  6. Afterwards, we need to create a route to our Launchpad site that matches the TENANT_HOST_PATTERN configured above in the mtad.yaml file. Run the following command on your command line, replace <flpID> as explained above and <accountSubdomain> with the subdomain of the account that hosts the application (typically, something like p1234567890trial with your user name).
    cf map-route site-entry-<flpID> cfapps.eu10.hana.ondemand.com -n <accountSubdomain>-flp-tutorial​

    Note: with this, we essentially “subscribe” the hosting account to the application as the first tenant. With the same mechanism, it will be possible to add further routes for other tenants in the future. However, those tenants would need to be associated with the same UAA service instance, something which is only possible by manual intervention of SAP today. For testing purposes, using the hosting account in this way is sufficient.

    • With the above multi-tenant setup in place, you should now remove the ALLOW_MOCKED_AUTH_HEADER environment variable that you may have introduced in your backend application as part of Step 5 of this tutorial series. Execute the following command:
      cf unset-env firstapp ALLOW_MOCKED_AUTH_HEADER​
  7. The output of the command will include a response similar to the following. Take note of the route mentioned therein. You can access your Launchpad site using this route as the host name.
    Adding route <accountSubdomain>-flp-tutorial.cfapps.eu10.hana.ondemand.com to app ...​

After successful deployment, you need to access the just created route (e.g., https://<accountSubdomain>-flp-tutorial.cfapps.eu10.hana.ondemand.com/) to navigate to your new Fiori Launchpad site. You will be prompted for the e-mail address and password of the account you use for SAP Cloud Platform Cloud Foundry.

After the login screen, you will see the Launchpad. You can launch the Cost Center Explorer from the corresponding tile on the Launchpad.

Congratulations! You have integrated your app into the Fiori Launchpad, where it could now be accessible next to other apps, including navigation between apps. Users can benefit from a unified experience and enjoy the advantages of the SAP Fiori Launchpad, including the new features of the Launchpad in SAP Fiori 2.0 like the viewport concept, the Me and Notification area, and much more.

Stay tuned for upcoming blog posts about the SAP S/4HANA Cloud SDK. In the meantime, take the opportunity and experiment with the features of the SAP Fiori Launchpad or the SAP S/4HANA Cloud SDK. You can also read on in the appendix to understand how you can integrate authorization in the Launchpad setup or how to optimize your frontend layout for the Launchpad.

Appendix

Configure authorization

If you have followed step 7, your backend application will already be protected against unauthorized access and only allow users with the Display scope. It makes sense to apply the same authorization also on the level of the Fiori Launchpad. With the current configuration of the apps on our Launchpad site, users that do not have the authorization will still be able to launch the Cost Center Explorer app, but would then see an empty list of cost centers (assuming you require the Display scope for the /costcenters path).

  1. Go to the Portal service in your Neo account (see above).
  2. Navigate to the Apps list.
  3. Select the Cost Center Explorer app in the list.
  4. Click on Edit.
  5. Switch to the tab Scopes.
  6. Click on the add icon above the list of assigned scopes.
  7. In the Select Scopes dialog, you need to add a new scope with the name defined before in the xs-security.json file. Click on New.
  8. Enter $XSAPPNAME.Display as the Name and click OK.
  9. Select the checkbox next to the newly created scope and click OK.
  10. Click Save.
  11. Redeploy the app as outlined in the section “Deploy the Launchpad to Cloud Foundry”. Make sure that you remove the previously created artifacts as explained in that section.

Now, the Cost Center Explorer tile will only be shown to users that have the Display scope assigned to their roles in order  (see step 7 on how to assign this to your users). All others only see the URL tile (if you have created it for your site) or a blank Launchpad.

Optimize the frontend for the Launchpad

Previously, the frontend was a standalone application that had its own title. The launchpad displays a title in the shell above the app area. Hence, we can remove the header bar from the app itself and should supply a speaking title:

  1. Modify the file i18n/i18n.properties located in your webapp folder: set the appTitle property to an appropriate name, for example, Cost Center Explorer. This name will be shown in the shell bar above the app in the Launchpad.
  2. Modify the file view/View1.view.xml: add the attribute showHeader="false" to the Page element.

Deploy Launchpad site package via command line

Instead of using the Cloud Platform cockpit, you can also use the MTA plugin provided by SAP to deploy .mtar file via the command line. First, you need to install the MTA plugin by following the procedure outlined the help pages.

Afterwards, you can deploy the downloaded .mtar file via the following command (give the path to your .mtar file as the last parameter as shown below):

cf deploy SAP_downloaded_site_<flpID>.mtar

The deployment process will take some time and finish with the output “Process finished.” Now you can proceed with the remaining steps as explained above.

Complete mtad.yaml deployment descriptor file

For your reference, please find below the complete mtad.yaml file used in the instructions above. As mentioned, replace <flpID> with the identifier of your Launchpad site.

_schema-version: '2.0'
ID: portal-site-<flpID>
version: 1.2.0
modules:
  - name: site-entry-<flpID>
    type: javascript.nodejs
    path: site-entry/
    parameters:
      memory: 256M
    properties:
      TENANT_HOST_PATTERN: '(.*)-flp-tutorial.cfapps.sap.hana.ondemand.com'
    requires:
      - name: site-host-<flpID>
      - name: portal-uaa
      - name: sapui5-provider
        properties:
          sapui5url: '~{url}'
      - name: tutorial-frontend
        group: destinations
        properties:
          name: sample
          url: ~{url}
      - name: tutorial-backend
        group: destinations
        properties:
          name: backend
          url: ~{url}
          forwardAuthToken: true
  - name: site-content-<flpID>
    type: com.sap.portal.site-content
    path: site-content/
    parameters:
      health-check-type: none
      memory: 128M
    requires:
      - name: site-client-<flpID>
      - name: portal-uaa
resources:
  - name: site-host-<flpID>
    type: org.cloudfoundry.managed-service
    parameters:
      service: portal-services
      service-plan: site-host
      config:
        siteId: <flpID>
  - name: portal-uaa
    type: org.cloudfoundry.existing-service
    parameters:
      service-name: myuaa
  - name: sapui5-provider
    properties:
      url: 'https://sapui5.hana.ondemand.com'
  - name: site-client-<flpID>
    type: org.cloudfoundry.managed-service
    parameters:
      service: portal-services
      service-plan: site-content
      config:
        siteId: <flpID>
  - name: tutorial-frontend
    properties:
      url: https://<URL-of-frontend>/
  - name: tutorial-backend
    properties:
      url: https://<URL-of-backend>/
To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply