Use SAP BTP, Kyma runtime to extend SAP Marketing Cloud

[gabbi]

Overview

This blog describes step by step how to do all the necessary configurations required to achieve API and event integration with SAP Marketing Cloud and SAP BTP, Kyma runtime. This, in turn, enables the customers and partners to extend SAP Marketing Cloud using SAP BTP, Kyma runtime.

Remark: Pairing SAP Marketing Cloud or SAP S/4HANA Cloud is currently not possible with SAP BTP trial accounts

Configuration

The above configuration enables access to SAP Marketing Cloud APIs and provides the ability to configure Kyma functions and microservices to be triggered with SAP Marketing Cloud events.

This is achieved thanks to SAP S/4HANA Cloud Extensibility which is a generic way of extending any S/4 system using both Cloud Foundry and SAP BTP, Kyma runtime.

Once the configuration is done, the runtime flow will trigger functions and microservices in SAP BTP, Kyma runtime with SAP Marketing Cloud events. It will also be possible to call SAP Marketing Cloud APIs using the provided credentials.

Runtime

Prerequisites

• A provisioned SAP BTP, Kyma runtime. Read this blog to get started.


• An SAP Marketing Cloud tenant that will be extended using SAP S/4HANA Cloud Extensibility and SAP BTP, Kyma runtime.


• Quota available for the SAP Enterprise Messaging service on the SAP BTP subaccount on which SAP BTP, Kyma runtime is enabled.

Register the S/4 system (SAP Marketing Cloud)

You will start by registering SAP Marketing Cloud as a system in SAP BTP Cockpit. This will allow SAP S/4HANA Cloud Extensibility to set up the necessary configurations and resources to enable API and events integration with SAP BTP, Kyma runtime.

• Create a system in SAP BTP Cockpit.

• Copy the generated token.

• Create a new Extension in SAP Marketing Cloud under Maintain SAP Cloud Platform Extensions and provide the copied token.

• In SAP BTP, add entitlements for SAP S/4HANA Cloud Extensibility to the subaccount in which SAP BTP, Kyma runtime is enabled.

• 
  
  
  
  • Choose Add Service Plans.
  
  
  • Select SAP S/4HANA Cloud Extensibility.
  
  
  • Select the registered S/4 system from the drop-down menu.
  
  
  • Select both messaging and api-access plans.
  
  
  • Save the changes
  
  
  
  

This will make the registered system accessible in Kyma runtime's Service Catalog as you will see in the next steps.

Enable calling SAP Marketing Cloud APIs

TIP: For details on setting up api-access for SAP S/4HANA Cloud APIs in the Kyma runtime, see the official documentation on SAP Help Portal.

This section describes how to do the necessary setup in SAP BTP, Kyma runtime to be able to make API calls to SAP Marketing Cloud.

• In SAP BTP, Kyma runtime, access SAP S/4HANA Cloud Extensibility in Service Catalog.

• Create a new instance with the api-access plan.

In the background, this will:

• 
  
  
  
  • Set up all the necessary communication arrangements in SAP Marketing Cloud.
  
  
  • Create the necessary system users to make API calls.
  
  
  • Set up any other configuration required to make API calls.
  
  
  
  

NOTE: scenarioId will depend on the API calls that will be made to SAP Marketing Cloud.

• Bind the created instance to a function or a microservice in Kyma.

The connection configuration will be available as environment variables that can be used by microservices or functions.

See a sample function that uses the credentials injected by the service binding:

/**

 * Add this to dependencies

{

  "name": "call-mktng-api",

  "version": "1.0.0",

  "dependencies": {

      "axios": "latest"

  }

}

 */

const axios = require("axios");

const baseURI = `${process.env['MKTNG_URL']}/sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=2`

console.log(`baseURI is-- ${baseURI}`);



