CRM and CX Blogs by SAP
Stay up-to-date on the latest developments and product news about intelligent customer experience and CRM technologies through blog posts from SAP experts.
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

SAP Emarsys Customer Engagement - Enhanced Lead Integration to SAP Sales Cloud Version 1

philipp_eicker
Product and Topic Expert
Product and Topic Expert
2 weeks ago

Table of Contents

  • Introduction
  • Background Information
    • Setup Steps in SAP Emarsys Customer Engagement
      • Create the Webhook Node Preset
      • Create the Automation Program
  • Integration Process
    • SAP Integration Suite
      • Purpose
      • Integration Flow
    • Connectivity Setup between Emarsys & SAP Integration Suite
      • Endpoint URL
      • Authentication
  • Conclusion

 

Introduction

The handover of marketing qualified leads to sales plays a crucial role in the marketing-driven lead process. It ensures that the sales team receives high-quality leads, which in turn improves sales efficiency and promotes collaboration between the marketing and sales departments.

This blog post describes how to built an integration between SAP Emarsys Customer Engagement (SAP Emarsys) and SAP Sales Cloud Version 1, leveraging the SAP Cloud Integration service included in SAP Integration Suite. This integration enables the creation of leads in SAP Sales Cloud with a broader range of information, exceeding the scope covered by the out-of-the box function.

Note: The SAP Emarsys Account Engagement (SAP Account Engagement) add-on enhances SAP Emarsys with B2B capabilities to run end-to-end processes being seamlessly integrated with SAP Sales Cloud. Our official SAP Account Engagement documentation highlights the out-of-the-box functionality of the SAP Emarsys Webhook which allows to create leads directly in SAP Sales Cloud. Creating leads directly in SAP Sales Cloud is limited to using a subset of fields represented in a flat structure.

The content described in this blog is custom-built and not part of any SAP pre-packaged integration. It can be used as a template for building a custom integration with SAP Emarsys Customer Engagement and SAP Sales Cloud Version 1. SAP Integration Suite is used for the message transformation for API-based data imports to SAP Sales Cloud Version 1.

Example: 

Let's assume we are organizing a trade fair for which contacts can register online on an external landing page. Part of this registration form is the option to indicate interest in an expert meeting at the booth. To do so, contacts are asked to enter their topic of interest and a suitable time slot into the form notes. In addition, they have the option to provide their email opt-in.

When the form is submitted, contacts that previously did not exist yet in SAP Emarsys are created using the SAP Emarsys API. The additional form notes are written to a dedicated custom field.

To demonstrate the technical integration, we execute the following simplified scenario: We handover newly created SAP Emarsys contacts who have submitted form notes to SAP Sales Cloud so that sales representatives can further validate the lead. (Note that we are intentionally simplifying at this point. In a real-life scenario, the business logic for determining when a contact is a marketing-qualified contact can of course vary.)

In the following we will take a closer look at the required setup steps.

 

Background Information

To create the contacts gathered from the Web forms as leads in SAP Sales Cloud we need to use Webhooks as part of an SAP Emarsys Automation Program.

A Webhook is an event-based API endpoint responsible for triggering internal functions to look up information in real time when a specific event occurs. Webhooks are used to integrate different applications and third-party APIs, allowing for real-time communication between two applications without the need for additional coding or a complex setup. For more information, take a look at the SAP Emarsys help documentation under Webhook Node.

Note that the Webhook node is an advanced feature, for which you need some technical resources to integrate it into your application. It is your responsibility to make sure that the integrated service operates appropriately.

An Automation Program is a customer engagement journey that is automated and aims to lead your interaction with a customer towards a specific goal. It starts from a single entry point and can spread out to multiple branches of a decision tree until reaching an end point. For more information, take a look at the the SAP Emarsys help documentation under Automation.

 

Setup Steps in SAP Emarsys Customer Engagement

Create the Webhook Node Preset

You first have to create a Webhook preset that can be used as input for the Webhook node in your automation program.

To do so, open the menu and choose Automation > Webhook Node Presets > Create Preset:

Menu Path to "Webhook Node Presets"Menu Path to "Webhook Node Presets"

Appearance Settings

  1. Define a preset name - this will help to identify the configuration preset in the Webhook node settings and will appear as the name of the node.
  2. Select a node icon - this icon will appear on the node after the preset has been selected.

SAP Emarsys Customer Engagement | Webhook Node - Appearance SettingsSAP Emarsys Customer Engagement | Webhook Node - Appearance Settings

Connection Settings

The connection settings are described as part of the Integration Process (see below).

