Please refer to the updated blog post “Best Practices for Importing Interaction Contact Data into SAP Marketing Cloud” here.

Introduction

Welcome to the blog post of the Expert Services Marketing Practice.

We are happy to share our experience with you around Marketing Integration, Analytics, and Business Technology.

You want to see more blogs from Expert Services? Click here

Overview

With this blog post we’ll provide a step-by-step configuration guide on how to setup SAP Hybris Marketing Cloud to receive messages from SAP Cloud Platform Integration.
We’ll go through the basic configuration steps and basic Iflow design and help you to understand how to use the available APIs on SAP Hybris Marketing Cloud.

This blog post does extend the existing documentation providing a examples and use cases, but does not replace or repeat information already documented in the official SAP API documentation.

 Product version

For this Blog Post following product release version has been used.

Note:
Since we have short release cycles, the content in this blog post might look different from what you find on your SAP Hybris Marketing Cloud and SAP Cloud Platform Integration system.
SAP Hybris Marketing Cloud: Quarterly release cycles
SAP Cloud Platform Integration: Monthly release cycles

Scope (Contact API, Scenario)

In this blog post we cover E2E scenarios maintaining contact data using the Contact OData API described in the API documentation listed below.

SAP Hybris Marketing Cloud Odata API: API_MKT_CONTACT
Documentation: https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/latest/en-US/06526bdbae42455ba69a4aef0750561b.html

We’ll cover the following scenarios:

• Retrieve a Contact Best Record from SAP Hybris Marketing Cloud
• Create a new Contact record on SAP Hybris Marketing Cloud
• Update an existing Contact record in SAP Hybris Marketing Cloud
• Create Marketing Permission for a specific Contact

This diagram illustrates the scenarios covered in this blog post.

Prerequisites

• SAP Hybris Marketing Cloud
• SAP Cloud Platform integration
• Postman (or any other tool to send a http request)
• XML tool (Intellij IDEA, Notepad++ or any other tool to read XML formatted messages)

References

• How to use the new Contact OData API for SAP Hybris Marketing Cloud 1711
  https://blogs.sap.com/2018/01/18/how-to-use-the-new-contact-odata-api-for-sap-hybris-marketing-cloud-1711
• Hybris Wiki
  https://wiki.hybris.com/display/marketing/SAP+Hybris+Marketing
• SAP Hybris Marketing Cloud Documentation
  https://help.sap.com/viewer/p/SAP_HYBRIS_MARKETING_CLOUD
• SAP Hybris Marketing Cloud Documentation – Public OData API (API_MKT_CONTACT)
  https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/latest/en-US/06526bdbae42455ba69a4aef0750561b.html
• SAP API Business Hub – SAP Hybris Marketing Cloud
  https://api.sap.com/shell/discover/contentpackage/SAPS4HANAMarketingCloud
  
• SAP Hybris Marketing Cloud Community
  https://www.sap.com/community/topic/hybris-marketing.html
• SAP Hybris Products for Marketing
  https://www.hybris.com/en/products/marketing

Configuration Guide

This configuration guide provides an overview of the sequence on configuration steps mandatory to the Integration scenario running.

SAP Hybris Marketing Cloud (yMKT)

• In SAP Hybris Marketing Cloud, navigate to the Communication Management Apps
• (Optional) Create a Communication User (depends on the Authentication option you select)
• Create a Communication System with your CPI tenant as your communication partner
• Create a Communication Arrangement with Communication Scenario SAP_COM_207 (Marketing – Interaction Contact Integration)

SAP Cloud Platform Integration (CPI)

(Custom Integration Scenario)

• Logon to your SAP Cloud Platform Cockpit
• Create a technical user on the SAP Cloud Platform Cockpit
• Logon to SAP Cloud Platform Integration and navigate to Design
• Create a new Integration Package
• Create, design and configure a new Iflow
• Deploy the IFlow

(Optional) Download and install Postman

• Configure a new request to send a request to the created endpoint on CPI

Configure SAP Hybris Marketing Cloud Communication with the Contact API

Follow the yMKT documentation for setting up communication with yMKT.

