Simplifying HTML5 Content Consumption Across Subac...

rupambhatta · ‎07-15-2024

Introduction

Motivation

Historically, HTML5 solutions deployed within SAP BTP were confined to their respective HTML5 repositories, accessible only from Work Zone instances subscribed to the same subaccount. This presented a challenge for organizations needing to share HTML5 content across multiple subaccounts. The manual process to achieve this was tedious and differed significantly from the straightforward content provider based integration available with other federated sources like SAP S/4 HANA.

High-level overview (TL;DR)

The newly introduced feature in SAP Build Work Zone allows the creation of Content Providers out of HTML5 business solutions deployed in a provider subaccount. These Content Providers can now be accessed from any other subaccount that shares the same identity provider. This is achieved by including Work Zone content definition in CDM format within the business solution (MTA) and deploying to BTP and using this exposed CDM definition from provider account from other consumer subaccount via destinations. The design-time destination is utilized to read the Work Zone content definition from the provider subaccount, while the runtime destination routes end-user access to applications contained in the business solution to the provider host via a managed AppRouter.

Most important prerequisite is that both provider and consumer subaccount should be connected to the same IDP.

Let us unpack the concept of Business Solution and CDM -

Business Solution

Before we discuss the details, we must understand the concept of Business Solution which is often represented as Multi Target Application (MTA) on Cloud Foundry environment which may contain modules like server side code, DB definition and One or More UI Apps. This modular approach allows for the deployment and management of complex business solutions within the platform that is the sum of individual parts & UI apps solving the specific sub-problems of a business scenario. The idea of HTML5 content consumption across subaccount is based upon this notion of business solution (or MTA as a whole in Cloud Foundry environment) rather than working with individual UI applications.

Common Data Model or CDM

The Work Zone content definition is defined in the Common Data Model (CDM) format defined here, which is a standardized structure for defining business content for SAP Build Work Zone, including roles, groups, catalogs, spaces, and pages. To enable the business solution to be consumed as a content provider in Work Zone, developers must include CDM definitions in their MTA projects.

Let us now dive into the details

Developer Flow

Prerequisites

Before starting, ensure you have:

An SAP BTP account with the necessary permissions to deploy apps - we will call this the provider subaccount.
Access to developer tools like Business Application Studio or SAP Build Code or knowledge of CF CLI to manage MTA build and CF deployment.

Step 1: Develop Multi-target Application (MTA) with one or more UI Application

You can either develop a new MTA project or use an existing single-tenant managed AppRouter based MTA project with HTML5 applications. If you are new to building UI application and deploying them as MTA project, you can learn more about it here.

Conversely, you may clone Manage Products sample project from github which is also referred in rest of this blog as example code snippets / screenshots. This is a simple MTA project "manageproductscdm" with 1 sample UI5 application "products" that connects to generic Northwind data service and show a list of products. Currently only UI5 apps are supported.

Step 2: Include sap.cloud.service definition in UI App manifest

sap.cloud.service definition in UI app manifest defines the business solution to which they belong. Hence, it is required to include this in the manifest.json of every UI application in the MTA. This is included as root property 'sap.cloud' in the manifest json. Code link in sample project

"sap.cloud": {
    "public": true,
    "service": "manageproductscdm"
}

Step 3: Define Work Zone content in CDM json in workzone folder under MTA project

This file should include the design-time definitions of your business content, such as roles, groups, catalogs, spaces, pages, etc. While creating your own cdm.json refer to the documentation here to understand more about the different supported entities in CDM v3.2 and how to construct the json objects for these entities.

In the sample the cdm.json file is added to the workzone folder which is a recommended best practice but not mandatory. If you choose any other folder name, the build script to copy the cdm.json to the resources folder needs to be also adjusted accordingly.

For simplicity the cdm.json in the sample application is created with group & catalog mode display and contains the entities shown in the table below. Observe the common properties like id, title, entitytype and payload for each entity json object. Once you understand the content structure, it would be easy to define for your own MTA and business solution content.

[Optional] 1 catalog (to display in AppFinder at runtime) with id "manageProductCatalogId" and has the UI app "products" included in it's payload.
The "texts" portion is for providing locale specific title text that will show up in the AppFinder against this catalog. (link to sample github code)

[Optional] 1 Group (to aggregate semantically similar apps in the site at runtime) with id "manageProductGroupID" and has the UI app "products" included in it's payload. Which means the Products app tile will be shown under group title when the end-user accesses the site at runtime. Similar to Catalog example above, "texts" part is to provide localized texts for the group title. (link to sample github code)

[Mandatory] 1 Role (to determine which users can use this content in runtime) with id "manageProductRole" and has the catalog, group and the app "products" assigned to it via "payload" section. At runtime, the user will have access to all the content in it's payload if the user has this specific role assigned. When the content provider is created in consumer WZ instance, if admin selects "Automatically add all content items to subaccount" option, a corresponding platform role collection is generated in the BTP subaccount which can then be assigned to the user as usual BTP role assignment process. More details below in the admin section & can also be found here. (link to sample github code)

