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 will provide a guide on how to setup SAP Marketing Cloud to receive Interactions, such as Posts from social media or product reviews, using SAP Cloud Platform Integration.
We will go through the basic configuration steps and basic Iflow design and help you to understand how to use the available APIs on SAP Marketing Cloud.
- Create interaction in SAP Marketing Cloud from Twitter
- Create and update integrations in SAP 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.
Resources
- Integration Guide SAP Marketing Cloud 1805 - Interactions at: https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1805.500/en-US/6322d15482854566a72f6c9f...
- URI Conventions (OData Version 2.0): https://www.odata.org/documentation/odata-version-2-0/uri-conventions/
Import Product Reviews to SAP Marketing Cloud
To give another example on another interaction type, we are creating product reviews and replicate the data to SAP Marketing Cloud. We are assuming that there is no pre-packaged content available from SAP and need to build a custom Iflow to create and update Interactions data.
Read Interaction Data from the API
You can read interaction data through the API once the Communication Arrangement for that specific services is configured.
Review the SAP Marketing Cloud API Documentation for available parameters and the OData documentation on how to apply those parameters.
Note: To get yourself familiar with the API you can test the APIs from https://api.sap.com/.
We have created a test contact with some interactions and interest items to demonstrate the GET requests.
| Request | GET /sap/opu/odata/sap/API_MKT_INTERACTION_SRV/$metadata HTTP/1.1 Host: my000000-api.s4hana.ondemand.com x-csrf-token: Fetch Authorization: Basic <Base64 encoded username and password> |
| Reply | Response Header: Set-Cookie →SAP_SESSIONID_AAA_100=1W0YHxaQMBfSXMKuuCbngS_xCFmOtRHohJ0AFj41YWs%3d; path=/; secure; HttpOnly x-csrf-token →O3uU-X98AdayKMTCJdjsGQ== For subsequent calls we are going to re-use the HTTP Session and access token |
| Request | GET /sap/opu/odata/sap/API_MKT_INTERACTION_SRV/Interactions/?$filter=InteractionSourceObject eq '111222333'&$select=InteractionUUID,InteractionContactId,InteractionContactOrigin,InteractionSourceObject,InteractionTimeStampUTC&$top=1&$inlinecount=allpages HTTP/1.1 Host: my000000-api.s4hana.ondemand.com x-csrf-token: O3uU-X98AdayKsadQ== |
| Reply | |
| Request | GET /sap/opu/odata/sap/API_MKT_INTERACTION_SRV/Interactions(guid'061abd30-e0ec-9949-1600-6d00ea9f7e2d')/InteractionInterests?$top=10&$inlinecount=allpages HTTP/1.1 Host: my000000-api.s4hana.ondemand.com x-csrf-token: O3uU-X98AdayKMTCJdjsGQ== |
| Reply | |
SAP Cloud Platform Integration (CPI) Configuration
Before configuring the Iflow on Cloud Platform Integration SAP Marketing Cloud communication needs to be configured.
In this scenario we are creating interactions in SAP Marketing Cloud using different services.
Procedure:
- 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
Create / Update a Product Review Interaction
Let's create a product review first. Our connected web shop triggers a message which is received on CPI and transformed to the message to the message structure expected from SAP Marketing Cloud.
The Interaction API (API_MKT_INTERACTION_SRV) provides functionalities to update interaction data.
To update an interaction you need to retrieve the uuid of the interaction to be updated first. This can be done from the Interaction API using filter criteria to identify an unique integration.
In our example the source interaction id (InteractionSourceObject) is defines as an unique identifier of the interaction.
Note: you can also use custom fields as filters.
Create an exchange property
You can use the Content Modifier integration pattern to modify the message body, header, and properties of a message at a specific point in the message processing.
We have created an exchange property saving the HTTP method used from the sender system in the request. The HTTP method is saved in the header field CamelHttpMethod.
Convert to XML
Most integration patterns used on CPI require XML formatted files. You can use one of the integration patterns provided to transform the inbound json message to xml.
Message Mapping
The message mapping is usually one of the most essential (also most complex) steps in the integration process. You can apply logic on field level to transform the messages using a graphical interface.
Reviewing the CPI Inbound and outbound message you will need some logic to populate all fields.
- Method: Since the method is not available in the inbound message payload there is no field that can be used for a field mapping.
We have saved the HTTP method in an exchange property which we can access by creating a custom function in the message mapping. - Code mappings: for mapping specific codes on CPI, you can create a Value Mapping to map codes between the source and target system.
The Value Mapping can be accessed using the standard function "Value Mapping" in the message mapping. - UUIDs: When not disabled, the UUID fields need to be mapped with a default value. See Considerations when creating Interactions with sub-entities.
| CPI Inbound Message (json) | |
| CPI Outbound Message (xml) | |
Routing the Message
Depending if this a create or an update, the message needs to be processed differently. The condition on the different branches can be done using a non-XML condition, referring to the value from the CamelHttpMethod header.
For the create branch, we mapped the message already to the correct structure and just need to send the message to SAP Marketing Cloud.
In case we have an update of an existing interaction, we need to enrich the message with the unique identifier of the interaction.
Define request parameters
In our example the source id of the product review is a unique identifier provided by the source system. This can be used to look up the InteractionUUID which was created on SAP Marketing Cloud when the interaction was initially created.
Content Enricher
With the content enricher you can enrich the message with information from an external service.
Here we are calling the Interaction API (API_MKT_INTERACTION_SRV) and define a query to filter for the correct Interaction
Query Options: $filter=InteractionSourceObject eq '${property.InteractionSourceObject}'&$select=InteractionUUID,InteractionContactId,InteractionContactOrigin,InteractionSourceObject,InteractionTimeStampUTC&$top=1
We selected "Enrich" as Aggregation Algorithm and defined the Path and Key Element of the original and lookup message.
With this configuration, the lookup values are added to the existing message.
| Content Enricher Inbound Message | |
| Content Enricher Outbound Message | |
Message Mapping
| CPI Inbound Message (json) | |
| CPI Outbound Message (xml) | |
Manage Interaction Sub-entities from a Product Review Update
When new objects are created on one of the sub-entities they need to be managed individually.
In this example a new Interest Item is added to the product review interaction.
Since this is an interaction update we can't use deep insert to attach sub-entities to the parent interaction. When creating an interaction without sub-entities, the InteractionUUID field can be disabled in the message mapping.
We could build a more complex mapping that can managed that use case and create a new batchChangeSetPart for every interaction sub-entity.
Here we decided to create a second branch and manage the import on interaction sub-entities in a separate Local Integration Process.
This extension of the Iflow only creates additional interest items, but depending on the object you're importing other functionalities, such as update and delete are available.
Please refer to the SAP Help documentation for further details.
.
Considerations when creating Interactions with sub-entities
When creating interactions with additional information such as Interaction Products, Interest Items, or Tags you can do this directly by attaching that information on one of the available sub-entities.
Note: The import of interactions data including sub-entities is a deep insert and is only available for creating interactions with sub-entities. Deep insert does not support an update of interactions and it's sub-entities.
Integration Guide SAP Marketing Cloud 1805 - Interactions at: https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1805.500/en-US/6322d15482854566a72f6c9f...
The integration developer needs to make sure that the message sent to SAP Marketing Cloud complies with the expected format.
One of the errors that was observed with many custom build scenario, was customers and partners getting error messages referring to invalid message payloads.
In this section we are going to review one specific error message regarding to importing interactions, especially when the interactions contains sub-entities.
Error Message excerpt:
com.thoughtworks.xstream.converters.ConversionException: OSCI issue : OSCI issue ---- Debugging information ---- message : OSCI issue cause-exception : com.sap.gateway.core.ip.processor.exception.ODataProcessingException cause-message : OSCI issue class : java.util.ArrayList required-type : java.util.ArrayList converter-type : com.sap.gateway.core.ip.processor.converter.ConverterXMLToList path : /batchParts/batchChangeSet/batchChangeSetPart/Interactions line number : 2 version : null -------------------------------, cause: org.apache.olingo.odata2.api.edm.EdmSimpleTypeException: The metadata do not allow a null value.
From the error message you can see that there is a issues with not allowing null values for specific element.
Reviewing the ODdata metadata you will find that the key ID fields can't be Null.
<Property Name="InteractionUUID" Type="Edm.Guid" Nullable="false" sap:unicode="false" sap:label="UUID" sap:updatable="false"/>
<Property Name="InteractionProductUUID" Type="Edm.Guid" Nullable="false" sap:unicode="false" sap:label="UUID" sap:creatable="false" sap:updatable="false"/>
In some use cases, e.g. when creating an interaction, the UUID is not available and can't be populated with the initial message. In that case the InteractionUUI can be disabled or populated with an "initial" guid as placeholder (see example below).
Note: Examples and description are created based on the Public OData API (API_MKT_INTERACTION_SRV) for Interactions.
This example is documented with Interaction Interests for easier presentation in the Contact Profile UI but also applies to other sub-entities.
Integration Guide SAP Marketing Cloud 1805 - Interactions at: https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1805.500/en-US/6322d15482854566a72f6c9f...
Import Interaction with/without Interest Item to SAP Marketing Cloud
For some interactions, you might not be require to attach additional information like interest items, tags, or products to the interaction.
Note:
You can suppress the InteractionUUID in the target structure for Interactions without sub-entities.
You need to send For the create branch initial uuids when sending interactions with sub-entities or updates.
This can be done in the message mapping or the sender system needs to provide the initial uuids.
Integration Guide SAP Marketing Cloud 1805 - Interaction API - Payload Examples
https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1805.500/en-US/b16a5be0aa124056af391fb8...
Import Interaction with Interest Item to SAP Marketing Cloud
Create Interaction without interest items
<?xml version="1.0" encoding="UTF-8"?>
<batchParts>
<batchChangeSet>
<batchChangeSetPart>
<method>POST</method>
<Interactions>
<Interaction>
<InteractionContactOrigin>SAP_HYBRIS_CONSUMER</InteractionContactOrigin>
<InteractionContactId>001</InteractionContactId>
<CommunicationMedium>ONLINE_SHOP</CommunicationMedium>
<InteractionType>PROD_REVIEW_CREATED</InteractionType>
<InteractionTimeStampUTC>2018-04-03T03:01:51</InteractionTimeStampUTC>
<SourceSystemType>COM</SourceSystemType>
<SourceSystem>SAP_MERCH_SHOP</SourceSystem>
<InteractionContent>Aggressive geometry paired with high-quality components.</InteractionContent>
</Interaction>
</Interactions>
</batchChangeSetPart>
</batchChangeSet>
</batchParts>Result on SAP Marketing Cloud with different payloads.
Create Interaction with multiple interest items
Initial guid is: 00000000-0000-0000-0000-000000000000
Initial uuid for InteractionInterestUUID is created in the CPI message mapping
This is an example request from CPI using the OData adapter to connect to the API_MKT_INTERACTION_SRV service.
<?xml version="1.0" encoding="UTF-8"?>
<batchParts>
<batchChangeSet>
<batchChangeSetPart>
<method>POST</method>
<Interactions>
<Interaction>
<InteractionInterests>
<InteractionInterest>
<ItemOfInterest>BIKE_BELL</ItemOfInterest>
<InteractionInterestUUID>00000000-0000-0000-0000-000000000000</InteractionInterestUUID>
</InteractionInterest>
<InteractionInterest>
<ItemOfInterest>BIKE_BAG</ItemOfInterest>
<InteractionInterestUUID>00000000-0000-0000-0000-000000000000</InteractionInterestUUID>
</InteractionInterest>
</InteractionInterests>
<InteractionUUID>00000000-0000-0000-0000-000000000000</InteractionUUID>
<InteractionContactOrigin>SAP_HYBRIS_CONSUMER</InteractionContactOrigin>
<InteractionContactId>JHI_001</InteractionContactId>
<CommunicationMedium>ONLINE_SHOP</CommunicationMedium>
<InteractionType>PROD_REVIEW_CREATED</InteractionType>
<InteractionTimeStampUTC>2018-04-03T03:27:44</InteractionTimeStampUTC>
<SourceSystemType>COM</SourceSystemType>
<SourceSystem>SAP_MERCH_SHOP</SourceSystem>
<InteractionContentSubject>001 Best Product ever!</InteractionContentSubject>
<InteractionContent>04/02 01 TEST via CPI Create.</InteractionContent>
</Interaction>
</Interactions>
</batchChangeSetPart>
</batchChangeSet>
</batchParts>Result in SAP Marketing Cloud
Watch the linked video for instructions how to check data load to SAP MArketing Cloud. Checking the Data Load in SAP Marketing Cloud: |
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 in this blog post.
If you are still facing issues, you can always reach out to our Product Experts on the SAP Community.
You want to see more articles from SAP Services? Click on the banner below.
Your SAP CX Services – Marketing Practice team.
- SAP Managed Tags:
2 Comments
| User | Count |
|---|---|
| 4 | |
| 3 | |
| 3 | |
| 2 | |
| 2 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 |
