Pro-code UI Extension in SAP Sales and Service Cloud V2

[JoEng]

One of the most common extension pattern in SAP Sales and Service Cloud Version 2 are UI Mashups. The general guidance on UI Mashups is to use the same identity provider for SAP Sales and Service Cloud Version 2 and the mashup. This way, users will not have to login twice and can directly consume the mashup.

For API Calls towards SAP Sales and Service Cloud Version 2, we recommend to use the SAP BTP Destination service. Using the OAuth2SAMLBearerAssertion allows the extension to retrieve an SAP Sales and Service Cloud Version 2 API Token to do API calls in context of the user. This will ensure the User can only see and manipulate data he is entitled to access. Also the correct user context is used for write requests to ensure a propper audit trail.

Scenario

In this demo scenario we will build an extension to SAP Sales and Service Cloud Version 2, which is displaying all open cases as part of the Account UI. A Sales rep will get an easy overview of all open cases and has the possibility to Escalate cases, where he expects more attention. As part of the scenario we can validate, that the Users is only entitled to see cases in his domain. Also we will see, that the patch requests are done using the correct user.

For this scenario I decided to use a simplified architecture based on the Secure a Basic Node.js App with the Authorization and Trust Management Service XSUAA tutorial. This way we don't need to implement the Authentication logic.

Architecture

Compontens:

• XSUAA and Approuter: The Authentication of users is done by XSUAA and the Approuter. Wen established a trusted connection between XSUAA and the central IdP (in our case SAP Cloud Identity).
• NodeJS Service: This service is handling the service requests from the mashup. It ensures the user is authorized to perform the requested actions and does the communication with SAP Sales and Service Cloud V2.
• Destination Service: The destination service is keeping tenant specific configuration and provides the logic for the OAuth2SAMLBearerAssertion, which will at the end allows to retrieve a user specific authentication token for SAP Sales and Service Cloud V2.
• SAPUI5 Mashup: For this example we decided on SAPUI5 in combination with the horizon theme. It is also possible to use other UI Frameworks like Angular.

Setup XSUAA and Application Router

The application is secured by two components. The Application Router and XSUAA. The Application Router is handling the authorization and acts as an OAuth Client. The XSUAA is a OAuth Service Provided by SAP BTP.

For a Detailed description, how to use AppRouter and XSUAA please checkout the Secure a Basic Node.js App with the Authorization and Trust Management Service (XSUAA) Tutorial.

{
   "xsappname": "case-list",
   "tenant-mode": "dedicated",
   "scopes": [
      {
         "name": "$XSAPPNAME.read",
         "description": "With this scope, USER can read cases."
      },
      {
         "name": "$XSAPPNAME.write",
         "description": "With this scope, USER can write cases."
      }
   ],
   "role-templates": [
      {
         "name": "Viewer",
         "description": "Role to get the list of cases",
         "scope-references": [
            "$XSAPPNAME.read"
         ]
      },
      {
         "name": "Writer",
         "description": "Role to get change cases",
         "scope-references": [
            "$XSAPPNAME.write"
         ]
      }
   ],
   "role-collections": [

 {

 "name": "CaseListViewer",

 "description": "Case List Viewer",

 "role-template-references": [

 "$XSAPPNAME.Viewer"

 ]

 },

 {

 "name": "CaseWriter",

 "description": "Case Writer",

 "role-template-references": [

 "$XSAPPNAME.Writer"

 ]

 }

 ],

 "oauth2-configuration": 

 { 

 "redirect-uris": ["https://approuter-case-list-joek001.cfapps.us10-001.hana.ondemand.com/login/callback"] 

 }

}

security/xs-security.json

The XSUAA configuration is stored in the xs-security.json file. It is describing the available roles. Those roles can be used later to check the general authorization inside the app.

Using the xs-security.json we can create a new XSUAA instance.

cf create-service xsuaa application xsuaa-service-tutorial -c security/xs-security.json

The app router is a nodejs application. The configuration is stored ih the xs-app.json file.

{
  "routes": [
    {
      "source": "^/cases",
      "target": "/",
      "destination": "cases-destination",
      "csrfProtection": false
    }
  ],
  "cors": [
    {
      "uriPattern": "^/cases1$",
      "allowedOrigin": [
        {
          "host": "my1000335.de1.test.crm.cloud.sap",
          "protocol": "https"
        }
      ]
    }
  ]
}

xs-app.json

The CORS related configuration is required to allow write requests as soon as the mashup is embedded into Sales and Service Cloud V2. The hostname needs to be according to your tenant URL.

