tl;dr

• In order to reach the business rules service, configure the managed app router with a

  "service": "com.sap.bpm.rule",
  "endpoint": "rule_runtime_url",​

  route, instead of a ‘destination’ route.

Where to store the configuration of an HTML5 application?

Perhaps the most convenient and business-friendly solution would be to use the Business Rules Service. The Business Rules service can easily act as a central configuration repository, with the added bonus of allowing key users to manage the configuration as they please.

The following steps will guide you through an example that you can implement in your trial (or free tier) account.

Step by Step Instructions

Step 0: Create and set up your trial account

1. Go to https://account.hanatrial.ondemand.com/trial/#/home/trial.
2. Start the ‘Set up account for Workflow Management’ booster.
   1. On the ‘Success’ screen, follow the ‘Go to Application’ link of ‘Open Workflow Management launchpad to access workflow, business rules, process visibility, and process flexibility applications.’

Step 1: Define the configuration

The configuration to serve via the business rules service is the following:

/** @type {{ Greeting: string, Addressee: string }} */
{
  "Greeting": "Hello",
  "Addressee": "world"
}

On the ‘Workflow Management Service’ cockpit, click ‘Development Tools / Create Rule Projects’.

1. Follow ‘Create a Project to Author Rules‘ to create rule project ‘MyHtml5appConfiguration’ with the following:
   1. Name, Label = ‘MyHtml5appConfiguration’
2. Create new local data object ‘InputElement’:
   1. Type = ‘Element’
   2. Business Data Type = ‘Boolean’
   3. Value help = [ true, false ]
3. Create new local data object ‘MyHtml5appConfiguration’:
   1. Type = ‘Structure’
   2. Attributes:
      1. ‘Greeting’:
         1. Type = ‘Element’
         2. Business Data Type = ‘String’
         3. Value help = [ ‘Hello’, ‘Hola’ ]
      2. ‘Addressee’:
         1. Type = ‘Element’
         2. Business Data Type = ‘String’
         3. Value help = [ ‘world’, ‘sun’, ‘moon’ ]
   3. Activate
4. Create new local rule ‘TextRule’:
   1. Type = ‘Text Rule’
   2. Result = ‘MyHtml5appConfiguration’
   3. Rule:
      1. If = true
      2. Then:
         • Addressee = ‘world’
         • Greeting = ‘Hello’
   4. Activate
5. Create new rule service ‘ConfigurationService’:
   1. Vocabulary:
      1. InputElement usage = ‘Input’
      2. MyHtml5appConfiguration usage = ‘Result’
   2. Activate
6. Create new rule set ‘ConfigurationRuleSet’:
   1. Rule Service = ‘ConfigurationService’
   2. Rules = ‘TextRule’
   3. Activate
7. Deploy rule service ‘ConfigurationService’ to the cloud runtime.
8. Optional:
   1. Release the version:
      1. Version = ‘1.0.0’
      2. Revision = ‘1’ (same as major version)
      3. Description = ‘Initial version.’
   2. Deploy the released version.
   3. In order to use the release version, set below:
      1. Service URL ‘rule-services’ instead of ‘workingset-rule-services’.
      2. Add `”RuleServiceRevision”: “1”` to the request body.
9. Test the ‘ConfigurationService’ using the SAP API Business Hub.
   1. The response should be like:

      {
        "Result": [
          {
            "MyHtml5appConfiguration": {
              "Greeting": "Hello",
              "Addressee": "world"
            }
          }
        ]
      }​

Step 2: Create the HTML5 application to be configured

In the Business Application Studio:

1. Create a ‘Full Stack Cloud Application’ ‘Dev Space’.
2. Enter the dev space and use ‘Start from template’ to create a new ‘Basic Multitarget Application’.
3. Add app router configuration:
   1. Right click ‘mta.yaml’ and choose ‘Create MTA Module from Template’ to create a new ‘Approuter Configuration’:
      1. Managed Approuter
      2. Give a unique name for the business solution of the project.
      3. Do you plan to add a UI?: ‘Yes’
4. Add a UI module:
   1. Right click ‘mta.yaml’ and choose ‘Create MTA Module from Template’ to create a new ‘SAP Fiori application’:
      1. ‘SAPUI5 freestyle’ / ‘SAPUI5 Application’
      2. Data source: ‘None’
      3. Project attributes:
         1. Module name: ‘ui1’
         2. Application title: ‘App Configured via Business Rules’
         3. Application namespace: ‘<app>.<namespace>.<of>.<your>.<choice>’
         4. Add deployment configuration to MTA project: ‘Yes’
      4. Wait for the module to be added and generated.
5. In ‘manifest.json’:
   1. Remove the ‘mainService’ data source and change the default model to type ‘sap.ui.model.json.JSONModel’.
   2. Change the pattern of route ‘RouteView1’ to the empty string “”.