Data Settings

The Webhook node can send data of the triggering event to the API endpoint, as well as values of contact data fields and additional data with static values.

Event Data

  1. Select this checkbox if you would like to forward the event payload that triggers the program. In our case, we don’t need to enable the “send triggering event data” flag as we are only considering the contact data that is coming from the external landing page through the SAP Emarsys API.

SAP Emarsys Customer Engagement | Webhook Node - Data Settings / Event DataSAP Emarsys Customer Engagement | Webhook Node - Data Settings / Event Data

Contact Data

  1. Here you can define key-value pairs to send contact data field values. In our case, we need to define the data that should be replicated for the lead creation in SAP Sales Cloud. Besides the SAP Emarsys system fields (see Emarsys System Fields), you can also use your own custom fields (see Creating Custom Fields). In the example below, we created the 'Form Notes' as a custom field which contains additional information gathered through the registration form.

    Note: You can add maximum 20 contact fields when defining contact data key-value pairs.

  2. Important: You must ensure to handover the contact identifier that was initially defined for the SAP Emarsys tenant. Handing over the identifier will allow SAP Sales Cloud to update the SAP Emarsys contact at a later point in time. For more details about contact matching with SAP Account Engagement, see Specifying a Contact Matching Method. 

SAP Emarsys Customer Engagement |Webhook Node - Data Settings / Contact DataSAP Emarsys Customer Engagement |Webhook Node - Data Settings / Contact Data

Additional Data

  1. These fields can contain static values that are sent with the requests so that your external system can identify their source (for example, the journey or scenario the event came from) and purpose.
  2. Here we are using the following data:
    • Name: No value defined - this allows the users that create the program to define the name
    • Priority: Same values that are known in SAP Sales Cloud
    • Origin Type: Same values that are known in SAP Sales Cloud (standard + custom fields)
    • Qualification Level: Same values that are known in SAP Sales CloudSAP Emarsys Customer Engagement | Webhook Node - Data Settings / Additional DataSAP Emarsys Customer Engagement | Webhook Node - Data Settings / Additional Data

Operational Data

  1. These fields are optional in the event data. You can also rename them. We recommend keeping the deduplication ID to make sure that the receiving system does not process duplicated messages. In our example, we don't map the 'ems_program_id', but it could be beneficial to map the programID where the Webhook nodes was triggered with a custom field in SAP Sales Cloud. 

SAP Emarsys Customer Engagement | Webhook Node - Data Settings / Operational DataSAP Emarsys Customer Engagement | Webhook Node - Data Settings / Operational Data

Create the Automation Program

The example described above uses the transactional entry point "New Contact" to trigger the automation program. In addition to the new contact criteria, a segment filters on contacts that have submitted form notes as part of their fair trade registration.

Note: There are various options to customize this process by using additional filters to make sure that only dedicated contacts are replicated. If you are using the "New Contact" entry node without any additional filter criteria, every new contact is considered. Customers using the SAP Account Engagement add-on can use the pre-built "Replicate New Marketing Contact" tactic (see Replicate New Marketing Contact).

  1. Create the Automation Program (Audience-focused journeys) 

    SAP Emarsys Customer Engagement | Automation Program CreationSAP Emarsys Customer Engagement | Automation Program Creation

  2. Assign the Webhook Node 

    SAP Emarsys Customer Engagement | Automation Program - Webhook Node AssignmentSAP Emarsys Customer Engagement | Automation Program - Webhook Node Assignment

  3. Maintain 'Additional Data Settings'

    As no value was defined for the 'Name' of the Webhook, the user creating the automation program can define the value.

    SAP Emarsys Customer Engagement | Automation Program - Webhook Note Additional Data SettingsSAP Emarsys Customer Engagement | Automation Program - Webhook Note Additional Data Settings

 

In the next step we will take a look at the integration process.

 

Integration Process

SAP Integration Suite

Purpose

SAP Integration Suite combines SAP Cloud Integration, API Management, Integration Advisor, Open Connectors, and other integration capabilities into a cohesive and simplified toolkit for enterprise integration.

The SAP Emarsys Webhook node only allows to pass flat structures to an API. For setting up the marketing permissions, the SAP Sales Cloud Lead-API requires sub-structures. Therefore, we use SAP Integration Suite to do this transformation.

Integration Flow

The integration flow was designed to make it easily transferable and adjustable. It consists of one Groovy-script step with the following functionality:

  • Mapping of field names and key values
  • Transformation to the required structure for the SAP Sales Cloud-Lead-API
  • Setting of the headers