...
# Application Router
- name: approuter
 path: ./approuter
 routes:
   - route: approuter-case-list-joek001.cfapps.us10-001.hana.ondemand.com
 buildpacks:
   - nodejs_buildpack
 memory: 128M
 services:
 - xsuaa-service
 env:
   destinations: >
     [
       {"name":"cases-destination",
        "url":"https://cases-joek001.cfapps.us10-001.hana.ondemand.com",
        "forwardAuthToken": true}
     ]
   SEND_XFRAMEOPTIONS: false
   COOKIES: "{ \"SameSite\":\"None\" }"

manifest.yml

The manifest.yml file contains the deployment description for the approuter. The destination configuration is pointing towards the application service, we are implementing in one of the next steps. Please check the Cookie and x-frameoptions as they are required as soon as the application is embedded into Sales and Service Cloud.

Setup Destination Service

To make calls to SAP Sales and Service Cloud V2 we need to setup the destination service and bind it to the application server. The setup process for a SAP Sales and Service Cloud V2 Destination is described on help.sap.com.

To consume the destination in an service running on SAP BTP Cloud Foundry Runtime a destination service instance needs to be created inside the related development space.

cf create-service destination lite destination-service

This concludes the BTP setup. We can now focus on the client and server side code.

Server Side Code

The sample code is published on github along with the described configurations.

To call the SAP Sales and Service Cloud V2 API via destination service, we are using the @SAP-cloud-sdk/http-client (on nodejs). The http client is handling the communication with the destination service (retrieving the Service URL and a authentication token) and executing the SAP Sales and Service Cloud V2 API call.

const response = await client.executeHttpRequest({destinationName: "service-cloud", jwt: req.tokenInfo.getTokenValue()}, { method: 'get', url: `/sap/c4c/api/v1/case-service/cases?$filter=(isIrrelevant%20eq%20null%20or%20isIrrelevant%20eq%20false)%20and%20(account.displayId%20eq%20${accountId})%20and%20(status%20ne%2007)&$orderby=adminData.updatedOn%20desc` });

The client SDK is abstracting a couple of activities.

• Retrieving token to call destination service
• Exchange User Token (`req.tokenInfo.getTokenValue()`) with access token for SAP Sales and Service Cloud V2.
• Call SAP Sales and Service Cloud V2 API

Mashup

For the UI you need to ensure you are using the same IDP than the SAP Sales and Service Cloud V2. As the server side is taking care of the token exchange, there is no destination service specific code required.

Deploy Application Code

The Application Code is deployed as another Cloud Foundry Application, which is referencing the destination and xsuaa service.

# Product List Application
- name: cases
  path: ./cases
  instances: 1
  memory: 128M
  routes:
  - route: cases-joek001.cfapps.us10-001.hana.ondemand.com
  buildpacks:
  - nodejs_buildpack 
  timeout: 180
  services:
  - xsuaa-service
  - destination-service

# Application Router
...

The deployment is done with a simple cf push.

Mashup Setup

Integration the mashup in SAP Sales and Service Cloud V2 is a simple process.

1. Navigate to Settings -> Mashup Authoring and create a mashup. The URL parameter can be directly extracted out of the URL or added later in the Process. It is important to not set any default value for dynamic values.
2. On the Account Screen it is possible to place the Mashup in Adaptation Mode. While placing the mashup, the dynamic placeholder can be assigned. In case of this example we are using the Account ID.

After we integrated the mashup on the page, we are testing the Mashup. As we are already logged in via the IdP there is no dedicated Login Screen shown. As soon as we are clicking the "Escalate" button, the case is escalated. The change history contains a personal user. Also the case list is filtered based on the access rights of the user.

Summary

In this blog post, we have created an application, which is secured using the application router and XSUAA. We created an Destination for SAP Sales and Service Cloud V2 and used the Destination Service to call the case API. At the end, we tested, that calls to the SAP Sales and Service Cloud V2 API are done on behalf of the Business User and that the correct user is used in the change log.

If we review the steps we have done to build the extension, we observe, that many steps are configurations, which needs to be done once. As soon as the infrastructure is configured, we can simply add more use-cases with low effort. For implementation projects it is now important to consider the infrastructure setup at the beginning of the project. This will allow to react agile on upcoming development needs during the project execution.

Resources

• Sample Code
• XSUAA Tutorial

[Jens-Limbach]

Great post! This shows very well how to build the foundation for any secured extension for SAP Sales and Service Cloud V2 with BTP. 🙂

[tokgozatakan]

Very nice guide! We already implemented a few UI5 apps (and plenty Build Apps applications) into our SSCV2 system and it is following the same approach. They work well, since the APIs are quite fast it doesn't feel like a mashup. 

You know what would be awesome? Some CAP application that works as an OData wrapper to build Fiori Elements applications directly. That'd make the development much faster!