• Integrate with Public APIs
  https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/latest/en-US/6e8377c56934462ca3f75bdc38faa6d5.html
• Communication Management
  https://help.sap.com/viewer/e0cd7c1ecf3d4f2f9feb46ec1c5b68fb/latest/en-US/2e84a10c430645a88bdbfaaa23ac9ff7.html?q=communication
• Maintain Communication User
  https://help.sap.com/viewer/e0cd7c1ecf3d4f2f9feb46ec1c5b68fb/latest/en-US/eef80dda3867461c92ac1273689ed36f.html
• Maintain Communication System
  https://help.sap.com/viewer/e0cd7c1ecf3d4f2f9feb46ec1c5b68fb/latest/en-US/15663c157670410ca366623dff329396.htm
• Maintain Communication Arrangement
  https://help.sap.com/viewer/e0cd7c1ecf3d4f2f9feb46ec1c5b68fb/latest/en-US/fab3fd449cf74c6384622b98831e989e.html

Demo: Configure Inbound Communication with SAP Hybris Marketing Cloud

Communication Arrangement Screen

Scenario ID:SAP_COM_0207

Scenario Description: Marketing – Interaction Contact Integration

Review OData Service Metadata

In the Blog Post we are using the Contact API v2.

From the Communication Arrangement copy the Service URL  and display the Service metadata in your Web browser. Review the available fields to make yourself familiar with the available standard Entities and Properties.
https://my000000-api.s4hana.ondemand.com/sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0002/$metadata

Before using any API, read through the documentation and pay attention to the Notes and Caution callouts in the documentation on help.sap.com.
Review the supported HTTP Methods for the Entity Set you are planning to use.

SAP Hybris Marketing Cloud API Documentation
https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1802%20500/en-US/06526bdbae42455ba69a4aef0750561b.html

SAP API Business Hub – SAP Hybris Marketing Cloud – Marketing – Contacts
https://api.sap.com/shell/discover/contentpackage/SAPS4HANAMarketingCloud/api/API_MKT_CONTACT_SRV

What happens with Contact Data on SAP Hybris Marketing Cloud?

Before loading any Contact data to the SAP Hybris Mrketing System understand what happens with the contact data on SAP Hybris Marketing.

Importing Contact Data in SAP Hybris Marketing Cloud

Retrieve Contact Best Record from SAP Hybris Marketing

Entity Path – Contacts

The /Contacts entity allows us to retrieve Contact Best Records (or Golden Records) from the yMKT system.

Let’s assume that the connected system, what is simulated with Postman, request a set of contacts from yMKT.

Get Contacts using OData Parameters

You can use the Odata Parameters supported by the Contact API as Query Strings as described in the help documentation.
For detailed information how to use Query Strings, refer to the Odata documentation.

Odata v2 URI conversion documentation.
http://www.odata.org/documentation/odata-version-2-0/uri-conventions/

Get one specific Contact with their UUID

From the Odata Service metadata you can see that the ContactUUID is a key and the type is Edm.Guid.
To form a successful GET request to retrieve a specific contact from the Contact API you need to provide the ContactUUID.

Configure a SAP Cloud Platform Integration IFlow

Logon to CPI and create a new Iflow.
Create a HTTP sender channel and configure the HTTP sender channel.
We did disable CSRF Protection to make testing easier.

Demo:

This demo shows the first steps to create a new custom Iflow and test receiving messages for processing.

When deploying the Iflow, the HTTP endpoint is created with the following format.
https://{CPI-Runtime-URL}/http/{Address}

Next, add a Request-Reply integration pattern and connect the Request-Reply service call to a receiver block.
Configure the receiver communication channel as Odata.

Address: https://my000000.s4hana.ondemand.com/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002
Proxy Type: Internet
Operation Details: GET
Resource Path: Contacts
Custom Query (example): $filter=${property.filter}&$select=${property.select}&$top=${property.top}&$format=${property.format}

Note:
The Integration Developer must make sure to from a valid query string. This highly depends on the implementation project and requirements, what parameters are used to pull contacts from the Contact API.
We have selected a subset of the available query parameter and added the dynamic values using simple expressions.