SAP Cloud Integration | Integration FlowSAP Cloud Integration | Integration Flow

Mapping

The mappings and transformations take place within the Groovy-script step. The entire code is provided at the end of this blog for reference. Within this script, the parsed JSON object from the Webhook payload is accessible via the Groovy Map 'mapJson'. Field names within 'mapJson' correspond to those in the Webhook within SAP Emarsys.
The target structure for calling the LeadCollection OData service is included in the Groovy-Map 'mapJson'. Here, it's crucial that the field names align precisely with those specified in the OData service definition. Upon completion of the mapping process, the 'mapJson' is converted into a JSON object and incorporated into the payload body. Encapsulation of value mappings is handled within the 'MapHelper' class, where static methods facilitate the mapping of field values.

SAP Cloud Integration | Groovy Script - MappingSAP Cloud Integration | Groovy Script - Mapping

To include extra mappings such as linking the SAP Emarsys field 'MyAdditionalEmarsysField' to the SAP Sales Cloud field 'MyAdditionalSalesCloudField_KUT', simply insert the following line into the code:

 

 

mapJson.MyAdditionalSalesCloudField_KUT = inJson.MyAdditionalEmarsysField

 

 

Note: As mentioned above it is important to handover the contact identifier that was initially defined for the SAP Emarsys tenant. Handing over the identifier will allow SAP Sales Cloud to update the SAP Emarsys contact at a later point in time. For more details about contact matching with SAP Account Engagement, see Specifying a Contact Matching Method. 

In our example, we created the SAP Sales Cloud extension field 'Emarsys Contact UID' and therefore maintained the following mapping:

 

 

mapJson.EmarsysContactUID_KUT = inJson.EmarsysUID

 

 

Inbound / Outbound Connectors

For both inbound and outbound we are using the HTTP-connector (since we have a JSON payload, we cannot use the Odata adapter for calling SAP Sales Cloud).

The adapter settings are the following:

Inbound

SAP Cloud Integration | Integration Flow - Inbound ConnectionSAP Cloud Integration | Integration Flow - Inbound Connection

Outbound

SAP Cloud Integration | Integration Flow - Outbound ConnectionSAP Cloud Integration | Integration Flow - Outbound Connection

Connectivity Setup between SAP Emarsys & SAP Integration Suite

Endpoint URL

After deploying the integration flow, the endpoint can be copied from SAP Integration Suite/SAP Cloud Integration

SAP Cloud Integration | Endpoint URLSAP Cloud Integration | Endpoint URL

to the Webhook in SAP Emarsys:

SAP Emarsys Customer Engagement | Webhook Endpoint URLSAP Emarsys Customer Engagement | Webhook Endpoint URL

Authentication

The easiest way to authenticate the Webhook call at the integration flow endpoint is via OAuth. In the SAP Business Technology Platform cockpit make sure that the instance of the Process Integration Runtime contains the role ESBMessaging.send (see Setting Up Inbound HTTP Connections). 

SAP BTP Cockpit | Instances View ParameterSAP BTP Cockpit | Instances View Parameter

Then create a service key and copy the clientid, clientsecret and the tokenurl 

SAP BTP Cockpit | Instance CredentialsSAP BTP Cockpit | Instance Credentials

to the corresponding fields of the authentication settings of the Webhook in SAP Emarsys:

SAP Emarsys Customer Engagement | Webhook AuthenticationSAP Emarsys Customer Engagement | Webhook Authentication

 

Conclusion

Now let’s shed some light on what we have achieved with the utilization of SAP Integration Suite with regard to the integration of SAP Emarsys Customer Engagement with SAP Sales Cloud Version 1.

While the out-of-the-box SAP Emarsys Webhook functionality for lead creation in SAP Sales Cloud is limited to using a subset of fields represented in a flat structure, the use of SAP Integration Cloud removes this restriction and allows the incorporation of advanced lead information.

On the one hand, information has been successfully replicated to nested lead attributes, including form text to notes and email opt-in status at subnode level to the marketing permission:

SAP Sales Cloud - Lead Includes Notes and Email Opt-inSAP Sales Cloud - Lead Includes Notes and Email Opt-in

On the other hand, the “Additional data" including the priority, origin type, and qualification level of the lead was presented to the automation program creator in a descriptive format so that they do not have to rely solely on code values. Consequently, the process of selecting the appropriate values became noticeably more user-friendly.

In this way, the process of creating leads in SAP Sales Cloud has not only been enhanced by the use of SAP Integration Cloud, but has also been significantly simplified.

Preview file
12 KB
Popular Blog Posts