Step 4: Add build script to mta.yaml to copy cdm.json to resources folder

In mta.yaml, under "build-parameters" (link to sample github code), add the following script which would run at mta build and copy the cdm.json to the resources folder. This will then be visible to the HTML5 repo instance and enable it to serve it as a CDM endpoint for content provider creation.

before-all:
    - builder: custom
    # CDM copy to resources folder #################################
      commands:
        - mkdir -p resources
        - cp workzone/cdm.json resources/cdm.json
    ################################################################

Step 5: Update mta.yaml with DT and RT destinations [Optional]

Generating the destinations on the provider account on deployment is very convenient as compared to manually creating them. Even though we need to export this destination from provider subaccount cockpit and import it in the consumer subaccount (also make some minor modifications), it is still worth it. But, please note that this is not a mandatory as admins can always create these destinations manually in the BTP cockpit.

If you are not familiar with destinations on SAP BTP, this tutorial is a good starting point.

Let's start with Designtime or DT destination, which is used by the consumer WZ instance to reach the cdm definition hosted by the HTML5 repo in the provider account (which is based on the cdm.json we just created in step 3).

For this, we will add a destination deployer module in the mta.yaml as shown in this code below (link to sample github code) -

Please note the URL format of the destination - it ends with the /applications/cdm/<sap.cloud.service>.
In this example, the sap.cloud.service name is manageproducts (see developer step no. 2 above) and hence the url format in the code snippet below.

# Destination deployer module - create CDM DT destination ##########
- name: manageproductscdm-destination-content
  type: com.sap.application.content
  requires:
  - name: manageproductscdm-destination-service
    parameters:
      content-target: true
  - name: manageproductscdm_html_repo_runtime
    parameters:
      service-key:
         name: manageproductscdm-html5-app-runtime-key
  - name: uaa_manageproductscdm
    parameters:
      service-key:
        name: uaa_manageproductscdm-key
  parameters:
    content:
      subaccount:
        destinations:
        - Name: manageproducstcdm_cdm
          ServiceInstanceName: manageproductscdm-html5-app-runtime-service
          ServiceKeyName: manageproductscdm-html5-app-runtime-key
          URL: https://html5-apps-repo-rt.${default-domain}/applications/cdm/manageproductscdm
        existing_destinations_policy: update
  build-parameters:
    no-source: true
#######################################################################

Once this is created, we add a HTML5 app-runtime resource for CDM DT destination under the resources section in the mta.yaml as shown below (link to sample github code) -

# HTML5 app-runtime resource for CDM DT destination ######################
- name: manageproductscdm_html_repo_runtime
  type: org.cloudfoundry.managed-service
  parameters:
    service: html5-apps-repo
    service-name: manageproductscdm-html5-app-runtime-service
    service-plan: app-runtime
###################################################################

Now let's move to the Runtime or RT destination We will add the destination resource which will generate the RT destination on deployment on the provider account that would point to the provider Work Zone managed AppRouter and end-user accessing any application at runtime would be routed to this url.

Add the following code and if you are already aware of the provider work zone URL (easiest way is to launch the Work Zone site in the provider account and copy the base url), you can already add this to the mta.yaml such that you don't need to manually change it after deployment. (link to sample github code)

# Destination resource for CDM RT destination #######################
- name: manageproductscdm-destination-service
  type: org.cloudfoundry.managed-service
  parameters:
    config:
      HTML5Runtime_enabled: false
      init_data:
        subaccount:
          destinations:
          - Authentication: NoAuthentication
            Name: manageproductscdm-rt
            ProxyType: Internet
            Type: HTTP
# Place holder URL. Must replace with actual provider Work Zone URL #
            URL: https://<subdomain>.<type>.cfapps.<region>.hana.ondemand.com
#####################################################################
          existing_destinations_policy: update
      version: 1.0.0
    service: destination
    service-name: manageproductscdm-destination-service
    service-plan: lite
#####################################################################

Step 6: Deploy MTAR to the provider subaccount

This is standard deployment flow of MTAR project. This tutorial can help if you need to learn the flow.

Post this deployment, you should see the app listed under HTML5 Applications in the Provider subaccount BTP cockpit.

Also, the DT and RT destinations in the provider subaccount BTP cockpit, that were created based on the mta.yaml declarations of module and resources for it.

Let us now move the administrator specific tasks for this scenario.

Admin Flow

Prerequisite

Provider and consumer subaccounts have SAP Build Work Zone subscriptions and atleast one site is already created on both subaccount WZ instances.

You have access to both Provider subaccount and consumer subaccount and relevant role collections assigned that allows you administrate Work Zone, add content provider, administrate destinations and assign role collections to users.

Step 1: Import the generated destinations from provider to consumer subaccount & edit relevant properties

Admin of provider subaccount needs to accomplish 3 tasks -

Export the DT & RT destinations
Copy clientsecret from service key of HTML Runtime instance of the business solution
Add consumer domain as trusted domains and adjust the CSP headers as required. This part is well explained in the documentation here.

Provider Admin Task 1: First login to the provider subaccount and export both DT and RT destination to your local filesystem.