When using Basic Authentication to connect to the Odata service, create a new credential artifact the holds the username and password.

Example IFlow

SAP Cloud Platform Integration Request Message

E-Mail with attachment

Example Requests and Replies

This section contains a couple example request and replies for:
/API_MKT_CONTACT_SRV;v=0002/Contacts

Get a specific contacts using the contact entry’s UUID

Request

GET /sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/Contacts?
$filter=Country eq 'DE' and DepartmentName eq 'Sales'
&$select=ContactUUID,FirstName,LastName,EmailAddress,PhoneNumber,MobileNumber,CorporateAccountName
&$top=10
&$format=json HTTP/1.1
Host: my000000.s4hana.ondemand.com

Response (JSON)

{
  "d": {
    "results": [
      {
        "__metadata": {
          "id": "https://my000000.s4hana.ondemand.com:443/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/Contacts(guid'00163e58-21d4-1ed8-8a9e-cf8a63fe3075')",
          "uri": "https://my000000.s4hana.ondemand.com:443/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/Contacts(guid'00163e58-21d4-1ed8-8a9e-cf8a63fe3075')",
          "type": "API_MKT_CONTACT_SRV.Contact"
        },
        "ContactUUID": "00163e58-21d4-1ed8-8a9e-cf8a63fe3075",
        "FirstName": "Vaasudeva",
        "LastName": "Swamy",
        "EmailAddress": "vaasudeva@hybristest.com",
        "PhoneNumber": "",
        "MobileNumber": "",
        "CorporateAccountName": "Kohli Store California"
      },
      {
        "__metadata": {
          "id": "https://my000000.s4hana.ondemand.com:443/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/Contacts(guid'00163e35-616b-1ed8-8a9e-cf43881e5a19')",
          "uri": "https://my000000.s4hana.ondemand.com:443/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/Contacts(guid'00163e35-616b-1ed8-8a9e-cf43881e5a19')",
          "type": "API_MKT_CONTACT_SRV.Contact"
        },
        "ContactUUID": "00163e35-616b-1ed8-8a9e-cf43881e5a19",
        "FirstName": "Kanda",
        "LastName": "Swamy",
        "EmailAddress": "kanda@hybristest.com",
        "PhoneNumber": "",
        "MobileNumber": "",
        "CorporateAccountName": "Kohli Store California"
      }
    ]
  }
}

Response (XML)

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xml:base="https://my300011.s4hana.ondemand.com:443/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/">
    <id>https://my300011.s4hana.ondemand.com:443/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/Contacts</id>
    <title type="text">Contacts</title>
    <updated>2018-03-19T19:33:30Z</updated>
    <author>
        <name/>
    </author>
    <link href="Contacts" rel="self" title="Contacts"/>
    <entry>
        <id>https://my300011.s4hana.ondemand.com:443/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/Contacts(guid'00163e58-21d4-1ed8-8a9e-cf8a63fe3075')</id>
        <title type="text">Contacts(guid'00163e58-21d4-1ed8-8a9e-cf8a63fe3075')</title>
        <updated>2018-03-19T19:33:30Z</updated>
        <category term="API_MKT_CONTACT_SRV.Contact" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
        <link href="Contacts(guid'00163e58-21d4-1ed8-8a9e-cf8a63fe3075')" rel="self" title="Contact"/>
        <content type="application/xml">
            <m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
                <d:ContactUUID>00163e58-21d4-1ed8-8a9e-cf8a63fe3075</d:ContactUUID>
                <d:FirstName>Vaasudeva</d:FirstName>
                <d:LastName>Swamy</d:LastName>
                <d:EmailAddress>vaasudeva@hybristest.com</d:EmailAddress>
                <d:PhoneNumber></d:PhoneNumber>
                <d:MobileNumber></d:MobileNumber>
                <d:CorporateAccountName>Kohli Store California</d:CorporateAccountName>
            </m:properties>
        </content>
    </entry>
    <entry>
        <id>https://my300011.s4hana.ondemand.com:443/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0002/Contacts(guid'00163e35-616b-1ed8-8a9e-cf43881e5a19')</id>
        <title type="text">Contacts(guid'00163e35-616b-1ed8-8a9e-cf43881e5a19')</title>
        <updated>2018-03-19T19:33:30Z</updated>
        <category term="API_MKT_CONTACT_SRV.Contact" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
        <link href="Contacts(guid'00163e35-616b-1ed8-8a9e-cf43881e5a19')" rel="self" title="Contact"/>
        <content type="application/xml">
            <m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
                <d:ContactUUID>00163e35-616b-1ed8-8a9e-cf43881e5a19</d:ContactUUID>
                <d:FirstName>Kanda</d:FirstName>
                <d:LastName>Swamy</d:LastName>
                <d:EmailAddress>kanda@hybristest.com</d:EmailAddress>
                <d:PhoneNumber></d:PhoneNumber>
                <d:MobileNumber></d:MobileNumber>
                <d:CorporateAccountName>Kohli Store California</d:CorporateAccountName>
            </m:properties>
        </content>
    </entry>