6. Add the ‘config’ model:
   1. Add a JSON model for the configuration from the business rules service:
      1. In ‘manifest.json’ in ‘sap.ui5.models’:

         "config": {
             "type": "sap.ui.model.json.JSONModel",
             "settings": {
                 "ruleServiceId": "<your rule service ID> e.g. 998bdc940a274cabaa8dcc5cc77abcde"
             }
         },

   2. Edit ‘model/models.js’ to add the configuration loader logic as suggested by the code snippet on the API Business Hub:

      loadConfigModelAsync: function (component) {
          let config = component.getModel("config");
          config.setDefaultBindingMode(sap.ui.model.BindingMode.OneWay);
      
          let ruleServiceId = config.getProperty("/ruleServiceId");
      
          if (ruleServiceId) {
              // Get XSRF token:
              // Match with route "^/business-rules-runtime/(.*)$" in xs-app.json, and API definition at [1]:
              //  [1] https://api.sap.com/api/SAP_CF_BusinessRules_Runtime_V2/resource
              $.ajax({
                  url: "./business-rules-runtime/rules-service/rest/v2/xsrf-token",
                  headers: { "X-CSRF-Token": "Fetch" }
              }).then(function (data, textStatus, jqXHR) {
                  let csrfToken = jqXHR.getResponseHeader('X-CSRF-Token');
      
                  // Get the configuration.
                  // JavaScript snippet from the API Business Hub:
                  var oRequestData = {
                      "RuleServiceId": ruleServiceId,
                      "Vocabulary": [{ "InputElement": true }]
                  };
      
                  $.ajax({
                      url: "./business-rules-runtime/rules-service/rest/v2/workingset-rule-services",
                      method: "POST",
                      headers: {
                          "DataServiceVersion": "2.0",
                          "Accept": "application/json",
                          "Content-Type": "application/json",
                          "x-csrf-token": csrfToken
                      },
                      data: JSON.stringify(oRequestData),
                      dataType: "json"
                  }).then(function (data, textStatus, jqXHR) {
                      jQuery.sap.log.debug("loaded configuration from business rules service");
                      //
                      if (data.Result[0]) {
                          config.setData(data.Result[0], true);
                      } else {
                          jQuery.sap.log.error(`unexpected data received: ${JSON.stringify(data)}`);
                      }
                  }, function (jqXHR, textStatus, errorThrown) {
                      jQuery.sap.log.error(jqXHR.responseText);
                  });
              }, function (jqXHR, textStatus, errorThrown) {
                  jQuery.sap.log.error(jqXHR.responseText);
              });
          }
      }

   3. Edit the ‘init’ function in ‘Component.js’ to load the configuration:

      // Load the configuration
      models.loadConfigModelAsync(this);
      

7. Edit the UI to show a greeting:
   1. Edit ‘View1’ with the layout editor, and add a label.
   2. Bind the label text to:

      "{config>/MyHtml5appConfiguration/Greeting}, {config>/MyHtml5appConfiguration/Greeting}!"​

8. Bind the application to the business rules service:
   1. Add a new resource to ‘mta.yaml’, e.g.:

        - name: ovh.lkajan.blogpost-business-rules-svc
          type: org.cloudfoundry.managed-service
          parameters:
            service: business-rules
            service-plan: lite # Choose 'basic' for non-trial use.

   2. Make the destination content module require the business rules service, and add a destination to the business rules service instance, e.g.:

      modules:
        - name: ovh.lkajan.blogpost-destination-content
          type: com.sap.application.content
          requires:
            # [...]
            - name: ovh.lkajan.blogpost-business-rules-svc
              parameters:
                service-key:
                  name: ovh.lkajan.blogpost-business-rules-svc-key
          parameters:
            content:
              instance:
                destinations:
                  # [...]
                  - Name: ovh_lkajan_blogpost_business_rules_svc
                    Authentication: OAuth2ClientCredentials
                    ServiceInstanceName: ovh.lkajan.blogpost-business-rules-svc
                    ServiceKeyName: ovh.lkajan.blogpost-business-rules-svc-key
      resources:
        # [...]
        - name: ovh.lkajan.blogpost-business-rules-svc
          type: org.cloudfoundry.managed-service
          parameters:
            service: business-rules
            service-plan: basic​

9. Route requests to the business rules service:
   1. Add a new route to ‘xs-app.json’:

        "routes": [
          {
            "source": "^/business-rules-runtime/(.*)$",
            "target": "/$1",
            "service": "com.sap.bpm.rule",
            "endpoint": "rule_runtime_url",
            "authenticationType": "xsuaa"
          },
          ...​

      • Note: “endpoint” is documented on ‘routes‘ and on Zvi Zeltser’s ‘SAP Application Router‘ blog post.
10. Build, and deploy the application.
11. Test the application by clicking its link on the ‘HTML5 Applications’ tab of the cockpit.

Credits

I thank Roberto De Salvo for the research he conducted on the topic of accessing the business rules runtime from a UI5 application.

Author and Motivation

Laszlo Kajan is a full stack Fiori/SAPUI5 expert, present on the SAPUI5 field since 2015, diversifying into the area of BTP (i.e. SAP cloud) development.

The motivation behind this blog post is to provide a concise example that shows how to retrieve HTML5 application configuration from the Business Rules Service.