Provider Admin Task 2:Now go to the instances and subscriptions in the provider subaccount BTP cockpit and look for html5-app-runtime-service instance corresponding to your business solution under the instances tab. In our case of Manage Product example, it is listed as manageproductscdm-html5-app-runtime-service.

Click on it to access the service key binding.

Click on the service key and copy the "clientsecret". We will need this while importing the DT destination in consumer subaccount next.

Provider Admin Task 3:

You'll need to add the URL of SAP Build Work Zone, standard edition of the consumer subaccount to the list of trusted domains in the provider account.

To do this, go to the SAP BTP cockpit, SecuritySettings. In the Trusted Domains tab, click Add. Adding the consumer URL to the trusted domains list, will prevent cross domain errors.

Admin of consumer subaccount needs to accomplish 2 tasks -

Import the DT destination and add the clientsecret copied from provider subaccount
Import the RT destination and update the url & include additional property CEP.HTML5ContentProvider

Consumer Admin Task 1: Fist login to the consumer subaccount and import the DT destination from the filesystem. You will notice that the Client Secret is empty.

Paste the "clientsecret" we copied from the service key binding of html5-app-runtime-service instance from provider account. Save the destination.

Consumer Admin Task 2: Next import the RT destination to the consumer subaccount.

Here, you need to ensure that the URL is maintained as the base Work Zone URL from the provider account. Easiest way would be to launch the provider subaccount site and copy the base URL, which would be in this form -

https://<SAP BTP provider subaccount domain>.<type>.cfapps.<SAP BTP subaccount region>.hana.ondemand.com

... where <type> can be 'launchpad', 'workzone', etc depending on which Work Zone edition is subscribed to from the provider subaccount.

...where <region> is something like eu10, us21, etc.

Moreover, make sure that the additional property "CEP.HTML5ContentProvider" is set to true in the RT destination.

Step 2: Add new content provider based in Work Zone content channel using the destinations

Now, login as Work Zone administrator on the consumer subaccount and navigate to the site manager ➡️ Channel Manager.

Start creation of a content provider from the menu button of the top right corner.

Fill the details and select the Design Time and Run Time destinations that were imported to the consumer tenant. Leave the remaining toggle buttons as default.

Save the Content Provider. The fetch of CDM content from provider and generation of the content provider can take sometime. Wait for the Status of the content provider to change to created.

If you now check the report, you should see all the CDM content (roles, groups, catalogs, apps, etc) that were imported from the provider account as defined in the cdm.json in the MTA of the business solution.

This would have also generated the platform role collections in BTP which can be assigned to users to allow access to the content with the payload of such role as defined in the cdm.json.

Step 3: Review and assign roles fetched from the provider CDM to the site on Consumer Work Zone instance

First navigate to the Site Directory and select the site where you wish to add the roles from this Content Provider. Go to site setting by clicking on the gear symbol and edit the site. In the Assignments section, click the search field to reveal the roles added from the content provider. Click on the plus symbol to add the role(s) to the site.

Step 4: Assign users to the role collection generated based on the roles fetched from the content provider

Login consumer subaccount cockpit as admin and navigate to Role Collections within Security section. Assign the users to the role(s) generated automatically when the Content Provider was created and the CDM role was fetched from the provider cdm.json definition.

These usually have the pattern - ˜<content provider ID>_<CDM Role ID>.

Now, we are all set for the end-users to access the Apps from the Provider subaccount in the Work Zone site of the consumer subaccount.

Update of content

In case, the developer deploys a new version or updated content within the cdm.json, the admin of the Consumer Work Zone instance must manually refresh the content provider in content channel in Work Zone administration console, to retrieve the latest CDM. This manual process is temporary and remains until the automatic refresh is implemented and enabled in the product.

End User Flow

End user can login to the Work Zone site as usual on the consumer tenant. Since the same IDP is configured in both sub-accounts, user access to apps from the provider subaccount are now seamless and abstracted from end-user as to what the actual source is. But, underlying mechanism flowing via the standard Work Zone managed AppRouter and by virtue of content provider RT destination, the app access is routed to the respective provider subaccount.

As per our sample project, user on the consumer Work Zone site sees this -

When the user clicks on the App tile, the app from the provider subaccount should load in-place.

Current Restrictions

Depending on the restrictions at the time of usage of these features, certain scenarios may not yet work. Please refer to the restriction section and release notes for updates on when the respective restrictions are removed.

What's Next

Enabling single-tenant business solutions on BTP to act as content providers for SAP Build Work Zone and access them across subaccounts marks a fundamental shift. This development not only brings parity for BTP-based HTML5 content with other federated content providers, such as SAP S/4 HANA, but also lays the groundwork for supporting multi-tenancy using the same underlying architecture. Consequently, this HTML5 content provider model will pave the way for future support of multi-tenant business solutions using SAP Build Work Zone. Stay tuned for announcements in the coming months.

Consolidated Links

Dev Guide:

Developing HTML5 Business Solutions as Content Providers
- About the Common Data Model Definitions

Admin Guide:

Federation of HTML5 Business Solutions