</feed>

Create and Update a Contact Record on SAP Hybris Marketing Cloud

Entity Path – ContactsOriginData

The ContactsOriginData entity allows us to create or update contact data from a defined source system. Further, retrieve Contact data from a specific Contact Origin from the yMKT system.

• An external system can create a new Contact on SAP Hybris Marketing using a defined Contact Origin
• An external system can update an existing Contact on SAP Hybris Marketing using a defined Contact Origin
• An external system can call the API to retrieve contacts data stored on Hybris Marketing for a specific Contact Origin like ERP Customer data, Hybris Consumer Data, or Twitter contact data.

Configure a SAP Cloud Platform Integration Iflow

We have built an example Iflow to cover the following scenarios:

• Create/Update Contact with PUT
• Update Contacts using PATCH/MERGE

Odata documentation – Chapter 2.6 Updating Entries: http://www.odata.org/documentation/odata-version-2-0/operations/
SAP Hybris Marketing Contact API – Contact Origin Data: https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1802%20500/en-US/06526bdbae42455ba69a4aef0750561b.html

The Iflow setup it pretty simple, most effort goes into defining the message mapping, to ensure we send a valid request message to SAP Hybris Marketing.

Demo: How to get the XML Schema file for the Message Mapping from the OData Adapter.

When to use what method?

When you implement your integration scenario you need to evaluate when to use what HTTP verb and provide a valid message.

• Use PATCH/MERGE when you want to partially update contact record.
• Use PUT when the contact record is a updated version of the existing contact record and you need to replace it.

First, we create a new Contact with PUT.

Contact create with PUT

{
	"batchParts": {
		"batchChangeSet": {
			"batchChangeSetPart": {
				"method": "PUT",
				"ContactOriginData": {
					"ContactOriginData": {
						"LastName": "Test",
						"FirstName": "Tom",
						"EmailAddress": "JHI_001@test.com",
						"Country": "US",
						"ContactPostalCode": "60611",
						"ContactOrigin": "SAP_ERP_CONTACT",
						"ContactID": "JHI_001",
						"CityName": "Chicago",
						"BirthDate": "2000-12-13",
						"OriginDataLastChgUTCDateTime": "0000-00-00T00:00:00"
					}
				}
			}
		}
	}
}

Contact update with PATCH/MERGE
Next, we update the Contact with PATCH/MERGE.
Here, the sender system only provides the information to be updated on SAP Hybris Marketing.

{
	"batchParts": {
		"batchChangeSet": {
			"batchChangeSetPart": {
				"method": "MERGE",
				"headers": {
					"header": {
						"headerName": "Sap-Cuan-SequenceID",
						"headerValue": "UpdatePatch"
					}
				},
				"ContactOriginData": {
					"ContactOriginData": {
						"EmailAddress": "TomTest@test.com",
						"ContactOrigin": "SAP_ERP_CONTACT",
						"ContactID": "JHI_001",
					"OriginDataLastChgUTCDateTime": "0000-00-00T00:00:00"
					}
				}
			}
		}
	}
}

Contact update with PUT
When Sending the same request with PUT, the contact record will be overwritten.