module.exports = {

    main: async function (event, context) {

        try {

            const response = await axios({

                method: 'get',

                url: `${baseURI}/Campaigns?$top=2`,

                auth: {

                    username: process.env['MKTNG_User'],

                    password: process.env['MKTNG_Password']

                  }

            });

            console.log(response.data.d.results);

            return response.data.d.results

        } catch (error) {

            console.log(error);

            event.extensions.response.status(500).send("Error");

        }

    }

}

Such a function can either be called internally from other functions or exposed externally via Kyma API Rules and then invoked via the URL

Enable SAP Marketing Cloud events consumption

TIP: For details on enabling the consumption of SAP S/4HANA Cloud events in Kyma runtime, see the official documentation on SAP Help Portal.

Set up EMS clients

In Kyma's Service Catalog, create the SAP S/4 HANA Cloud Extensibility instance with the messaging plan:

• For systemName, enter the name of the registered system.


• Provide a unique emClientId.

It will create the Enterprise Messaging client in the background and set up the necessary communication arrangement. You can verify the created client in the Enterprise Messaging admin UI.

The namespace will look as follows: sap/S4HANAOD/{emClientId}

This Enterprise Messaging client will be receiving the events from SAP Marketing Cloud. To capture and forward the events from this instance to Kyma, you need to create another Enterprise Messaging client.

In subscriberFilter, provide the same namespace that was created for the SAP S/4 HANA Cloud Extensibility instance of the messaging plan. This is done to receive events from that namespace in this Enterprise Messaging client.

Configure events in SAP Marketing Cloud

You now need to configure in SAP Marketing Cloud all event types you wish to send to SAP BTP, Kyma runtime for various extensions.

• In SAP Marketing Cloud, access Enterprise Event Enablement.

• Go to channels list and select the channel with the name SAP_CP_XF_{emClientId}

• Search and select the events that will be sent.

As an example, I selected sap/s4/beh/marketingpermission/v1/MarketingPermission/*.

You will see the same events appearing in the EMS admin UI.

 

Set up an extension in SAP BTP, Kyma runtime

You can now create a serverless function or a microservice that can receive the events from SAP Marketing Cloud via Enterprise Messaging.

These steps show how to create a function, but the flow will be similar if you decide to use a microservice.

To enable secure access, you have an option to set up OAuth2 for the exposed webhook. However, it is not a must to use OAuth2 - customers can always use their preferred authentication mechanism such as basic authentication or any other that works with EMS webhooks.

• Set up an OAuth2 client in Kyma.

Note: The client id and client secret values are by default encoded. Please decode and then copy them to EMS webhook details

• Expose the function with an API Rule.

Configure an Enterprise Messaging webhook

To consume the events, you need to go to the second Enterprise Messaging client that was created and configure the queue and subscription to enable SAP BTP, Kyma runtime to start receiving the events. Then, you need to create a webhook.

• Create a new queue for this EMS client.

• Create a queue subscription.

• Configure the queue subscription by setting Topic to the namespace originally created for the messaging instance of SAP S/4HANA Cloud Extensibility.

• Set up the webhook.

• The webhook url is the URL of the API rule created in Kyma runtime to receive events.


• Provide the client id and client secret for the OAuth client client created in Kyma runtime.


• Provide the Token URL. It is of the form https://oauth2.{kyma cluster domain}/oauth2/token

This completes the whole setup and allows the function to start receiving events.

As the last check, you can view the payload printed in the Kyma logs:

Sample Json Payload

{"type":"sap.s4.beh.marketingpermission.v1.MarketingPermission.Changed.v1","specversion":"1.0","source":"/default/sap.s4.beh/000000000730096987","id":"+hY+VeskHtuDiNMBjQ0Tgg==","time":"2020-10-12T04:51:30Z","datacontenttype":"application/json","data":{"MarketingPermissionUUID":"fa163e0b-249b-1ee9-b48b-5ab2bab3c4b8","PermissionGranted":"Y"}}

Now you have both events and apis from SAP Marketing Cloud connected to SAP BTP, Kyma runtime. Thus enabling you to extend SAP Marketing Cloud using SAP BTP, Kyma runtime