{
	"batchParts": {
		"batchChangeSet": {
			"batchChangeSetPart": {
				"method": "PUT",
				"ContactOriginData": {
					"ContactOriginData": {
						"EmailAddress": "TomTest@test.com",
						"ContactOrigin": "SAP_ERP_CONTACT",
						"ContactID": "JHI_001",
						"OriginDataLastChgUTCDateTime": "0000-00-00T00:00:00"
					}
				}
			}
		}
	}
}

Entity Path – MarketingPermissions

The MarketingParmission entity allows you to manage marketing permission and subscription information on the contact level.

• Public OData API (API_MKT_CONTACT)
• Entity set: MarketingPermissions
• https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1711%20500/en-US/06526bdbae42455ba69a4aef0750561b.html

Marketing Permissions Documentation:
https://help.sap.com/viewer/62cc88e5299040099390a257433adeb4/1802%20500/en-US/79b996a75b024dc3a7c02fcf755c3e12.html
There are different ways how you can import permission and subscription data. Here, we’re using the Contact Odata service to import permission and subscription data.

Note:
The examples shown here are describing the technical setup on how to import permission and subscription data and are performed on a test/demo system .

Example Iflow

Again, the main chuck of building the integration scenario is in the message mapping.
The configuration steps are same as for the other entities.

Example Requests

This section contains a couple example request and replies for:
API_MKT_CONTACT_SRV;v=0002/MarketingPermissions

Create Marketing Permission

The Contact must already exist in SAP Hybris Marketing to  create/update Marketing Permissions or Subscriptions.
In this example the contact opts-out for being contacted via E-Mail.

Request

POST /http/esmkt/MarketingOdataApi/ContactMarketingPermission HTTP/1.1
Host: XXXXX-iflmap.avtsbhf.eu1.hana.ondemand.com
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
	"batchParts": {
		"batchChangeSet": {
			"batchChangeSetPart": {
				"MarketingPermissions": {
					"MarketingPermission": {
						"ContactID": "JHI_001",
						"ContactOrigin": "SAP_HYBRIS_CONSUMER",
						"ContactPermissionID": "jhi_001@test.com",
						"ContactPermissionOrigin": "EMAIL",
						"MarketingArea": "",
						"CommunicationMedium": "EMAIL",
						"CommunicationCategory": "",
						"ContactPermission": "N",
						"PermissionUTCDateTime": "0000-00-00T00:00:00",
						"PermissionSourceCommMedium": "WEB",
						"CommunicationDirection": "O"
					}
				}
			}
		}
	}
}

Create Subscription

You need to create the Communication Category first in the “Communication Category and Limits” App on SAP Hybris Marketing Cloud.

SAP Hybris Marketing automatically distinguishes between opt-in/opt-out and subscribe/unsubscribe if the CommunicationCategory is provided or not.

Here, the contact Subscribes to a newsletter.

POST /http/esmkt/MarketingOdataApi/ContactMarketingPermission HTTP/1.1
Host: XXXXX-iflmap.avtsbhf.eu1.hana.ondemand.com
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
	"batchParts": {
		"batchChangeSet": {
			"batchChangeSetPart": {
				"MarketingPermissions": {
					"MarketingPermission": {
						"ContactID": "JHI_001",
						"ContactOrigin": "SAP_HYBRIS_CONSUMER",
						"ContactPermissionID": "jhi_001@test.com",
						"ContactPermissionOrigin": "EMAIL",
						"MarketingArea": "",
						"CommunicationMedium": "EMAIL",
						"CommunicationCategory": "1",
						"ContactPermission": "Y",
						"PermissionUTCDateTime": "0000-00-00T00:00:00",
						"PermissionSourceCommMedium": "WEB",
						"CommunicationDirection": "O"
					}
				}
			}
		}
	}
}

 Summary

The APIs provided provide a rich set of functionality and can be extended easily. Make sure to review the documentation before using the API and make yourself familiar using the APIs.
Useful documentation is referenced at the beginning of this blog post.

If you are still facing issues, you can always reach our to our Product Experts on the SAP Community.

• Expert Services
• SAP Community
• SAP Support Portal

You want to see more blogs from Expert Services? Click here