In the SAP Marketing Cloud system, choose the Maintain Communication Users app, click New to create a new communication user. 26. PUBLIC. Integration Guide.
© 2021 SAP SE or an SAP affiliate company. All rights reserved.
Integration Guide | PUBLIC SAP Marketing Cloud 2021-11-05
Integration Guide
THE BEST RUN
Content
1
Overview of Integration Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2
Document History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3
Implementing Integrations for Business Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1 Business Scenario: Dynamic Customer Profiling and Segmentation. . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Business Scenario: Campaign and Journey Orchestration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3 Business Scenario: Commerce Marketing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.4 Business Scenario: Lead- and Account-Based Marketing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.5 Business Scenario: Marketing Planning and Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.6 Business Scenario: Marketing Analytics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Core Data Services-Based Extraction from SAP Marketing Cloud to SAP BW Systems. . . . . . . . . 24
Core Data Services-Based Extraction from SAP Marketing Cloud to Other SAP and Non-SAP Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Models for Core Data Service-Based Extractions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4
Integration Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
4.1 Overview of Integration Scenarios (Table). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.2 Inbound. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Commerce, Social Media, Web, and IoT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Landing Pages and Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Survey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.3 Outbound. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Sending Emails and Text Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Setting Up External Campaign Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Open Channel Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Mobile, Social, and Digital Channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Setting Up Captcha Configuration for Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
4.4 Application-Enabling Integrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Integrating Custom Themes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Integration with SAP Analytics Cloud (1SO). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Content Studio Integrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Enabling Geospatial Segmentation with here.com. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Integration with Baidu Maps for Geospatial Segmentation (Deprecated). . . . . . . . . . . . . . . . . . 318
SAP Jam Integration for Collaboration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Verifying Email Addresses Using a Partner Solution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Integration with an External Coupon Service System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
2
PUBLIC
Integration Guide Content
Partner Extension: Integrate with Digital Market Intelligence. . . . . . . . . . . . . . . . . . . . . . . . . . 330 Marketing Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330 4.5 Suite-Enabling Integrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Sales and Service (Inbound). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 Sales Automation (Outbound). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352 Financial Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Survey Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Personalized Commerce. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
5
Integration APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
5.1 Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387
Videos - Best Practices for Data Load. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .388
Quick Guide - Which API for Which Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
Consuming the Integration APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Extending the Integration APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Optimize Performance During OData Service Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Best Practices and Recommended Package Sizes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Import Monitor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Data Load Monitor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
HTTP Response Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
5.2 Contact Profiling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Contacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Interaction Contacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Corporate Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Business Partners from SAP Cloud for Customer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
Import Business Partners. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
Products. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
Product Hierarchies and Categories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
Interactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
Interest Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
Business Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Agreements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .681
Scores. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
Marketing Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Classifications (Deprecated). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
Marketing Attribute Categories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
Import Monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
5.3 Landing Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
External Landing Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .743
External Landing Page Value Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
5.4 Segmentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .754
Target Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
Integration Guide Content
PUBLIC
3
Export Target Groups and Target Group Member Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761 5.5 Campaign Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
Campaign and Target Group Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .761 Campaign Execution Plans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763 Campaigns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767 Campaign Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788 Campaign Message Content and Personalized Email Content. . . . . . . . . . . . . . . . . . . . . . . . . .793 Campaign Success Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812 Import Campaign Performance Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817 Survey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886 Read Content of Export Files in Campaigns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .901 Marketing Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .904 5.6 Commerce Marketing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 Recommendations (SAP Business Technology Platform). . . . . . . . . . . . . . . . . . . . . . . . . . . . .923 Recommendations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939 External Recommendations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954 Recommendations Interaction Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971 Import Offers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .973 Read Offers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002 Discover Offers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008 Coupons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026 5.7 Marketing Analytics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032 Import Analytical Data for Marketing Executive KPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033 5.8 Marketing Planning and Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040 Actual and Committed Spend Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1041 Marketing Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045 5.9 Custom Business Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1057 Import of Data into Custom Business Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057 5.10 Business Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058 Business User. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058 Business User - Read. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070 Business User - Read Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
6
Business Event Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1092
6.1 Campaign File Export. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1093
6.2 Campaigns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
6.3 Coupon Code Usages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
6.4 Interactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1096
6.5 Interaction Contacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097
6.6 Marketing Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
6.7 Marketing Subscriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
4
PUBLIC
Integration Guide Content
7
Integration Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101
8
Create Your Own Apps: SAP Rapid Application Development by Mendix. . . . . . . . . . . . . . . . 1102
Integration Guide Content
PUBLIC
5
1 Overview of Integration Options
This guide explains the different integration options with SAP Marketing Cloud. Its aim is to help you quickly find the documentation that will guide you through the integration process from wherever your integration journey starts.
Note
Before you start, make sure you have the required version of this document. You can find the available versions at the following location: https://help.sap.com/mkt
Note
In the PDF version of the guide, some links to topics may be missing. All links are available in the HTML version of the guide.
Integration Options
The graphic shows only the major integration options.
6
PUBLIC
Integration Guide Overview of Integration Options
Where to Find the Information You Need
Questions This Guide Answers
Read Me
Which business scenarios do I want to implement and how do I connect Learn more about the integration options from a
with the outside world?
marketing process perspective.
Implementing Integrations for Business Scenar ios [page 9]
How do I connect the marketing solution to an existing solution, for ex ample, to a Sales solution from SAP?
Find out how to bridge the gap between market ing and other business domains that are built on cloud or on premise solutions.
Integration Scenarios [page 49]
Which API should I use if I want to integrate a third-party data source that provides, for example, agreement, campaign, or contact informa tion?
Quick Guide - Which API for Which Entity [page 389]
Integration APIs [page 387]
Integration Guide Overview of Integration Options
PUBLIC
7
2 Document History
The following table provides an overview of the most important document changes.
Document History Date
Description
2021-10-27
Initial version for the Integration Guide 2111.
8
PUBLIC
Integration Guide Document History
3 Implementing Integrations for Business Scenarios
Overview of business scenarios, their scope items, related main and additional integration activities, as well as configuration and business administration activities.
A business scenario is a sequence of business processes designed to achieve key business objectives. A scope item is a self-contained and reusable entity of predefined content for the implementation of a business process. A business scenario can include one or more scope items.
You can find scope items in the Manage Your Solution application under View Solution Scope.
Note
You can use a business scenario only if its corresponding scope item is active in your system, that is, it has a green flag.
Scope items that are active in your system will only work if you have the required licenses and the integration to the corresponding application is implemented.
If a scope item is not active in your system, it has a gray sign. If you want to activate a scope item, contact SAP.
Integration of SAP Marketing Cloud with external systems can be achieved by using integration scenarios which are predelivered packages or by using integration services, such as public APIs.
Furthermore, communication scenarios are technical references used to enable the integration of SAP Marketing Cloud with external systems. A communication arrangement describes a communication scenario with a remote system during configuration time and provides the necessary metadata for service configuration.
The following business scenarios and scope items are available:
Business Scenario: Dynamic Customer Profiling and Segmentation [page 10] Scope Item: Consumer and Customer Profiling (JC1)
Business Scenario: Campaign and Journey Orchestration [page 11] Scope Item: Segmentation and Campaign Execution by Email (JC2) Scope Item: External Campaigns (JC9) Scope Item: Facebook Campaigns (JC6) Scope Item: Trigger-Based Campaigns and Trigger-Based Campaigns - with Abandoned Shopping Cart (JC8) Scope Item: Google Ads Campaigns (Assign) and Google Campaign Manager (Assign) (JC7) Scope Item: Asian Network Campaigns (23T) Scope Item: Permission Marketing (1T1) Scope Item: Marketing Events (3ZE)
Business Scenario: Commerce Marketing [page 16] Scope Item: Product Recommendation (JC3) Scope Item: Offer Recommendation (1SW)
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
9
Scope Item: Offer and Coupon Management in Marketing (1HQ) Offers with Coupons on Mobile App Offers with External Coupon Service Offer and Coupons with External Services
Business Scenario: Lead- and Account-Based Marketing [page 19] Scope Item: Marketing Lead Management (JC0) Scope Item: Marketing-Driven Sales Enablement (1SY) Scope Item: Marketing Lead Nurturing (2ZM)
Business Scenario: Marketing Planning and Performance [page 21] Scope Item: Marketing Planning (JC5)
Business Scenario: Marketing Analytics [page 23] Scope Item: Analytics Extensibility and Data Extraction (3SM)
3.1 Business Scenario: Dynamic Customer Profiling and Segmentation
Overview of the Dynamic Customer Profiling and Segmentation business scenario, its scope item, related main and additional integration activities, as well as configuration and business administration activities.
For information about the business scenario and its corresponding process steps, see Dynamic Customer Profiling and Segmentation.
Scope Item: Dynamic Customer Profiling (JC1)
Main Integration Activities You can perform the following main integration activities for this scope item:
Contacts [page 412] (SAP_COM_0207) integration service Interaction Contacts [page 469] (SAP_COM_0206) integration service Corporate Accounts [page 512] (SAP_COM_0207) integration service Enabling Geospatial Segmentation with here.com [page 317]
Additional Integration Activities Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item:
To import customer and contact data, as well as sales volume data like quotes, orders and returns, use the SAP ERP Integration with SAP Marketing Cloud (1KW) scope item with SAP_COM_0060 communication scenario. For more information, see SAP ERP Integration with SAP Marketing Cloud .
Integration with SAP Commerce (SAP_COM_0082) communication scenario and Integration with SAP Product Content Management (SAP_COM_0051) integration scenario. For more information, see Integration with SAP Commerce Cloud [page 62] and Integration with SAP Product Content Management [page 314].
10
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Google Analytics Integration (SAP_COM_0079) integration scenario. For more information, see Integration with Google Analytics [page 87].
SAP Customer Data Cloud Integration for Contacts and Accounts (SAP_COM_0264) integration scenario. For more information, see SAP Customer Data Cloud and SAP Marketing Cloud [page 338].
To integrate with SAP Cloud for Customer, the following integration scenarios are available: Integration with SAP Cloud for Customer - Inbound Channel [page 338] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
SAP S/4HANA Integration with SAP Marketing Cloud (23L) scope item. For more information, see SAP S/ 4HANA Integration with SAP Marketing Cloud .
To use scores with this business scenario, you must set up a predictive scenario with external score values. For more information, see Predictive Scenarios. The Scores (SAP_COM_0307) integration service is available. For more information, see Scores [page 700].
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
Contacts and Profiles Segmentation Configuration General Settings Map Free Texts Manage Interests Marketing Attribute Categories
3.2 Business Scenario: Campaign and Journey Orchestration
Overview of the Campaign and Journey Orchestration business scenario, its scope items, related main and additional integration activities, as well as configuration and business administration activities. For information about the business scenario and its corresponding process steps, see Campaign and Journey Orchestration.
Scope Item: Segmentation and Campaign Execution by Email (JC2)
Main Integration Activities for Sinch You can perform the following main integration activities for this scope item: Marketing Campaign Execution E-Mail Integration (SAP_COM_0040 for emails and SAP_COM_0041 for text
messages) integration scenario. For more information, see Setting Up Service Provider for Emails and Text Messages [page 110]. Enabling Geospatial Segmentation with here.com [page 317]
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
11
Main Integration Activities for Amazon
You can perform the following main integration activities for this scope item:
Marketing Campaign Execution E-Mail Integration (SAP_COM_0016 for emails and SAP_COM_0039 for bounces) integration scenario. For more information, see Setting Up Amazon [page 138].
Enabling Geospatial Segmentation with here.com [page 317]
Additional Integration Activities
Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item:
Marketing Campaign Open Channel Integration (SAP_COM_0049) integration scenario. For more information, see Open Channel Integration [page 194].
Marketing Generic DAM Integration (SAP_COM_0050) integration scenario. For more information, see Integrate with Content Management Systems or Digital Asset Management Systems [page 306] and Integrate with SAP Document Center [page 312].
Marketing SAP Product Content Management Integration (SAP_COM_0051) integration scenario. For more information, see Integration with SAP Product Content Management [page 314].
Marketing - Campaign Message Integration (SAP_COM_0208) integration service. For more information about exporting and importing message content for multiple languages, see Campaign Message Content and Personalized Email Content [page 793].
Marketing - Export File Content Integration (SAP_COM_0311) integration service. Fore more information about reading export file content in campaigns, see Read Content of Export Files in Campaigns [page 901].
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
Define Marketing Permission Check Activate Campaign Triggers Custom Business Objects Custom Fields in Segmentation Segmentation Configuration Workflow for Business Objects Sender Profiles [page 155] Managing Approval Workflows Verifying Email Addresses Using a Partner Solution [page 321]
Scope Item: Marketing Events (3ZE)
Main Integration Activities You can perform the following main integration activities for this scope item: Marketing - Marketing Events Integration (SAP_COM_0474) will be deprecated in a future release.
Marketing - Event Outbound Integration (SAP_COM_0541) and Marketing - Event Inbound Integration (SAP_COM_0371) integration scenarios. For more information, see in the integration flow guide Integrating Marketing Events Data with SAP Marketing Cloud under Create Communication Arrangement.
12
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
If event data is to be fetched from different event provider platforms, define ID origin using the ID Origin configuration application. For more information, see Configuring Origins.
If you want to create an event with a specific media type, for example, EVENTS, define media types using the Media Types configuration application. For more information, see Media Types.
If you want to assign an event to a specific marketing area, for example, GLOBAL, define marketing areas using the Marketing Areas configuration application. For more information, see Marketing Areas.
Create and schedule application jobs to import marketing events data from event provider platforms. For more information, see Marketing Events: Import Marketing Events.
Scope Item: External Campaigns (JC9)
Main Integration Activities You can perform the following main integration activities for this scope item: Marketing External Campaign Execution (SAP_COM_0037) integration scenario. For more information,
see Setting Up External Campaign Execution [page 155].
Additional Integration Activities Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item: Marketing Campaign Success Integration (SAP_COM_0390) integration service. For more information, see
Campaign Success Data [page 812].
Configuration and Business Administration Activities To set up this scope item, perform the following configuration and business administration activities: Define Marketing Permission Check Activate Campaign Triggers Custom Business Objects Custom Fields in Segmentation Segmentation Configuration
Scope Item: Facebook Campaigns (JC6)
Main Integration Activities You can perform the following main integration activities for this scope item: Marketing Campaign Execution Facebook Integration (SAP_COM_0031) integration scenario. For more
information, see Social Campaigns Using Facebook and Instagram [page 254].
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
13
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
Contacts and Profiles Campaigns General Settings Segmentation Configuration
Scope Item: Trigger-Based Campaigns and Trigger-Based Campaigns - with Abandoned Shopping Cart (JC8)
Main Integration Activities You can perform the following main integration activities for this scope item: Marketing Campaign Execution E-Mail Integration (SAP_COM_0016) integration scenario. For more
information, see Setting Up Service Provider for Emails and Text Messages [page 110].
Additional Integration Activities Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item: Marketing Landing Pages Integration (SAP_COM_0023) integration scenario. For more information, see
Custom Integration of Forms [page 92]. For the abandoned shopping cart process, the Marketing - SAP Commerce Data Integration
(SAP_COM_0082) integration scenario is required. For more information, see Integration with SAP Commerce Cloud [page 62].
Configuration and Business Administration Activities To set up this scope item, perform the following configuration and business administration activities: Define Marketing Permission Check Activate Campaign Triggers Custom Business Objects Custom Fields in Segmentation Segmentation Configuration Sender Profiles [page 155]
Scope Item: Google Ads and Google Campaign Manager Campaigns (JC7)
Main Integration Activities You can perform the following main integration activities for this scope item: Marketing - Google Ads Integration (SAP_COM_0030) integration scenario. For more information, see
Integration with Google Ads [page 243].
14
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Marketing - External Campaign Integration (SAP_COM_0037). For more information, see Integration with Google Campaign Manager [page 259].
Scope Item: Asian Network Campaigns (23T)
Main Integration Activities for WeChat Campaigns For the WeChat Campaigns variant of this scope item, perform the following main integration activities: Marketing Network Channel Events Integration (SAP_COM_0174) integration scenario Marketing Campaign Execution WeChat Integration (SAP_COM_0085) integration scenario Marketing Baidu Map Integration (SAP_COM_0075) integration scenario
Configuration and Business Administration Activities for WeChat Campaigns Perform the following configuration and business administration activities: Create WeChat official accounts. Create and schedule application jobs. Activate the All China Consumers (B2C) segmentation profile. For more information, see WeChat Integration [page 65] and Integration with Baidu Maps for Geospatial Segmentation (Deprecated) [page 318].
Main Integration Activities for LINE Campaigns For the LINE Campaigns variant of this scope item, perform the following main integration activities: Marketing Network Channel Events Integration (SAP_COM_0174) integration scenario Marketing Campaign Execution LINE Integration (SAP_COM_0218) integration scenario
Configuration and Business Administration Activities for LINE Campaigns Perform the following configuration and business administration activities: Create LINE accounts. Create and schedule application jobs. For more information, see LINE Integration [page 77].
Scope Item: Permission Marketing (1T1)
Main Integration Activities You can perform the following main integration activities for this scope item: Marketing Campaign Execution E-Mail Integration (SAP_COM_0016) integration scenario. For more
information, see Setting Up Service Provider for Emails and Text Messages [page 110].
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
15
Additional Integration Activities
Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item:
Marketing Form Integration (SAP_COM_0023) integration scenario. For more information, see Custom Integration of Forms [page 92].
Marketing - Form Publication Integration (SAP_COM_0148) integration scenario. For more information, see Form Publication [page 105].
Marketing - SAP BTP Landing Page Publication Integration(SAP_COM_1074) integration scenario. For more information, see Landing Page Design.
Marketing SAP BTP Form Integration (SAP_COM_1041) integration scenario. For more information, see Standard Integration of Forms [page 102].
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
Contacts and Profiles Configuration for Permission Marketing Campaigns General Settings Sender Profiles [page 155] Segmentation Configuration
3.3 Business Scenario: Commerce Marketing
Overview of the Commerce Marketing business scenario, its scope items, related main and additional integration activities, as well as configuration and business administration activities. For information about the business scenario and its corresponding process steps, see Commerce Marketing.
Scope Item: Product Recommendation (JC3)
Main Integration Activities
You can perform the following main integration activities for this scope item:
Contacts [page 412] (SAP_COM_0207) integration service Interactions [page 615] (SAP_COM_0206) integration service Interaction Contacts [page 469] (SAP_COM_0207) integration service Corporate Accounts [page 512] (SAP_COM_0207) integration service Marketing - Recommendations (SAP_COM_1043) integration scenario. For more information, see
Recommendations (SAP Business Technology Platform) [page 923]. Marketing - Recommendations Integration (SAP_COM_0019) integration scenario. For more information,
see Recommendations [page 939].
16
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Additional Integration Activities
Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item:
Marketing - SAP Commerce Data Integration (SAP_COM_0082) integration scenario. For more information, see Integration with SAP Commerce Cloud [page 62].
Integration with SAP Product Content Management [page 314] (SAP_COM_0207) integration service. External Recommendations Integration (SAP_COM_0300) integration service. For more information, see
External Recommendations [page 954]. Recommendations Interaction Data [page 971]
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
Recommendation Algorithms Recommendation Data Source Pre-Filters
Scope Item: Offer Recommendation (1SW)
Main Integration Activities You can perform the following main integration activities for this scope item: Marketing - Offer Integration (SAP_COM_0020) integration service. For more information, see Import Offers
[page 973].
Additional Integration Activities Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item: Marketing - Offer Discovery Integration (SAP_COM_0021) integration service. For more information, see
Discover Offers [page 1008]. Marketing - SAP Commerce Data Integration (SAP_COM_0082) integration scenario. For more information,
see Integration with SAP Commerce Cloud [page 62]. External Recommendations Integration (SAP_COM_0300) integration service. For more information, see
External Recommendations [page 954].
Scope Item: Offer and Coupon Management in Marketing (1HQ)
Main Integration Activities for Offers with Coupons on Mobile App You can perform the following main integration activities for the Offers with Coupons on Mobile App variant of this scope item: Contacts [page 412] (SAP_COM_0207) integration service Interaction Contacts [page 469] (SAP_COM_0206) integration service Corporate Accounts [page 512] (SAP_COM_0207) integration service
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
17
Marketing - Offer Integration (SAP_COM_0020) integration service. For more information, see Import Offers [page 973].
Marketing - Mobile Channel in Campaign Management (SAP_COM_0061) integration scenario. For more information, see Mobile App Integration with Google Firebase [page 244].
Additional Integration Activities for Offers with Coupons on Mobile App
Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for the Offers with Coupons on Mobile App variant of this scope item:
Marketing - Offer Discovery Integration (SAP_COM_0021) integration service. For more information, see Discover Offers [page 1008].
Marketing - Marketing Location Integration (SAP_COM_0305) Offer for wallet use case (SAP_COM_0306) Marketing - Mobile Channel - Inbound Interactions with Campaign Reference (SAP_COM_0169)
Main Integration Activities for Offers with External Coupon Service
You can perform the following main integration activities for the Offers with External Coupon Service variant of this scope item:
Marketing - External Coupon Management Service Integration (SAP_COM_0286) integration scenario. For more information, see Integration with an External Coupon Service System [page 321].
Marketing - Coupon Integration (SAP_COM_0317) integration scenario. For more information, see Coupons [page 1026].
Marketing - Campaign Execution - Shared Mobile Services E-Mail Integration (SAP_COM_1025) integration scenario.
Additional Integration Activities for Offers with External Coupon Service
Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for the Offers with External Coupon Service variant of this scope item:
Marketing - Offer Discovery Integration (SAP_COM_0021) integration service. For more information, see Discover Offers [page 1008].
Marketing - Offer Integration (SAP_COM_0020) integration service. For more information, see Import Offers [page 973]. The following integration scenarios provide APIs for dependent offer objects such as products, target groups, or marketing locations. For example, you can first import products and then assign the imported products to an imported offer. Marketing - Target Group UI Integration (SAP_COM_0205). For more information, see Target Groups [page 755]. Marketing - Marketing Location Integration (SAP_COM_0305). For more information, see Marketing Locations [page 710].
Main Integration Activities for Offer and Coupons with External Services
You can perform the following main integration activities for the Offers and Coupons with External Services variant of this scope item:
Marketing - External Coupon Management Service Integration (SAP_COM_0286) integration scenario. For more information, see Integration with an External Coupon Service System [page 321].
18
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Marketing - Coupon Integration (SAP_COM_0317) integration scenario. For more information, see Coupons [page 1026].
Marketing - Campaign Execution - Shared Mobile Services E-Mail Integration (SAP_COM_1025) integration scenario.
Martketing - Interaction UI Integration (SAP_COM_0206) integration service.
Additional Integration Activities for Offer and Coupons with External Services
Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for the Offers amd Coupons with External Services variant of this scope item:
Marketing - Offer Discovery Integration (SAP_COM_0021) integration service. For more information, see Discover Offers [page 1008].
Marketing - Offer Integration (SAP_COM_0020) integration service. For more information, see Import Offers [page 973]. The following integration scenarios provide APIs for dependent offer objects such as products, target groups, or marketing locations. For example, you can first import products and then assign the imported products to an imported offer. Marketing - Target Group UI Integration (SAP_COM_0205). For more information, see Target Groups [page 755]. Marketing - Marketing Location Integration (SAP_COM_0305). For more information, see Marketing Locations [page 710].
3.4 Business Scenario: Lead- and Account-Based Marketing
Overview of the Lead Management and Nurturing business scenario, its scope items, related main and additional integration activities, as well as configuration and business administration activities. For information about the business scenario and its corresponding process steps, see Lead- and AccountBased Marketing.
Scope Item: Marketing Lead Management (JC0)
Main Integration Activities
For the Lead Campaign feature of this scope item, you need to integrate with SAP Cloud for Customer or with SAP Customer Relationship Management (SAP CRM). For more information, see: SAP Cloud for Customer Integration with SAP Marketing Cloud . The following information on integration
scenarios is available: Integration with SAP Cloud for Customer - Inbound Channel [page 338] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
19
SAP CRM Integration with SAP Marketing Cloud . The following information on integration scenarios is available: Integration with SAP CRM - Inbound Channel [page 342] Integration with SAP CRM - Outbound Channel [page 354]
For the Call Qualifications feature of this scope item, you can integrate with SAP Cloud for Customer. For more information, see SAP Cloud for Customer Integration with SAP Marketing Cloud . The following information on integration scenarios is available:
Integration with SAP Cloud for Customer - Inbound Channel [page 338] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
Additional Integration Activities
Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item:
UI Integration with SAP Cloud for Customer (SAP_COM_0045) integration scenario, for navigation from contacts to sales system
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
Optionally, you can set up the workflow. Workflow for Business Objects
In case you have activated more than one communication arrangement, that is, you have configured more than one target system, the Business Add-In (BAdI) Lead Management: Determine Target System Type is performed. With the Custom Logic app, you can implement the BAdI. You define the target system type (either SAP_C4C or SAP_CRM) depending on different attributes of the contact that is currently in process. The BAdI is performed once for each member of the target group. That is, you define in which target system the correspondings leads or activities are created.
Scope Item: Marketing-Driven Sales Enablement (1SY)
Main Integration Activities For the Activity for Sales feature of this scope item, you need to integrate with SAP Cloud for Customer or with SAP CRM.
For more information, see:
SAP Cloud for Customer Integration with SAP Marketing Cloud . The following information on the integration scenarios is available: Integration with SAP Cloud for Customer - Inbound Channel [page 338] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
SAP CRM Integration with SAP Marketing Cloud . The following information on the integration scenarios is available:
Integration with SAP CRM - Inbound Channel [page 342] Integration with SAP CRM - Outbound Channel [page 354]
For the Sales Insights on Marketing Campaigns feature of this scope item, you need to integrate with SAP Cloud for Customer.
20
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
For more information, see SAP Cloud for Customer Integration with SAP Marketing Cloud information on the integration scenarios is available:
Integration with SAP Cloud for Customer - Inbound Channel [page 338] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
. The following
Additional Integration Activities
Depending on your business needs and the business scenarios and scope items you want to use, you might have to perform the following additional integration activities for this scope item:
UI Integration with SAP Cloud for Customer (SAP_COM_0045) integration scenario, for navigation from contacts to sales system
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
Optionally, you can set up the workflow. Workflow for Business Objects
For the feature Sales Insights on Marketing Campaigns , you have to activate the campaign transfer. Campaigns: Transfer Campaigns to Sales
Scope Item: Marketing Lead Nurturing (2ZM)
The Lead Nurture feature uses email campaigns and lead campaigns (optional). To use this scope item, please refer to the following dependent scope items: Scope Item: Segmentation and Campaign Execution by Email (JC2) [page 11]: To design the stream and
run email campaigns. Scope Item: Marketing Lead Management (JC0) [page 19] (optional): Only if you want to transfer the
qualified leads to sales.
3.5 Business Scenario: Marketing Planning and Performance
Overview of the Marketing Planning and Performance business scenario, its scope item, related main integration activities, as well as configuration and business administration activities. For information about the business scenario and its corresponding process steps, see Marketing Planning and Performance.
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
21
Scope Item: Marketing Planning (JC5)
Main Integration Activities
You can perform the following main integration activities for this scope item:
Marketing - Business Data Integration (SAP_COM_0004) integration service. For more information, see Importing Actual and Committed Spend from SAP ERP [page 382].
Marketing - Planning Spends Integration (SAP_COM_0018) integration scenario. For more information, see Integration with SAP ERP for Spend Planning [page 379].
Configuration and Business Administration Activities
To set up this scope item, perform the following configuration and business administration activities:
1. If custom dimensions are going to be used for budget planning, define them using the Custom Dimensions configuration application. For more information, see Custom Dimensions.
2. If you defined custom dimensions, define or import custom dimension values in the system from a comma-separated value (CSV) file in the Custom Dimension Values business administration application. For more information, see Custom Dimension Values.
3. If brand is going to be used as a dimension for budget planning, define or import brands in the system from a comma-separated value (CSV) file in the Brands business administration application. For more information, see Brands.
4. If market is going to be used as a dimension for budget planning, define markets and assign countries to markets using the Markets configuration application. For more information, see Markets.
5. If audience is going to be used as a dimension for budget planning, define or import audiences using the Audiences business administration application. For more information, see Audiences.
6. If planning is going to be done for different media types, define media types using the Media Types configuration application. For more information, see Media Types.
7. Define marketing areas using the Marketing Areas configuration application. For more information, see Marketing Areas.
8. Define planning models using the Planning Models configuration application. For more information, see Planning Models.
9. If you want to restrict the values that can be used for budget plans in budget planning, define dimension relationships using the Dimension Relationships business administration application. For more information, see Dimension Relationships.
10. If you defined custom dimensions or if you want to change the labels for the standard dimensions, define labels for dimensions using the Labels for Dimensions and Measures configuration application. For more information, see Labels for Dimensions and Measures.
11. If you want to change the labels for the standard measures, define labels for measures using the Labels for Dimensions and Measures configuration application. For more information, see Labels for Dimensions and Measures.
12. Define the actual spend data you want to display in planning using the Actual Spend and Ad Serving Cost configuration application. For more information, see Actual Spend and Ad Serving Cost.
13. Define spend types using the Spend Types configuration application. For more information, see Spend Types.
14. Activate workflow for business objects using the Workflow for Business Objects configuration application. For more information, see Workflow for Business Objects.
15. Define workflows for marketing approvals using the Manage Workflows business administration application. For more information, see Managing Approval Workflows.
22
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
16. Activate change log for business objects using the Change Log configuration application. For more information, see Change Log.
17. Activate snapshots for business objects using the Snapshots for Business Objects configuration application. For more information, see Snapshots for Business Objects.
3.6 Business Scenario: Marketing Analytics
Overview of the Marketing Analytics business scenario, its scope items, and related main integration activities. For information about the business scenario and its corresponding process steps, see Marketing Analytics.
Scope Item: Analytics Extensibility and Data Extraction (3SM)
Analytics Extensibility These are the available extensibililty options for this scope item. To learn more about the two types of integration and which one you have, see Setup of SAP Analytics Cloud, Embedded Edition/SAP Analytics Cloud. Create Custom Analytics Stories
For more information, see Create Custom Stories, SAP Analytics Cloud and Create Custom Stories, SAP Analytics Embedded Edition. Create Custom Operational Reports For more information, see Custom Operational Reports.
Core Data Services (CDS)-Based Data Extraction You can perform the following main integration activities for this scope item: Core Data Services-Based Data Extraction from SAP Marketing Cloud to SAP BW Systems
For more information, see Setting Up Analytics Extensibility and Data Extraction. For more information, see Core Data Services-Based Extraction from SAP Marketing Cloud to SAP BW Systems [page 24]. Core Data Services-Based Data Extraction from SAP Marketing Cloud to Other SAP and Non-SAP Systems For more information, see Core Data Services-Based Extraction from SAP Marketing Cloud to Other SAP and Non-SAP Systems [page 25]. For more information, see Cloud Data Integration API [page 30].
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
23
3.6.1 Core Data Services-Based Extraction from SAP Marketing Cloud to SAP BW Systems
This procedure helps you set up the Core Data Services-Based Extraction from SAP Marketing Cloud to an SAP BW system.
Context
BW Modeling Tools installation
SAP HANA Studio with BW Modeling Tools must be installed on the local PC to perform the setup. For more information, see Install BW Modeling Tools.
Object List
Ensure that the following objects have been created in prerequisites setup instructions. There may be different names based on different system environment, you can ask for them from Administrators who performed the setup.
Object Source System DataSource DataStore Object Data Transfer Process
Name
<system ID>-<client> IMKTTG_DS IMKTTGDSO DTP-Full RSDS IMKTTG_DS <system ID>-<client> ADSO > IMKTTGDSO
Procedure
1. Verify the source system. a. Open SAP BW/4HANA, and log on to SAP BW/4HANA system.
You successfully logged on, and SAP Easy Access page is displayed. b. Access the BW Workbench, and run TCode RSA1.
The Process Chain Display Planning View page is displayed. c. In the Source System panel, expand ODP ABAP CDS Views and find the source system XXX that you
created in set-up instructions or you're required to test in your own scenario.
The source system is displayed. d. Right-click the source system and choose Check.
Source system connection XXX OK is displayed at the bottom of the screen. 2. Verify the data flow.
a. Open the SAP HANA studio, and navigate to the SAP BW/4HANA system using the BW Modeling Perspective.
24
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
You've successfully opened the SAP BW/4HANA project. b. In the Data Sources node, expand the ABAP CDS Views folder and then expand the source system.
Check if data source (for example, IMKTTG_DS) exists and activated.
The Data Source IMKTTG_DS is displayed. c. In the BW Repository node, expand the NODESNOTCONNECTED folder and then expand the DataStore
Object (advanced) folder. Check if DSO (for example, IMKTTGDSO) exists and activated.
The Data Store Object IMKTTGDSO is displayed. d. In the DataStore Object (advanced) > IMKTTGDSO node, expand the Data Transfer Process folder and
check if DTP (for example, DTP-Full RSDS IMKTTG_DS <system><client> > ADSO IMKTTGDSO) exists and activated.
The Data Transfer Process DTP-Full RSDS IMKTTG_DS <system><client> > ADSO IMKTTGDSO is displayed. 3. Verify the extracted data. a. Open the SAP HANA studio, and navigate to the SAP BW/4HANA system using the BW Modeling Perspective.
You've successfully opened the SAP BW/4HANA project. b. Open DSO IMKTTGDSO and navigate to Properties DDIC tab. Choose /BIC/AXXX1 link beside Active
Table.
The SAP BW/4HANA screen is opened in a new page. c. On the Dictionary: Display Table screen, choose Contents. In the Select Fields for Selection screen,
check Target Group field according to your own scenario and then choose Execute.
The Data Browser page (SE16) is displayed. d. On the Data Browser screen, choose Number of Entries. If data exists in source system, the result must
be XX.
The extracted data records are displayed.
If you are interested to figure out which CDS Views are capable of extracting data from SAP Marketing Cloud into the desired target system, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud
3.6.2 Core Data Services-Based Extraction from SAP Marketing Cloud to Other SAP and Non-SAP Systems
This section provides information on how to extract data from an SAP Marketing Cloud system to other SAP and non-SAP systems using the SAP Cloud Data Integration (CDI) API.
The previous section, Core Data Services-Based Extraction from SAP Marketing Cloud to SAP BW Systems [page 24] explains data extraction from an SAP Marketing Cloud system to SAP BW systems while this section deals with data extraction to other SAP and non-SAP systems.
You can extract data from an SAP Marketing Cloud system to other SAP and non-SAP systems using the communication scenario SAP_COM_0531.
The CDI API enables data extraction from SAP Marketing Cloud to be consumed via an ODataV4 endpoint. You must implement the ODataV4 client for consuming the CDI API services using one of the following:
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
25
SAP Cloud Integration (SCI) (Deprecated) SAP Data Intelligence (Data Hub) SAP Smart Data Integration (SDI)
Note
SAP Cloud Integration (SCI) has been deprecated, because only SAP Smart Data Intelligence (DI) or SAP Data Intelligence (Data Hub) is the standard platform for data integration, whereas SCI is positioned as middleware for process integration on SAP BTP.
Note
Consumption of the CDI API services in a non-SAP is supported system only using the above-listed services. For more information, see Cloud Data Integration API [page 30].
Prerequisites
You have to create a communication arrangement for the communication scenario SAP_COM_0531. Creating a communication arrangement is required on SAP Marketing Cloud irrespective of the consuming channel, that is, Data Hub, or SAP SDI.
Set Up the Communication Arrangement on SAP Marketing Cloud
To access the CDI API services, complete the following steps on SAP Marketing Cloud.
Create a Communication User A technical user is required to access the CDI API services. This user is a special user used for data extraction purposes. 1. Log in to the SAP Marketing Cloud system as an Administrator. 2. In the SAP Marketing Cloud system, choose the Maintain Communication Users app, click New to create a
new communication user.
26
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
3. Enter the User Name, Description, and Password (either enter a password manually or use the proposed password). Click Create.
Note
The certificate upload isn't mandatory for this scenario.
Create a Communication System The connection management needs to know in which system the connection is being set up, hence a communication system has to be created. 1. Log in to the SAP Marketing Cloud system as an Administrator. 2. Open SAP Marketing Cloud in a new browser window. In the Communication Systems app, click New to
create a new communication system.
3. Enter a System ID and System Name for your communication system, and choose Create.
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
27
4. On the Communication System page, under Technical Data, enter the following: 1. Host Name: If host name not required then System ID is sufficient. Host Name is required when the connection needs to be set up with third-party system and its Host ID is required. 2. Logical System: Not required. 3. Port: Default port is 443. Don't change the port number.
5. Under Users for Inbound Communication, choose + button. 6. In the New Inbound Communication User pop-up screen, enter the User Name and select User Name and
Password option for Authentication Method, and then click OK.
7. On the Communication System page, choose Save.
Create Communication Arrangement
To access the CDI API services, a communication arrangement is required. The communication arrangement generates the service endpoints and assigns the right authorization roles required to access the provider data.
Use the Communication Scenario ID SAP_COM_0531 to create a communication arrangement. While creating a communication arrangement, the authorizations required to access the CDI API services are granted to the communication user from the communication scenario role SAP_COM_0531. With the creation of communication arrangement, the service endpoints are exposed with the communication user and are ready for consumption.
1. Log in to the SAP Marketing Cloud system as an Administrator. 2. In the SAP Marketing Cloud system, choose the Communication Arrangements app, click New to create a
new arrangement.
28
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
3. In the New Communication Arrangement pop-up screen, enter the scenario SAP_COM_0531 and click Create.
4. Enter the Communication System that you defined while setting up a Communication System, and click Save. Once the communication system is saved, the two ODataV4 service groups (Cloud Data Integration (CDI) and Cloud Data Integration for Core Data Services (CDI_CDS)) are populated on the Communication Arrangements page, under Inbound Services.
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
29
Note
Upon creation of Communication Arrangement service, the service endpoints aren't listed but only OData groups are listed as shown. To access the CDI admin service endpoint, you must fetch the URL in the following way: <Host>/<Service Path> where, <Service Path> is /sap/opu/ odata4/sap/cdi/default/sap/cdi/0001/.
This communication arrangement is a customer-managed Communication Arrangement, so the certificate is optional. You must append `-api' to the uri host, to make a successful call from the client system as shown: https://myXXXXXXX-api.s4hana.ondemand.com/sap/opu/odata4/sap/cdi/ default/sap/cdi/0001/. Once the admin service endpoint is accessible, you can fetch the service path for each of the providers with a GET call to the provider EntitySet as shown: <Host>/sap/opu/ odata4/sap/cdi/default/sap/cdi/0001/Providers.
For more information on the CDI API, see Cloud Data Integration API [page 30].
Related Information
For an overview of CDS-based data extraction in SAP Marketing Cloud, see the blog: CDS-Based Data Extraction - An Overview
For a general overview of CDS-based data extraction, see CDS-Based Data Extraction - An Overview If you are interested to figure out which CDS Views are capable of extracting data from SAP Marketing
Cloud into the desired target system, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud
3.6.2.1 Cloud Data Integration API
This section provides the technical information of the Cloud Data Integration (CDI) API. To access the CDI admin service endpoint, you must fetch the URL in the following way: <Host>/<Service Path> where, <Host> is the SAP Marketing Cloud host similar to https://myXXXX-api.s4hana.ondemand.com and <Service Path> is /sap/opu/odata4/sap/cdi/default/sap/cdi/0001/.
30
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Accordingly, the service endpoint URL is: https://myXXXXXXX-api.s4hana.ondemand.com/sap/opu/ odata4/sap/cdi/default/sap/cdi/0001/.
The response to the service endpoint call consists of the following entity sets:
{ "@odata.context": "$metadata", "value": [ { "name": "Namespaces", "url": "Namespaces" }, { "name": "Providers", "url": "Providers" }, { "name": "Subscriptions", "url": "Subscriptions" } ] }
Entity Sets
The following are the CDI API Entity Sets:
Namespaces: For SAP Marketing Cloud, the ABAP CDS Views are the applicable namespaces. Providers: Providers are the different CDS Views that have been enabled for extraction. In SAP Marketing
Cloud, all the CDS Views that start with the naming convention I_MKT_* or C_MKT_* are the providers. GET /sap/opu/odata4/sap/cdi/default/sap/cdi/0001/Providers { "NamespaceID": "ABAP_CDS", "ProviderID": "I_MKT_CONTACTFACETDATA_2", "Description": "Marketing: Contact Facet Data", "ServiceURL": "/sap/opu/ odata4/sap/cdi_cds/cdi_cds/sap/i_mkt_contactfacetdata_2/0001/" } GET /sap/opu/odata4/sap/cdi_cds/cdi_cds/sap/i_mkt_contactfacetdata_2/0001/ Based on the type of CDS View, the corresponding entity set is displayed, for example the MasterData, Facets, etc. { "@odata.context": "$metadata", "value": [ { "name": "MasterData", "url": "MasterData" } ] } The provider-specific OData service contains the entity set with data access. The client can access the list of columns accessed by sending a GET request to <serviceRoot>/$metadata. GET /sap/opu/odata4/sap/cdi_cds/cdi_cds/sap/ i_mkt_contactfacetdata_2/0001/$metadata provides the service metadata. Subscriptions: There can be (0: N) subscriptions for a provider. This information is required for delta extraction scenario. The CDS Views advertise their change-tracking capabilities by annotating entity sets with the Capabilities.ChangeTracking term. The client requests the service track changes by specifying track-changes preference on a request in the Prefer header. Prefer: odata.track-changes If supported for the request, the service includes a Preference-Applied header in the response containing the track-changes preference and includes a delta link on the last page of results. A subscription is created implicitly by accessing the provider data with odata.track-changes enabled. The Subscriptions are stopped via a DELETE call to the Subscriptions entity set. It's possible to create a subscription explicitly via a POST call. In this case, the client can set an external ID. The currentDeltaLink and the previousDeltaLink are calculated by the server. Deletion of Subcriptions Subscriptions can be deleted with a DELETE request specifying the NameSpaceID, ProviderID, and SubscriptionID key fields.
Note
The key fields must be part of the URI when delete operation is performed as shown <Serv_path>/ EntitySet (NamespaceID='ABAP_CDS',ProviderID='ProviderID#',SubscriptionID=' SubscriptionID#'). Since the DELETE request is a Modify operation for EntitySet, the CSRF token is fetched before performing the actual delete call.
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
31
Provider Data Access
Data Preview: A GET call to the EntitySet of a provider URL with top and/or skip fetches the data in preview mode. For example, <Host>/<Serv_path>/EntitySet?$top=2&$skip=1.
Full Mode: A GET call to the EntitySet of a provider URL fetches the data in preview mode. For example, <Host>/<Serv_path>/EntitySet. In the GET <HOST>/sap/opu/odata4/sap/cdi_cds/cdi_cds/sap/ i_mkt_contactfacetdata_2/0001/MasterData call along with the header information Prefer: odata.maxpagesize=<pagesize>, you can set the desired pagesize for pagination. The @odata.nextLink contains the link to fetch the next set of entries.
Delta Mode: A GET call to the EntitySet of a provider URL with header fetches the data in Delta mode. The first fetch is delta init and the delta link is provided at the end of payload. Use this link to make subsequent calls to retrieve Deltas only. For example, <Host>/<Serv_path>/EntitySet with Header Prefer: odata.track-changes The response is similar to the following with the data ending with delta link as shown: "@odata.deltaLink" : "<Serv_path>/EntitySet? $deltatoken=D_KJKAAPANFEPNVANLRAZBI3KCHM" This action results in implicit subscription creation for provider.
Note
Delta mode can be used along with the pagesize attribute. If the specified pagesize is smaller than the data, the response contains data along with a link to the next page and the subsequent requests fetch the data from the next pages. During the last page fetch, the delta link is returned.
3.6.3 Models for Core Data Service-Based Extractions
CDS Modeling: Campaign and Campaign Performance [page 33] Overview of the data model that illustrates the relationships between the CDS views for campaign and campaign performance.
CDS Modeling: Contacts and Profiles [page 34] Models available to show relationships between CDS views for data extraction.
CDS Modelling: Marketing Events and Event Participants [page 37] Overview of the data model that illustrates the relationships between the CDS views for marketing events and event participants.
CDS Modeling: Marketing Planning [page 40] Models available to show relationships between CDS views for data extraction.
CDS Modeling: Scores and Predictive Studio [page 45] Overview of CDS views that are modeled according to the relationships between the different entities of scores.
32
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
3.6.3.1 CDS Modeling: Campaign and Campaign Performance
Overview of the data model that illustrates the relationships between the CDS views for campaign and campaign performance.
Prerequisites
For information regarding prerequisites, see Business Scenario: Marketing Analytics [page 23] and open the collapsible section titled Core Data Services (CDS)-Based Data Extraction.
Technical Details
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
33
Anno tations Description
1 The I_MKT_AssgdCmpgnSuccessData view contains the actual campaign performance data in the date level. You can aggregate the data into the campaign level and compare with the target defined in the I_MKT_CampaignTarget view. The view also contains additional dimensions, for example, gender, age, and country/region.
2 The I_MKT_CampaignTarget view contains the defined performance target in the campaign level.
(K) Represents key fields.
Note
The different version of campaign generated by the snapshot functionally of the marketing plan application can be extracted from the I_MKT_InitiativeVersion / I_MKT_CampaignTargetVersion CDS view. The MktgObjVersHdrUUID field identifies the snapshot version. And the CDS view I_MKT_ObjectVersionHeader gives the information on the snapshot version.
The purpose of this diagram is to show how the CDS views for Campaigns and Campaign Performance are linked together to form a model. The complete CDS view definitions, including all of the available fields can be viewed in the View Browser application.
Released CDS Views that are enabled for data extraction contain the following annotation: @Analytics.dataextraction.enabled: true.
Released CDS Views that support delta extraction contain the following annotation: @Analytics.dataextraction.delta.
For more information about the views that are enabled for extraction, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud .
Change History
New as of 2008 release.
3.6.3.2 CDS Modeling: Contacts and Profiles
Models available to show relationships between CDS views for data extraction.
Interaction Contacts [page 35] Overview of the data model that illustrates the relationships between the CDS views for Interaction Contacts.
Interactions [page 36] View the data model that visualizes the relationships between the CDS views for Interactions.
34
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
3.6.3.2.1 Interaction Contacts
Overview of the data model that illustrates the relationships between the CDS views for Interaction Contacts. For information about prerequisites, see Business Scenario: Marketing Analytics [page 23] and open the collapsible section titled Core Data Services (CDS)-Based Data Extraction.
Technical Details
Numbers indicate there is additional information below.
Anno tations Description
1
I_MKT_Contact : filters out contacts and container contacts that are either obsolete or flagged for deletion.
2
I_MKT_ContactAll : filters out obsolete contacts and container contacts.
(K) Represents key fields.
More details regarding complete CDS view definitions with all available fields can be viewed in the View Browser application.
Released CDS Views that are enabled for data extraction contain the annotation @Analytics.dataextraction.enabled: true.
Released CDS Views that support delta extraction contain the annotation @Analytics.dataextraction.delta.
For more information regarding which views are enabled for extraction, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud .
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
35
3.6.3.2.2 Interactions
View the data model that visualizes the relationships between the CDS views for Interactions.
Prerequisites
For information regarding prerequisites, see Business Scenario: Marketing Analytics [page 23] and open the collapsible section titled Core Data Services (CDS)-Based Data Extraction.
Technical Details
Numbers indicate there is additional information below.
36
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Anno tations Description
1
I_MKT_Interaction filters out interactions that are either obsolete or flagged for deletion.
(K) Represents key fields.
The purpose of this diagram is to show how the CDS views for Interactions can be linked together to form a model. More details regarding complete CDS view definitions with all available fields can be viewed in the View Browser application.
All of the CDS Views in the graphic support delta extraction and contain the annotation @Analytics.dataextraction.delta.
For more information regarding which views are enabled for extraction, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud .
3.6.3.3 CDS Modelling: Marketing Events and Event Participants
Overview of the data model that illustrates the relationships between the CDS views for marketing events and event participants.
Use
Use these CDS views if you want to extract the definition and values of events and event participants to process them further in an external system. These views support custom fields of events and participants.
Prerequisites
For information regarding prerequisites, see Business Scenario: Marketing Analytics [page 23] and open the collapsible section titled Core Data Services (CDS)-Based Data Extraction.
Technical Details
Numbers indicate that there's additional information provided below the diagram. The graphic below illustrates the relationship between the CDS views for marketing events.
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
37
Anno tations Description
1 C_MKT_MktgEventDetailsDex: This data extraction enabled CDS view provides the values of marketing event details such as event ID, name, description, event type, and so on.
2 I_MKT_MktgEvent: This basic view provides the values of events details such as event ID, name, description, event type, and so on.
3 I_MKT_CalendarDate: This basic view represents the event start date. The date is illustrated by the calendar year, month, quarter, and day. This helps to aggregate the extracted event details for the calendar dates.
PK Represents key fields.
The graphic below illustrates the relationship between the CDS views for marketing event participants.
38
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Anno tations Description
4 C_MKT_MktgEvtPrtcpntDetsDex: This data extraction enabled CDS view provides details of marketing event participant such as participant ID, contact origin, number of polls answered, number of surveys answered and so on. This view supports delta extraction as well as data of custom fields.
5 I_MKT_MktgEventParticipant: This basic view provides the values of event participants such as participant ID, contact origin, number of polls answered, number of surveys answered etc.
PK Represents key fields.
The purpose of the graphic below is to show how the CDS views for marketing event and event participants can be linked together to form a model. More details regarding complete CDS view definitions with all available fields can be viewed in the View Browser application.
Released CDS Views that are enabled for data extraction contain the following annotation: @Analytics.dataextraction.enabled: true.
Released CDS Views that support delta extraction contain the following annotation: @Analytics.dataextraction.delta.
For more information about the views that are enabled for extraction, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud .
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
39
3.6.3.4 CDS Modeling: Marketing Planning
Models available to show relationships between CDS views for data extraction. Planned and Actual Spend for Campaigns [page 40] View the data model which visualizes the relationships between the CDS views for Planned and Actual Spend for Campaigns. Proposed Spend for Programs [page 42] Overview of the data model that illustrates the relationships between the CDS views for Proposed Spend for Programs. Marketing Plan, Planned Budget, and Program Funding [page 43] Overview of the data model that illustrates the relationships between the CDS views for Marketing Plans, Planned Budget, and the Funding Source for Programs.
3.6.3.4.1 Planned and Actual Spend for Campaigns
View the data model which visualizes the relationships between the CDS views for Planned and Actual Spend for Campaigns.
Prerequisites
For information regarding prerequisites, see Business Scenario: Marketing Analytics [page 23] and open the collapsible section titled Core Data Services (CDS)-Based Data Extraction.
Technical Details
Numbers indicate there is additional information below.
40
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Anno tations Description
1
C_MKT_CmpgnPlndSpendHeaderDEX: For some campaigns, the planned spend amount might be defined at the
campaign level. Therefore, you can find the planned spend amount per month in the following CDS view instead.
2
I_MKT_Initiative: If you use the marketing plan snapshot functionality, you will find the campaign snapshot in
the CDS view I_MKT_InitiativeVersion. Therefore, you might need to merge the CDS view
I_MKT_Initiative and I_MKT_InitiativeVersion together to have the entire campaign history.
(K) Represents key fields.
Note
The different versions of campaigns generated by the snapshot functionally of the marketing plan application can be extracted from the same CDS views. The field MktgObjVersHdrUUID identifies the snapshot version. The CDS view I_MKT_ObjectVersionHeader gives the information on the snapshot version.
The only exception is the CDS view I_MKT_Initiative. In this case, the snapshot version can be extracted from the CDS view I_MKT_InitiativeVersion.
The purpose of this diagram is to show how the CDS views for Planned and Actual Spend for Campaigns can be linked together to form a model. More details regarding complete CDS view definitions with all available fields can be viewed in the View Browser application.
Released CDS Views that are enabled for data extraction contain the annotation @Analytics.dataextraction.enabled: true.
Released CDS Views that support delta extraction contain the annotation @Analytics.dataextraction.delta.
For more information regarding which views are enabled for extraction, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud .
Change History
New as of 2102 release.
Related Information
CDS Modeling: Campaign and Campaign Performance [page 33]
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
41
3.6.3.4.2 Proposed Spend for Programs
Overview of the data model that illustrates the relationships between the CDS views for Proposed Spend for Programs.
Prerequisites
For information regarding prerequisites, see Business Scenario: Marketing Analytics [page 23] and open the collapsible section titled Core Data Services (CDS)-Based Data Extraction.
Technical Details
Anno tations Description
1 The global proposed spend amount for a program is only relevant if no media type has been defined for the pro gram. If a media type is defined for a program, the valid proposed spend amount comes from the CDS view C_MKT_ProgramMediaTypeSpendDEX.
(K) Represents key fields.
Note
The different version of programs generated by the snapshot functionally of the marketing plan application can be extracted from the same CDS views. The field MktgObjVersHdrUUID will identify the snapshot version. The CDS view I_MKT_ObjectVersionHeader gives the information on the snapshot version.
The purpose of this diagram is to show how the CDS views for Proposed Spend for Programs can be linked together to form a model. More details regarding complete CDS view definitions with all available fields can be viewed in the View Browser application.
Released CDS Views that are enabled for data extraction contain the annotation @Analytics.dataextraction.enabled: true.
42
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
Released CDS Views that support delta extraction contain the annotation @Analytics.dataextraction.delta. For more information regarding which views are enabled for extraction, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud .
Change History
New as of 2102 release.
3.6.3.4.3 Marketing Plan, Planned Budget, and Program Funding
Overview of the data model that illustrates the relationships between the CDS views for Marketing Plans, Planned Budget, and the Funding Source for Programs.
Prerequisites
For information regarding prerequisites, see Business Scenario: Marketing Analytics [page 23] and open the collapsible section titled Core Data Services (CDS)-Based Data Extraction.
Technical Details
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
43
Anno tations Description
1
The planning dimensions refer to the following CDS views:
I_MKT_Market (MKT_MARKET) I_MKT_Country (MKT_COUNTRY) I_MKT_Region (MKT_REGION) I_MKT_Brand (MKT_BRAND) I_MKT_Audience (MKT_AUDIENCE) I_MKT_CustomDimension01 to 10 (MKT_CSTMDIMN01 to 10)
2 This CDS view contains 2 types of Budget that can be distinguish via the field MarketingBudgetPlanType: Public: Budget Plan Allocated: Allocated Bugdet Plan
This CDS view contains delta records and need to be aggregated by the Planning Dimensions and MarketingBudgetPlanUUID to get the total budget value.
(K) Represents key fields.
Note
The different versions of marketing plan, planned budget, and funding source generated by the snapshot functionally of the marketing plan application can be extracted from the same CDS views. The field MktgObjVersHdrUUID will identify the snapshot version.The CDS view I_MKT_ObjectVersionHeader gives the information on the snapshot version.
The purpose of this diagram is to show how the CDS views for marketing plans, planned budget, and funding sources for programs can be linked together to form a model. More details regarding complete CDS view definitions with all available fields can be viewed in the View Browser application.
Released CDS Views that are enabled for data extraction contain the annotation @Analytics.dataextraction.enabled: true.
Released CDS Views that support delta extraction contain the annotation @Analytics.dataextraction.delta.
For more information regarding which views are enabled for extraction, see the following blog at: Discover CDS View Based Extractors from SAP S/4HANA Cloud .
Change History
New as of 2102 release.
44
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
3.6.3.5 CDS Modeling: Scores and Predictive Studio
Overview of CDS views that are modeled according to the relationships between the different entities of scores.
Use
Use the Score CDS views if you want to extract the definition and the values of rule-based scores and predictive scores and further process them in an external system. If you have score values persisted, you can also extract score values. Non-persisted score values cannot be extracted. The API supports custom scores and SAP delivered scores.
Prerequisites
The prerequisite for using these CDS views is that you use one of the following integrations: CDI (Cloud Data Integration) BW or SAP DI to export data of Score entities into non-marketing systems (better performance than Rest
API, and with delta capability) For more information about prerequisites, see Business Scenario: Marketing Analytics [page 23] and open the collapsible section titled Core Data Services (CDS)-Based Data Extraction.
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
45
Technical Details
Score CDS Views Entity Score
Score Implementation
46
PUBLIC
CDS View I_MKT_CustomPredictiveScore I_MKT_ConfiguredScore
I_MKT_CustomPrdtvScoreImplmtn
Description
Custom Scores created with Predictive Scenarios application
Scores configured with customiz ing: SAP delivered scores
Score Builder scores
Implementation methods of custom scores created with Predictive Scenar ios application
Integration Guide Implementing Integrations for Business Scenarios
Entity
Score Model Score Persistence Score Value
CDS View I_MKT_ConfiguredScoreImplmtn
I_MKT_ScoreModel I_MKT_ScorePersistence I_MKT_MktgIntactnCntctScrVal
Description
Implementation methods of scores that are either configured via customizing or score builder scores
Score Models (Predictive Models)
Score Persistence
Persisted Score Values
Best Practices: Score Extraction and System Performance
Note
With an ODP source system, we recommend using ABAP runtime, since the extraction is done by ABAP anyway. A transformation in SAP HANA would cause unnecessary effort, since the data must first be persisted. For more information, see Transformation in the SAP HANA Database.
Before extracting score values, please consider how it can influcence system performance. Especially consider the following points: You can achieve better performance by scheduling regular full loads if
Your delta load regularly contains large amounts of data The amount of data in your delta load is similar to or even greater than that of the full load One possible scenario where this applies is where you have many scores that allow only one version to be persisted. Since adding the new version will delete the previous version, this doubles the number of records contained in the delta. Consider the update frequency of scores. The more daily scores you have, the heavier your delta load. Although the CDS-based extraction provides excellent performance, it still adds to the overall resource consumption. Additionally, a huge delta load leads to longer extraction runtime.
Recommendations for Consumption Please note the following recommendations to ensure optimum system performance: BW
The number of records contained in a delta load should not exceed 600 million. The recommended package size is 1 000 000 (one million). OData API The number of records contained in a delta load should not exceed 600 million. The recommended package size is 100 000 (one hundred thousand). The maximum number of parallel processes is 10 (ten).
Example: How to Calculate Your Data Load Volume The numbers shown in this example serve only as reference.
Let's assume you have the following number of scores, score versions and interaction contacts in your system:
Integration Guide Implementing Integrations for Business Scenarios
PUBLIC
47
Score Persistence Daily Weekly Monthly
Number of Score Versions Kept
10 10 10
Number of Scores Created Number of Contacts
5
5 million
5
5 million
5
5 million
Then the load of score values ranks from 750 million in the initial load to 50 million score values in the daily delta load.
Load
Calculation of Score Values Number of Score Values
Estimated Duration of Load
Initial Load
Delta Load for Daily Persis tence
(10 versions *5 scores + 10 versions * 5 scores + 10 ver sions *5 scores) * 5 million contacts
750 million
5 newly created scores * 5 million contacts + 5 deleted scores * 5 million contacts
50 million
Since the maximum number of score versions has been reached, adding a new ver sion will delete the oldest score version. The delta load also includes the deleted ver sions.
5 hours 30 minutes
Delta Load for Weekly Persis tence
(5 newly created scores * 5 million contacts + 5 deleted scores * 5 million contacts ) + (5 newly created scores * 5 million contacts + 5 deleted scores * 5 million contacts )
100 million
Once a week, the delta load contains 100 million score values. 50 million score val ues for the daily load and an other 50 million score values for the weekly load.
45 minutes
Delta Load for Monthly Per sistence
(5 newly created scores * 5 million contacts + 5 deleted scores * 5 million contacts ) + (5 newly created scores * 5 million contacts + 5 deleted scores * 5 million contacts ) + (5 newly created scores * 5 million contacts + 5 deleted scores * 5 million contacts )
150 million
Once a month, the delta load contains 150 million values. 50 million score values for the daily load, 50 million score values for the weekly load and another 50 million score values for the monthly load.
1 hour
48
PUBLIC
Integration Guide Implementing Integrations for Business Scenarios
4 Integration Scenarios
See the section for information about the integration of SAP Marketing Cloud with external systems.
Overview
Integration Scenarios provide a tight business process integration between SAP Marketing Cloud and other solutions. Technically they are loosely coupled by the SAP Cloud Integration middleware. We distinguish between Inbound [page 61] processes, where an external process step triggers a business process step in SAP Marketing Cloud and Outbound [page 108] processes, where a business process step in SAP Marketing Cloud triggers and external process step.
Application-Enabling Integrations [page 267] feature the integration of complete applications such as SAP Analytics Cloud or Google AdWords.
Suite-Enabling Integrations [page 333] include the integrations that form the SAP Customer Experience portfolio.
Apps for Setting Up a Typical Integration
In general, you enable the data exchange with an external system in the cloud by setting up the communication with the system. Each integration has its specific parameters, described in the respective integration guide topic, but all are set up in the following apps: Communication Management.
See the following topics for information about how to perform the steps in general: Maintain Communication Users Communication Arrangements How to Create a Communication Arrangement Maintain Communication Systems
Prerequisites and Details For prerequisites and details you specify to enable specific integration options, see the topics in this section.
Overview of Integration Scenarios (Table) [page 50] Inbound [page 61] Outbound [page 108] Application-Enabling Integrations [page 267]
The section provides information about integration options that enable specific applications of SAP Marketing Cloud, such as geospatial segmentation, or analyzing marketing data based on the analytic capabilities of SAP BusinessObjects Cloud. Suite-Enabling Integrations [page 333]
Integration Guide Integration Scenarios
PUBLIC
49
This section contains details of integration with applications in the SAP Suite, such as SAP Customer Experience, S/4HANA, CRM, ERP, and includes inbound, outbound, and bidirectional integration.
4.1 Overview of Integration Scenarios (Table)
Inbound
The content of the following table can be sorted and filtered.
Inbound Scenarios
Category
Connected Solution
Content
Communica tion Sce nario/ Comment
Integration Package on API Hub
Market Data and Events
Integration with Data Management Platforms [page 88] (DMP)
Cookie-based user data & interactions
SAP_COM_0 343
Not available on SAP API Hub.
Market Data and Events
List of exter nal providers, event partici pation
Prospects: contact data, corporate ac counts
SAP_COM_0 003
https://api.sap.com/package/SAPHybrisMarketingCloud filebaseddataload?section=Overview SAP Marketing Cloud - File-Based Data Load
Import CSV Using SAP Cloud Integra tion (Depre cated) [page 108]
50
PUBLIC
Integration Guide Integration Scenarios
Category
Connected Solution
Content
Communica tion Sce nario/ Comment
Integration Package on API Hub
Market Data and Events
1. Import third party
SAP_COM_0 342
contact,
permis
sion and
interac
tion data
to SAP
Market
ing Cloud
2. Create external landing pages us ing an iFlow
3. Bring prefill function ality to external tools us ing the Outboun dID
https://api.sap.com/package/ThirdPartyLandingPageDa taIntegrationwithSAPMarketingCloud?section=Overview
External Landing Page Integration
Sales and Service Data
Non-SAP SFA solutions
For example accounts and contacts from Salesforce Sales Cloud
SAP_COM_0 017
Not available on SAP API Hub.
Market Data and Events
Landing Pages Marketing
and Forms
permissions,
[page 91]
contact data,
and subscrip
tions
SAP_COM_0 https://api.sap.com/package/ThirdPartyLandingPageDa
023;
taIntegrationwithSAPMarketingCloud?section=Overview
SAP_COM_01
48
Social media, Web, Com merce, Mo bile, IoT
SAP Jam Communities [page 64]
User profiles, created prod uct reviews, read product reviews
SAP_COM_0 003
SAP_COM_0 004
Currently not on API Hub
Integration Guide Integration Scenarios
PUBLIC
51
Category
Connected Solution
Content
Communica tion Sce nario/ Comment
Integration Package on API Hub
Social media, Web, Com merce, Mo bile, IoT
Integration with Google Analytics [page 87]
Web Tracking: Campaign Conversion and Device Category in formation
SAP_COM_0 079
https://api.sap.com/package/SAPHybrisMarketingGoo gleAnalyticsIntegration?section=OVERVIEW
Social media, Web, Com merce, Mo bile, IoT
WeChat Inte gration [page 65]
Posting events (fol low, unfollow, send mes sages)
SAP_COM_01 Not available on SAP API Hub. 74
Social media, Web, Com merce, Mo bile, IoT
LINE Integra tion [page 77]
Posting events (fol low, unfollow, send mes sages) of Net work Channel
SAP_COM_01 74
Not available on SAP API Hub.
Social media, Web, Com merce, Mo bile, IoT
Fitbit Activity Tracker
Enrich profile with IoT data, project based see https:// blogs.sap.co m/ 2017/10/13/ leverage-fit bit-data-torun-sap-hyb ris-marketingcloud-cam paigns-part-1connectingfitbit-withhybris-mar
keting/
Not available on SAP API Hub.
52
PUBLIC
Integration Guide Integration Scenarios
Category
Connected Solution
Content
Communica tion Sce nario/ Comment
Integration Package on API Hub
Social media, Web, Com merce, Mo bile, IoT
Khoros
Contacts with
(fka Spred their social
fast / Lithium) IDs, interac
activity
tions like raw
tracker
marketing
leads for fol
low ups
Not available on SAP API Hub.
Survey
Integration with ThirdParty Survey Providers [page 107]
Import Sur vey Metadata and Re sponses from third-party tools.
SAP_COM_0 073
Third Party Survey Data Integration with SAP Marketing Cloud
Outbound
The content of the following table can be sorted and filtered.
Outbound Scenarios
Category
Connected Solution
Content
Communica tion Sce nario/ Comment
Integration Package on API Hub
Mobile & So cial Channel
Mobile App In Mobile Push tegration with Notifications Google Fire base [page 244]
SAP_COM_0 Not available on SAP API Hub. 061 and SAP_COM_01 69
Mobile & So cial Channel
Social Cam paigns Using Facebook and Instagram [page 254]
Social Cam paigns & Cus tom Audien ces
SAP_COM_0 031
Not available on SAP API Hub.
Digital Chan nel
WeChat Inte gration [page 258]
WeChat Mes sage Cam paigns
SAP_COM_0 085
Not available on SAP API Hub.
Integration Guide Integration Scenarios
PUBLIC
53
Category
Connected Solution
Content
Communica tion Sce nario/ Comment
Integration Package on API Hub
Digital Chan nel
LINE Integra tion [page 258]
Line Message SAP_COM_0 Campaigns 218
Not available on SAP API Hub.
Digital Chan nel
Integration with Google Ads [page 243]
Digital Chan nel
Integration with Google Campaign Manager [page 259]
GoogleAd words (Paid Search, Dis play Ads)
SAP_COM_0 https://api.sap.com/package/SAPHybrisMarketingGoo
030
gleAdWordsPaidSearchIntegration?section=Documents
Performance Data
SAP_COM_0 037
https://api.sap.com/package/SAPMarketingCloudIntegra tionwithGoogleDoubleClickCampaignManager?sec
tion=Artifacts
Email and Text Mes sages
Setting Up
Outbound
Amazon [page Mails incl.
138] (Email Bounce/
Servie Pro Success
vider)
SAP_COM_0 016, SAP_COM_0 039
Not available on SAP API Hub.
Email and Text Mes sages
Setting Up Sinch [page 112] (Email Service Pro vider)
Outbound Emails
SAP_COM_0 Not available on SAP API Hub. 040
Email and Text Mes sages
Setting Up Sinch [page 112]
SMS
SAP_COM_0 Not available on SAP API Hub. 041
Email and Text Mes sages
Setting Up a Generic Email and Text Mes sage Interface [page 116] (Any Email Service Pro vider)
Outbound Emails
SAP_COM_0 Not available on SAP API Hub. 234
Email and Text Mes sages
Setting Up a Generic Email and Text Mes sage Interface [page 116]
SMS
SAP_COM_0 Not available on SAP API Hub. 258
54
PUBLIC
Integration Guide Integration Scenarios
Category
Connected Solution
Content
Communica tion Sce nario/ Comment
Integration Package on API Hub
Extensions
Setting Up Ex ternal Cam paign Execu tion [page 155]
External Cam paign Execu tion: Transfer Target Group Member Data
SAP_COM_0 037
Not available on SAP API Hub.
Extensions
Open Channel Integration [page 194]
Open Cam paign Chan nel: Create customer specific ac tions & followon objects
SAP_COM_0 049
Not available on SAP API Hub.
Options to Integrate with External Outbound Channels for Campaigns
Overview Entity Types
Setting Up External Campaign Execution [page 155]
Open Channel Inte gration [page 194]
Generic Email and Text Message Integra tion [page 120]
Generic Email and Text Message Integra tion [page 120]
Replicate full cam
Transfer individual con Integrate any Email
paigns and target
tacts from target
Service Provider
groups member keys group for execution on (ESP), for example,
regularly (optional) for external platform, for Inxmail.
execution in external example, for 3rd party
platforms/systems, for CRM integration (e.g.
example, for Ad cam lead creation) while the
paigns (any DMP,
campaign flow is con
DSP).
trolled within SAP Mar
keting Cloud.
Integrate any text mes sage service provider
Campaign (optional, incl. parameters)
Campaign
Email messages
Target group members with personalization data
Text Messages
Integration Guide Integration Scenarios
PUBLIC
55
Setting Up External Campaign Execution [page 155]
Open Channel Inte gration [page 194]
Generic Email and Text Message Integra tion [page 120]
Generic Email and Text Message Integra tion [page 120]
Personalizations
Performed in external Performed in external Performed in SAP Mar Performed in SAP Mar
system
system
keting Cloud
keting Cloud
Transfer of personal ized contact attributes through Export Definition
Transfer of personal ized emails
Transfer of personal ized text messages
Implementation De tails
Communication Ar rangement Setup
SCI (optional)
BAdI Implementation
Communication Ar rangement Setu
Communication Ar rangement Setup
SCI (optional)
SCI (optional)
Communication Ar rangement Setup
SCI (optional)
Standard Campaign Success Handling
SAP Marketing Cloud requests campaign success data in a peri odic way (every four hours).
BAdI implementation
Implementation with API
Implementation with API
SAP Marketing Cloud requests bounce infor mationevery 10 mi nutes, when the cam paign has been exe cuted within the last 48 hours. After 48 hours, the bounces are collected every four hours
SAP Marketing Cloud requests status infor mationevery 10 mi nutes, when the cam paign has been exe cuted within the last 48 hours. After 48 hours the bounces are collected every four hours
Typically tracked by ESP: bounce, com plaint
Typically tracked by message provider: bounce
Tracked by SAP Mar keting Cloud: mail sent, mail opened, link click
Implementation with API
Tracked by SAP Mar keting Cloud: message sent, link click
Implementation with API
Transfer Messages/ No
No
Yes
Yes
Campaign Content
Instances per System Unlimited
Unlimited
Unlimited
Unlimited
Application-Enabling
The content of the following table can be sorted and filtered.
56
PUBLIC
Integration Guide Integration Scenarios
Application-Enabling scenarios
Connected Sol
ution
Use Scenario
Communica tion Scenario/ Comment
Integration Package on API Hub
SAP Predictive Consumer Buy Analytics - Auto ing Propensity mated Predictive (fka SAP Infinite Insight)
Not applicable
Not available on SAP API Hub.
SAP Jam Inte gration for Col laboration [page 320]
Collaboration for Marketing Planning, Cam paign Manage ment
SAP_COM_002 Not available on SAP API Hub. 6
Integration with SAP Analytics Cloud (1SO) [page 268]
Self-service BI/ SAP_COM_006 agile analytics in 5 the cloud
Not available on SAP API Hub.
Enabling Geo spatial Segmen tation with here.com [page 317] (fka Nokia Here)
Geospatial Seg mentation
Not applicable
Not available on SAP API Hub.
Integration with Baidu Maps for Geospatial Seg mentation (Dep recated) [page 318]
Geospatial Seg mentation for Chinese geolo cation data
SAP_COM_007 5
Not available on SAP API Hub.
Integrate with Content Man agement Sys tems or Digital Asset Manage ment Systems [page 306] (OpenText and others)
Enrich email
SAP_COM_005
campaign con 0
tent with crea
tive assets from
PCM/DAM solu
tions
SAP Marketing Cloud Integration With Content Management Sys tem
Integration Guide Integration Scenarios
PUBLIC
57
Connected Sol
ution
Use Scenario
Communica tion Scenario/ Comment
Integration Package on API Hub
Integrate with SAP Document Center [page 312]
Upload images and access im ages for use via the Content Studio app
SAP_COM_005 Not available on SAP API Hub. 0
Verifying Email Addresses Using a Partner Solu tion [page 321] (Neverbounce)
Email ID lists for verification and Hard Bounce Prevention, see Blog for CSV based integra tion and blog for CPI based inte gration
SAP_COM_004 9
Not available on SAP API Hub.
Integration with an External Cou pon Service Sys tem [page 321]
Ingest externally generated cou pons codes for offers
SAP_COM_028 6
Not available on SAP API Hub.
Marketing Events [page 330]
Fetch Events data from thirdparty event pro vider platforms
SAP_COM_047 Third Party Marketing Events Integration with SAP Marketing Cloud 4 ( Deprecated) Marketing Event Outbound Integration (SAP_COM_054 1) and Market ing - Event In bound Integra tion (SAP_COM_037 1)
Suite-Enabling Integrations
The content of the following table can be sorted and filtered.
58
PUBLIC
Integration Guide Integration Scenarios
Suite-Enabling Integrations
Category
Connected Solution Content
Communication Sce Integration Package
nario/Comment
on API Hub
Financial data
Integration with SAP ERP for Spend Plan ning [page 379]
WBS spend for cam paigns including project creation
SAP_COM_0018
SAP Marketing Cloud SAP ERP Actual and Committed Spend In tegration
Industry data
(CAR) SAP Customer POS data Activity Repository re tail applications bundle [page 352]
SAP_COM_0004 / re quires SAP CAR 2.0 FP1
Not available on SAP API Hub.
Market Data and Events
Integration with SAP Qualtrics Surveys [page 384]
Import survey re sponse data
SAP_COM_0073
SAP Qualtrics Surveys Integration with SAP Marketing Cloud
Sales Automation
Integration with Exter nal Sales Systems Outbound Channel [page 374]
For example: Lead Handover to Sales force Sales Cloud
SAP_COM_0017
Partner Offering by Ad vantco
Sales and Service Data
Integration with SAP CRM - Inbound Chan nel [page 342]
1. Customers, con sumers & con tacts, marketing attributes mobile & social channel
2. Sales business documents such as orders, oppor tunities etc.
3. Permissions (Mi gration)
SAP_COM_0017
Sales and Service Data
Integration with SAP Cloud for Customer Inbound Channel [page 338]
Integrating Service Tickets [page 350]
1. Individual custom SAP_COM_0017 ers, corporate ac counts and con tacts
2. Leads and oppor tunities, call activi ties, appoint ments/visits,
3. Marketing attrib utes,
4. Permissions (one time migration)
https://api.sap.com/ package/SAPHybris MarketingCloud SAPCRMIntegration? section=Overview
https://api.sap.com/ package/SAPHybri sCloudforCustomerIn tegrationwithSAPHy brisMarketing?sec tion=Overview
Integration Guide Integration Scenarios
PUBLIC
59
Category
Connected Solution Content
Communication Sce Integration Package
nario/Comment
on API Hub
Sales and Service Data Integration with SAP ERP [page 349]
Customers and con tacts, consumers, products, sales orders, returns, quotations, EoP for customer/ contacts
SAP_COM_0060
https://api.sap.com/ package/SAPHybris MarketingCloudSA PERPOrderandBusi nessPartnerIntegra tion?section=Overview
Sales and Service Data
Order Management Data Replication to SAP Marketing Cloud [page 348]
Customers and con tacts, consumers, products, EoP for busi ness partner, sales or der
SAP_COM_0060
Social media, Web,
SAP Customer Data
Commerce, Mobile, IoT Cloud and SAP Mar
keting Cloud [page
338] (fka Gigya)
User profiles, market ing attributes & per missions, newsletter subscriptions
SAP_COM_0264
https://api.sap.com/ package/ SAPS4HANAEnterpri seManagementOnPre miseIntegrationwith SAPHybrisMarketing Cloud?section=Over view
https://api.sap.com/ package/SAPHybris MarketingCloud SAPS4HANAEnterpri seCloudIntegration? section=Overview
Not available on SAP API Hub.
60
PUBLIC
Integration Guide Integration Scenarios
Category
Connected Solution Content
Communication Sce Integration Package
nario/Comment
on API Hub
Social media, Web,
Integration with SAP
Commerce, Mobile, IoT Commerce Cloud
[page 62]
1. Master data
Marketing - Commerce SAP Commerce Cloud
For example, cus Data Integration
Integration with SAP
tomers and prod (SAP_COM_0082)
Marketing Cloud
ucts.
Marketing - Recom
2. Transactional data mendation Integration
For example, or (SAP_COM_0019)
ders and carts.
SAP Commerce Cloud, Context-Driven Serv ices Integration with SAP Marketing Cloud
Note
Standard Commerce 6.0 solutions use SAP Commerce Data Hub or Expressway
to send master and transactional data.
Note
Clickstream inte gration requires a SAP Commerce Cloud, ContextDriven Services li cense.
3. Product and offer recommendations
4. Personalized con tent
5. Clickstream data For example, products viewed.
4.2 Inbound
Commerce, Social Media, Web, and IoT [page 62] Landing Pages and Forms [page 91]
Integration options for landing pages and forms. Survey [page 107] Extensions [page 108]
Integration Guide Integration Scenarios
PUBLIC
61
4.2.1 Commerce, Social Media, Web, and IoT
Integration with SAP Commerce Cloud [page 62] Support omnichannel activities by integrating SAP Marketing Cloud with SAP Commerce Cloud.
SAP Jam Communities [page 64] Provides user profiles and product reviews.
WeChat Integration [page 65] With this integration, you can synchronize the followers of your WeChat official accounts as well as the follower interactions to SAP Marketing Cloud. What's more, you can create and carry out WeChat campaigns through SAP Marketing Cloud. Analytical reports about WeChat followers and interactions are available as well.
LINE Integration [page 77] With this integration, you can synchronize the followers of your LINE accounts as well as the follower interactions to SAP Marketing Cloud. What's more, you can create and carry out LINE campaigns through SAP Marketing Cloud. Analytical reports about LINE followers and interactions are available as well.
Integration with Google Analytics [page 87] Overview of the integration scenario.
Integration with Data Management Platforms [page 88] With this integration scenario, you can capture and replicate Data Management Platform (DMP) IDs from DMP providers, such as Adform. A DMP ID is mapped to a commerce contact ID and stored inside SAP Marketing Cloud.
4.2.1.1 Integration with SAP Commerce Cloud
Support omnichannel activities by integrating SAP Marketing Cloud with SAP Commerce Cloud.
This integration leverages the value of commerce stores by personalization of customer engagement on the one hand as it allows you to display SAP Marketing Cloud content such as recommendations and personalized campaign content in SAP Commerce Cloud. On the other hand, the integration drives the customer retention by gathering data from SAP Commerce Cloud for your marketing activities in SAP Marketing Cloud.
You perform installation and configuration activities for the integration entirely in SAP Commerce Cloud.
For information about setting up the integration, see Configuring SAP Cloud Integration and Configuring SAP Marketing Cloud. Documentation for SAP Commerce Cloud is accessible to SAP customers and partners.
62
PUBLIC
Integration Guide Integration Scenarios
Note
You can also integrate with the on-premise version of SAP Commerce. For all integration options, see SAP Marketing Cloud Integration Module .
System Requirements
The system requirements for the integration are as follows:
Feature Product recommendations
Offer recommendations
Personalized campaign content (seg mentation) Master and transactional data
Clickstream data905 and higher
SAP Commerce Cloud (in the Public Cloud)
SAP Marketing Cloud
1905 and higher
1908
1905 and higher
1908
1905 and higher
1908
1905 and higher 1908
1908
For an overview of the features introduced with each release of SAP Commerce Cloud, see the release notes for SAP Commerce Cloud. The release notes are available from the SAP Commerce Cloud product page on the SAP Help Portal at SAP Commerce, under What's New.
To view the documentation for a given release, use the version drop-down list.
Outbound: Product and Offer Recommendations, Personalized Storefront Content (Segmentation)
Display product and offer recommendations based on the latest information submitted from the customer, such as their cart contents or recently viewed items. SAP Commerce Cloud tracks the visibility and success of your recommendations, and sends this data to SAP Marketing Cloud for analysis.
You can define restrictions to drive the display of individual page components based on real-time campaign lookups in SAP Marketing Cloud. You can also drive the display of entire page variants using marketing data.
For detailed information on the required communication settings, see Configuring SAP Marketing Cloud.
Integration Guide Integration Scenarios
PUBLIC
63
Inbound: Master Data, Transactional Data, and Clickstream Data
Various types of master and transactional data are collected by SAP Commerce Cloud. For example, customer, product, saved shopping cart, abandoned shopping cart, order, and review data. This data is then sent to SAP Marketing Cloud.
For detailed information on the required communication settings, see Configuring SAP Marketing Cloud.
With clickstream integration, user events on the storefront are aggregated in SAP Commerce Cloud, and then sent to SAP Marketing Cloud for follow-up marketing activities. Various types of user events on the storefront can be sent, for example, product views, category views, and keyword searches.
Clickstream data can be replicated to SAP Marketing Cloud using one of the following integrations:
1. SAP Commerce Cloud, Context-Driven Services using SAP Cloud Integration For more information, see the following: Customer Interaction Replication from SAP Commerce Cloud, Context-Driven Services SAP Commerce Cloud, Context-Driven Services Integration with SAP Marketing Cloud Context-Driven Services Foundation Integration
Note
The system automatically deletes the contacts for anonymous users that only have a SAP_CDS_PROFILE origin, if the users have remained anonymous for more than 90 days. This is independent from the licensed number of contacts. For more information on the handling of contacts, see Contacts
2. Google Analytics using SAP Cloud Integration For more information, see Overview of Create Interactions Scenario and Google Analytics Integration with SAP Marketing Cloud .
4.2.1.2 SAP Jam Communities
Provides user profiles and product reviews.
The integration option provides user information of consumers or contacts on a commerce store, and product reviews from SAP JAM Communities for the use in SAP Marketing Cloud. If known users read product reviews, interactions are created.
The integration is based on the capabilities of SAP JAM Communities when used in commerce context to facilitate discussions on a product, asking and answering questions on a product, and creating product reviews.
Integration Setup
To enable the connection with SAP JAM Communities, create the following communication settings: Communication user
64
PUBLIC
Integration Guide Integration Scenarios
Communication system Two communication arrangements: One selecting Communication Scenario SAP_COM_0003, and a second
selecting Communication Scenario SAP_COM_0004.
For information about how to use the communication management apps in general, see Communication Management.
SAP JAM Communities Data in SAP Marketing Cloud
Find the replicated user data along with profile picture, email address, user ID, user ID of the SAP Commerce shop (if integrated with SAP JAM Communities) in the Consumer Profile.
Reviews are treated as a specific interaction type that captures the review score (1-5 stars) in the valuation field, which is also used by sentiments (1 = strong negative to 5 = strong positive). Product data is added to the product node of the interaction. The product name is a tag of the interaction. Interactions of this type run through the SAP HANA text analysis identifiying additional tags that can be used for further processing, or interest assignment.
For information about how to set up the integration, see the product page SAP Jam Collaboration and choose Administrator Guide Integrations Integrate an SAP S/4HANA application .
4.2.1.3 WeChat Integration
With this integration, you can synchronize the followers of your WeChat official accounts as well as the follower interactions to SAP Marketing Cloud. What's more, you can create and carry out WeChat campaigns through SAP Marketing Cloud. Analytical reports about WeChat followers and interactions are available as well.
Note
The WeChat integration supports WeChat subscription accounts and WeChat service accounts only.
The following is a detailed list of the business functions that come with the WeChat integration: Synchronization of WeChat followers and interactions to SAP Marketing Cloud Creation and execution of WeChat campaigns through SAP Marketing Cloud Analytical reports about the acquisition of WeChat followers, including reports predefined by SAP and
custom reports that you can build with a CDS view Analytical reports about WeChat interactions, including reports predefined by SAP and custom reports
that you can build with a CDS view For information about setting up and administering the WeChat integration, see the following documents: Setting Up the WeChat Integration [page 66] Administering the WeChat Integration [page 73] For extensibility options, see Extensibility [page 76]. For the descriptions of the business functions, see the following documents:
Integration Guide Integration Scenarios
PUBLIC
65
Followers of Digital Accounts Attributes Related to Followers of Digital Accounts WeChat Campaigns
4.2.1.3.1 Setting Up the WeChat Integration
Set up the connection between SAP Marketing Cloud and your WeChat official account.
Prerequisites
You have registered an official account through the WeChat Official Account Admin Platform.
Procedure
1. Import the WeChat certificate.
For more information, see Importing the WeChat Certificate [page 67]. 2. Create communication configurations for the inbound communication and outbound communication,
respectively.
For more information, see Creating Communication Configurations [page 68]. 3. Create your official account.
For more information, see Creating a WeChat Official Account [page 72]. 4. Create and schedule application jobs.
You must create a job based on the template Digital Accounts: Process Inbound Messages, which is required for the automatic synchronization of followers and interactions to SAP Marketing Cloud.
If your WeChat official account already had followers before the WeChat integration goes live, you must create a job based on the template Digital Accounts: Synchronize WeChat Users to synchronize the existing followers to SAP Marketing Cloud.
There are other jobs that are required for specific functions only. For more information, see Creating and Scheduling Application Jobs [page 73].
Results
The system synchronizes followers and follower interactions from the WeChat server to SAP Marketing Cloud automatically. Depending on the application jobs you have run, the system synchronizes other types of data (for example, campaign content) to SAP Marketing Cloud.
66
PUBLIC
Integration Guide Integration Scenarios
4.2.1.3.1.1 Importing the WeChat Certificate
In the standard delivery, the system gets and posts WeChat data directly through the WeChat server. If you adopt this approach, import the WeChat certificate so that SAP Marketing Cloud will be trusted by the WeChat server. If you have your own logic for getting and posting WeChat data through a different server, which uses the HTTPS communication protocol, then import the certificate of that server instead.
Prerequisites
A business role that contains the Security (SAP_CORE_BC_SEC) business catalog is required. You can use the standard business role Administrator (SAP_BR_ADMINISTRATOR), which contains the Security business catalog and other administration-related catalogs. Alternatively, you can create custom business roles using the Maintain Business Roles app.
Procedure
1. Go to https://open.weixin.qq.com/ . 2. Locate the WeChat certificate and export it to a file. 3. Log into SAP Fiori launchpad with a business role that contains the Security (SAP_CORE_BC_SEC)
business catalog. 4. Open the Maintain Certificate Trust List app. 5. Choose + (Add).
The Upload Certificate window appears. 6. Upload the WeChat certificate file.
Next Steps
Creating Communication Configurations [page 68]
Integration Guide Integration Scenarios
PUBLIC
67
4.2.1.3.1.2 Creating Communication Configurations
Create the configurations required for the communication between SAP Marketing Cloud and the WeChat server.
Prerequisites
A business role that contains the Communication Management (SAP_CORE_BC_COM) business catalog is required. You can use the standard business role Administrator (SAP_BR_ADMINISTRATOR), which contains the Communication Management business catalog and other administration-related catalogs. Alternatively, you can create custom business roles using the Maintain Business Roles app.
Context
The WeChat integration involves communication in both the inbound and outbound directions. In the inbound communication, the WeChat server pushes to a customer-defined servlet WeChat events as well as messages that followers send to WeChat official accounts. Then the servlet forwards the WeChat events and messages to SAP Marketing Cloud by calling the private ICF service <host name>/sap/cuan/ntwrk/. The outbound communication involves synchronizing data (for example, basic follower information and campaign content) from the WeChat server and executing WeChat campaigns through SAP Marketing Cloud. The inbound communication and outbound communication require their respective communication system/ communication arrangement pair. In addition, you need to create a communication user for the inbound communication. When calling the private ICF service to forward the WeChat events and messages to SAP Marketing Cloud, your servlet must authenticate itself with this communication user first. The following communication scenarios are relevant to the WeChat integration: Marketing Network Channel Events Integration (SAP_COM_0174) Marketing Campaign Execution WeChat Integration (SAP_COM_0085) For detailed instructions, see Configuring the Inbound Communication [page 69] and Configuring the Outbound Communication [page 70]. For general information about communication management, see Communication Management.
68
PUBLIC
Integration Guide Integration Scenarios
4.2.1.3.1.2.1 Configuring the Inbound Communication
Create the communication user, communication system, and communication arrangement required for the inbound communication.
Customer Implementation
You must define a servlet for the inbound communication. This servlet receives the WeChat events and messages pushed by the WeChat server and then forwards them to SAP Marketing Cloud by calling the private ICF service <host name>/sap/cuan/ntwrk/. For more information, see the blog Inbound Connection from WeChat or LINE to SAP Marketing Cloud .
Creating the Communication User
Proceed as follows: 1. Log into SAP Fiori launchpad with a business role that contains the Communication Management
(SAP_CORE_BC_COM) business catalog. 2. Open the Maintain Communication Users app. 3. Choose New.
The Create Communication User dialog box appears. 4. Fill in the following fields:
User Name and Description (for example, WECHAT_EVENT and WeChat Event) Password 5. Save the communication user. A communication user ID is generated automatically.
Note
When calling the private ICF service, your servlet should authenticate itself with the communication user ID instead of the user name.
Do not exit SAP Fiori launchpad.
Creating the Communication System
This communication system is a dummy one. The purpose of it is to bind the communication user that you created earlier with the communication arrangement that you will create later. To create the communication system, proceed as follows: 1. Open the Communication Systems app. 2. Choose New.
Integration Guide Integration Scenarios
PUBLIC
69
The New Communication System dialog box appears. 3. Enter a system ID and its name, for example, WECHAT_EVENT and WeChat Event. Choose Create.
The editing screen for the communication system appears. 4. A host is irrelevant to the inbound communication. Enter dummy in the Host Name field to assign a dummy
host. 5. Assign the communication user created earlier to this communication system, as follows:
1. In the User for Inbound Communication section, choose + (Add). The New Inbound Communication User dialog box appears.
2. Enter the user created earlier and select the authentication method User Name and Password. 6. Save and activate the communication system.
Do not exit SAP Fiori launchpad.
Creating the Communication Arrangement
Proceed as follows: 1. Open the Communication Arrangements app. 2. Choose New.
The New Communication Arrangement dialog box appears. 3. Enter scenario SAP_COM_0174 and an arrangement name. Choose Create.
The editing screen for the communication arrangement appears. 4. In the Communication System field, enter the communication system created earlier. 5. Save and activate the communication arrangement.
Next Steps
Configuring the Outbound Communication [page 70]
4.2.1.3.1.2.2 Configuring the Outbound Communication
Create the communication system and communication arrangement required for the outbound communication.
Creating the Communication System
Proceed as follows: 1. Log into SAP Fiori launchpad with a business role that contains the Communication Management
(SAP_CORE_BC_COM) business catalog.
70
PUBLIC
Integration Guide Integration Scenarios
2. Open the Communication Systems app. 3. Choose New.
The New Communication System dialog box appears. 4. Enter a system ID and its name, for example, WECHAT_API and WeChat API. Choose Create.
The editing screen for the communication system appears. 5. In the Host Name field in the Technical Data section, enter api.weixin.qq.com, which is the host name
of the WeChat server. Choose Save.
Note
If you have your own logic for getting and posting WeChat data through another server, then enter the host name of that server instead. For more information, see Extensibility [page 76].
6. Set the authentication method to None, as follows: 1. In the User for Outbound Communication section, choose + (Add). The New Outbound User dialog box appears. 2. Select the authentication method None. Choose Create.
7. Save and activate the communication system. Do not exit SAP Fiori launchpad.
Creating the Communication Arrangement
Proceed as follows: 1. Open the Communication Arrangements app. 2. Choose New.
The New Communication Arrangement dialog box appears. 3. Enter scenario SAP_COM_0085 and an arrangement name. Choose Create.
The editing screen for the communication arrangement appears. 4. In the Communication System field, enter the communication system that you have created. 5. Activate all the outbound services by selecting the Active checkboxes. 6. Save and activate the communication arrangement.
Next Steps
Creating a WeChat Official Account [page 72]
Integration Guide Integration Scenarios
PUBLIC
71
4.2.1.3.1.3 Creating a WeChat Official Account
Create a WeChat official account in SAP Marketing Cloud.
Prerequisites
A business role that contains the Marketing - Data (SAP_CEC_BC_MKT_PRD_PC) business catalog is required. You can use the standard business role Marketing Expert (SAP_BR_MARKETING_EXPERT), which contains the Marketing - Data business catalog and other marketing-related catalogs. Alternatively, you can create custom business roles using the Maintain Business Roles app.
Procedure
1. Log into SAP Fiori launchpad with a business role that contains the Marketing - Master Data (SAP_CEC_BC_MKT_PRD_PC) business catalog.
2. Open the Digital Accounts app. 3. On the landing page, choose Create Digital Account.
The Select Digital Account Type dialog box appears. 4. Select WeChat Official Account.
The editing screen for the official account appears. 5. Select the marketing area and enter the required information. Choose Create.
The required information includes: ID and name of the official account that are registered through the WeChat Official Account Admin
Platform Handshake token
You create your own handshake token. The token entered here must be the same as the one specified on the Basic Configurations page on the WeChat Official Account Admin Platform. Original ID Credentials for the official account, including the following: App ID App Secret You can find these credentials from the Basic Configurations page on the WeChat Official Account Admin Platform. 6. On the WeChat Official Account Admin Platform, enter your handshake token and the URI of your servlet.
Results
The official account appears with the Active status on the landing page of the Digital Accounts app. By default, the system sets the image assigned to the WeChat communication medium in the Manage Images app as the
72
PUBLIC
Integration Guide Integration Scenarios
profile picture of the official account. Clicking the account displays various tabs that contain different kinds of information about the official account. The Information tab contains basic information about the official account and the credentials. You can change the profile picture, credentials, and so on, by clicking the Edit button.
Next Steps
Creating and Scheduling Application Jobs [page 73]
4.2.1.3.2 Administering the WeChat Integration
Learn about the system administration activities relevant to the WeChat integration. Creating and Scheduling Application Jobs [page 73] Learn about the application job templates relevant to the WeChat integration. Some are required for the WeChat integration in general, while others are required for specific functions. Activating, Deactivating, and Restricting a WeChat Official Account [page 75] You can set a WeChat official account to any of these statuses in the Digital Accounts app: Active, Inactive, and Restricted. Overview of Business Catalogs Required for Different Business Functions [page 76] Different business functions require different business catalogs. Learn about the business catalogs that are required for the functions related to the WeChat integration and assign business roles to business users appropriately.
4.2.1.3.2.1 Creating and Scheduling Application Jobs
Learn about the application job templates relevant to the WeChat integration. Some are required for the WeChat integration in general, while others are required for specific functions.
Overview of Related Application Job Templates
Application Job Template Digital Accounts: Process Inbound Messages
Description
A job created using this template creates contacts and inter actions from digital accounts, such as WeChat official ac counts, in SAP Marketing Cloud. For more information, see Digital Accounts: Process Inbound Messages.
Integration Guide Integration Scenarios
PUBLIC
73
Application Job Template Digital Accounts: Synchronize WeChat Users
Digital Accounts: Synchronize Campaign Content from WeChat
Description
You have set up the WeChat integration and thus the follow ers of a WeChat official account can be synchronized to SAP Marketing Cloud automatically. However, there are certain situations where you must synchronize WeChat followers by running a job that is created with this template. For more in formation, see Digital Accounts: Synchronize WeChat Users.
You must create a job using this template if you want to cre ate and carry out WeChat campaigns through SAP Marketing Cloud. Business users maintain campaign con tent on the WeChat Official Account Admin Platform. The ap plication job synchronizes the campaign content from the WeChat Official Account Admin Platform to SAP Marketing Cloud. For more information, see Digital Accounts: Syn chronize Campaign Content from WeChat.
Checking the Application Log
You can find a log of all these application jobs centrally from the Application Logs app. The filters that you can use for the application jobs are as follows:
Application Job
Digital Accounts: Process Inbound Messages
Digital Accounts: Synchronize WeChat Users Digital Accounts: Synchronize Campaign Content from WeChat
Filter Category CUAN, subcategory CUAN_NTWRK Category CUAN, subcategory CUAN_WECHAT
Alternatively, you can find the log of a particular application job directly from the Marketing Application Jobs app. From the application job list, click the icon next to an application job.
Required Business Role
A business role that contains the Marketing - Business Administration (SAP_CEC_BC_MKT_ADM_PC) business catalog is required for scheduling application jobs and checking logs. You can use the standard business role Administrator - Marketing (SAP_BR_ADMINISTRATOR_MKT), which already contains this business catalog. Alternatively, you can create custom business roles using the Maintain Business Roles app.
74
PUBLIC
Integration Guide Integration Scenarios
4.2.1.3.2.2 Activating, Deactivating, and Restricting a WeChat Official Account
You can set a WeChat official account to any of these statuses in the Digital Accounts app: Active, Inactive, and Restricted.
Activating a WeChat Official Account
To use the full functionality of the WeChat integration, you must set an official account to Active status. When completing creating an official account, the status of the official account is set to Active automatically. To set an official account from Restricted status to Active status, choose the Activate button. To set an official account from Inactive status to Active status, choose the Switch to Restricted Mode button and then the Activate button.
Deactivating a WeChat Official Account
If you do not want to connect to an official account, for example, because the official account is no longer in use, deactivate it by choosing the Deactivate button.
Restricting a WeChat Official Account
When an official account is restricted, the outbound connection to the official account stops working. Therefore, the following functions become unavailable: Execution of WeChat campaigns through SAP Marketing Cloud Synchronization of basic information about new followers from WeChat, such as nickname and gender Synchronization of WeChat followers using an application job created based on the job template Digital
Accounts: Synchronize WeChat Users Synchronization of campaign content from WeChat using an application job created based on the job
template Digital Accounts: Synchronize Campaign Content from WeChat When an official account is restricted, there is no impact on the inbound connection from an official account. The synchronization of interactions between followers and the official account still works and the messages that followers send to the official account are still synchronized. To set an official account to Restricted status, choose the Switch to Restricted Mode button.
Integration Guide Integration Scenarios
PUBLIC
75
4.2.1.3.2.3 Overview of Business Catalogs Required for Different Business Functions
Different business functions require different business catalogs. Learn about the business catalogs that are required for the functions related to the WeChat integration and assign business roles to business users appropriately.
The following table lists the business catalogs that are required for different functions:
Business Function
Required Business Catalog
Standard Business Role That Can Be Used
Functions Available with the Digital Accounts App
Marketing - Data (SAP_CEC_BC_MKT_PRD_PC)
Marketing Expert (SAP_BR_MARKETING_EXPERT)
Contact Profiles of WeChat Followers
Marketing - Contacts and Profiles Base (SAP_CEC_BC_MKT_DMB_PC)
Marketing - Contacts and Profiles Standard (SAP_CEC_BC_MKT_DMS_PC)
Segmentation
Marketing Segmentation (SAP_CEC_BC_MKT_SEG_PC)
WeChat Campaigns
Marketing - Campaign Management (SAP_CEC_BC_MKT_CPM1_PC)
Custom analytical reports in the Query Marketing - Data
Browser app
(SAP_CEC_BC_MKT_PRD_PC)
Query Browser (SAP_CA_BC_VDM_BROWSE)
Quick Launch
Marketing - Quick Launch (SAP_CEC_BC_MKT_COM_PC (Depre cated as of 2011)
4.2.1.3.3 Extensibility
Customize the way that you use the WeChat integration.
Custom Fields
You can add custom fields to the Digital Accounts app using the Custom Fields app. When creating custom fields in that app, use business context MKT_DIGITAL_ACCOUNT.
76
PUBLIC
Integration Guide Integration Scenarios
Due to ABAP DDIC restrictions, only a defined number of fields and characters can be created for each business context.
Business Context MKT_DIGITAL_ACCOUNT
Description
Maximum Number of Char Maximum Number of Fields acters
Marketing: Digital Account 100
1000
For general information about creating and enabling custom fields, see Custom Fields.
Custom Logic for Getting WeChat Access Tokens
In the standard delivery, the system requests WeChat access tokens directly from the WeChat server. However, due to business requirements, you may have multiple servers that have outbound connections to the same official account. You use one of them as a primary server, which is responsible for getting and storing access tokens. In this situation, you can set up the system to get access tokens through the primary server by creating an enhancement implementation in the Custom Logic app. When creating your enhancement implementation in that app, use the Marketing: Digital Account business context and Getting of Access Token enhancement option.
For more information, see Custom Logic.
Required Business Role
A business role that contains the Extensibility (SAP_CORE_BC_EXT) business catalog is required for creating custom fields or custom logic. You can use the standard business role Administrator (BR_ADMINISTRATOR), which already contains this business catalog. Alternatively, you can create custom business roles using the Maintain Business Roles app.
4.2.1.4 LINE Integration
With this integration, you can synchronize the followers of your LINE accounts as well as the follower interactions to SAP Marketing Cloud. What's more, you can create and carry out LINE campaigns through SAP Marketing Cloud. Analytical reports about LINE followers and interactions are available as well.
Note
The LINE integration supports LINE@ accounts only.
The following is a detailed list of the business functions that come with the LINE integration: Synchronization of LINE followers and interactions to SAP Marketing Cloud
Integration Guide Integration Scenarios
PUBLIC
77
Note
Not all LINE followers of a LINE account are necessarily synchronized to SAP Marketing Cloud. Only the following followers are synchronized: Those who followed the LINE account before the LINE integration went live and have initiated an
interaction with the LINE account after the LINE integration went live Those who follow the LINE account after the LINE integration went live Creation and execution of LINE campaigns through SAP Marketing Cloud Analytical reports about the acquisition of LINE followers, including reports predefined by SAP and custom reports that you can build with a CDS view Analytical reports about LINE interactions, including reports predefined by SAP and custom reports that you can build with a CDS view For information about setting up and administering the LINE integration, see the following documents: Setting Up the LINE Integration [page 78] Administering the LINE Integration [page 84] For extensibility options, see Extensibility [page 86]. For the descriptions of the business functions, see the following documents: Followers of Digital Accounts Attributes Related to Followers of Digital Accounts LINE Campaigns
4.2.1.4.1 Setting Up the LINE Integration
Set up the connection between SAP Marketing Cloud and your LINE account.
Procedure
1. Create communication configurations for the inbound communication and outbound communication, respectively. For more information, see Creating Communication Configurations [page 79].
2. Create your LINE account in SAP Marketing Cloud. For more information, see Creating a LINE Account [page 83].
3. Create a job based on the template Digital Accounts: Process Inbound Messages. This job is required for the synchronization of followers and interactions. For more information, see Creating and Scheduling Application Jobs [page 84].
78
PUBLIC
Integration Guide Integration Scenarios
Results
The system synchronizes followers and follower interactions from the LINE server to SAP Marketing Cloud automatically.
Note
Not all LINE followers of a LINE account are necessarily synchronized to SAP Marketing Cloud. Only the following followers are synchronized: Those who followed the LINE account before the LINE integration went live, but have initiated an
interaction with the LINE account since the LINE integration went live Those who follow the LINE account after the LINE integration went live
4.2.1.4.1.1 Creating Communication Configurations
Create the configurations required for the communication between SAP Marketing Cloud and the LINE server.
Prerequisites
A business role that contains the Communication Management (SAP_CORE_BC_COM) business catalog is required. You can use the standard business role Administrator (SAP_BR_ADMINISTRATOR), which contains the Communication Management business catalog and other administration-related catalogs. Alternatively, you can create custom business roles using the Maintain Business Roles app.
Context
The LINE integration involves communication in both the inbound and outbound directions.
Inbound Communication
You must define a servlet for the inbound communication. In the inbound communication, the LINE server pushes to your servlet LINE events as well as messages that followers send to a LINE account. Then the servlet forwards the LINE events and messages to SAP Marketing Cloud by calling the private ICF service <host name>/sap/cuan/ntwrk/. The inbound communication requires a communication system/communication arrangement pair. In addition, you need to create a communication user for the inbound communication. When calling the private ICF service to forward the LINE events and messages to SAP Marketing Cloud, your servlet must authenticate itself with this communication user first.
Integration Guide Integration Scenarios
PUBLIC
79
Outbound Communication The outbound communication involves synchronizing data (for example, basic follower information) from the LINE server and executing LINE campaigns through SAP Marketing Cloud. The outbound communication requires a communication system/communication arrangement pair. The following communication scenarios are relevant to the LINE integration: Marketing Network Channel Events Integration (SAP_COM_0174) Marketing Campaign Execution LINE Integration (SAP_COM_0218) For detailed instructions, see Configuring the Inbound Communication [page 80] and Configuring the Outbound Communication [page 82]. For general information about communication management, see Communication Management.
4.2.1.4.1.1.1 Configuring the Inbound Communication
Create the communication user, communication system, and communication arrangement required for the inbound communication.
Customer Implementation
You must define a servlet for the inbound communication. This servlet receives the LINE events and messages pushed by the LINE server and then forwards them to SAP Marketing Cloud by calling the private ICF service <host name>/sap/cuan/ntwrk/.
Creating the Communication User
Proceed as follows: 1. Log into SAP Fiori launchpad with a business role that contains the Communication Management
(SAP_CORE_BC_COM) business catalog. 2. Open the Maintain Communication Users app. 3. Choose New.
The Create Communication User dialog box appears. 4. Fill in the following fields:
User Name and Description (for example, LINE_EVENT and LINE Event) Password 5. Save the communication user. A communication user ID is generated automatically.
Note
When calling the private ICF service, your servlet should authenticate itself with the communication user ID instead of the user name.
80
PUBLIC
Integration Guide Integration Scenarios
Do not exit SAP Fiori launchpad.
Creating the Communication System
This communication system is a dummy one. The purpose of it is to bind the communication user that you created earlier with the communication arrangement that you will create later. To create the communication system, proceed as follows: 1. Open the Communication Systems app. 2. Choose New.
The New Communication System dialog box appears. 3. Enter a system ID and its name, for example, LINE_EVENT and LINE Event. Choose Create.
The editing screen for the communication system appears. 4. A host is irrelevant to the inbound communication. Enter dummy in the Host Name field to assign a dummy
host. 5. Assign the communication user created earlier to this communication system, as follows:
1. In the User for Inbound Communication section, choose + (Add). The New Inbound Communication User dialog box appears.
2. Enter the user created earlier and select the authentication method User Name and Password. 6. Save and activate the communication system.
Do not exit SAP Fiori launchpad.
Creating the Communication Arrangement
Proceed as follows: 1. Open the Communication Arrangements app. 2. Choose New.
The New Communication Arrangement dialog box appears. 3. Enter scenario SAP_COM_0174 and an arrangement name. Choose Create.
The editing screen for the communication arrangement appears. 4. In the Communication System field, enter the communication system created earlier. 5. Save and activate the communication arrangement.
Next Steps
Configuring the Outbound Communication [page 82]
Integration Guide Integration Scenarios
PUBLIC
81
4.2.1.4.1.1.2 Configuring the Outbound Communication
Create the communication system and communication arrangement required for the outbound communication.
Creating the Communication System
Proceed as follows:
1. Open the Communication Systems app. 2. Choose New.
The New Communication System dialog box appears. 3. Enter a system ID and its name, for example, LINE_API and LINE API. Choose Create.
The editing screen for the communication system appears. 4. Under Technical Data General , enter api.line.me in the Host Name field, which is the host name of
the LINE server. Choose Save.
Note
If you have your own logic for getting and posting LINE data through another server, then enter the host name of that server instead.
5. Set the authentication method to None, as follows: 1. In the User for Outbound Communication section, choose + (Add). The New Outbound User dialog box appears. 2. Select the authentication method None. 3. Choose Create.
6. Save and activate the communication system. Do not exit SAP Fiori launchpad.
Creating the Communication Arrangement
Proceed as follows: 1. Open the Communication Arrangements app. 2. Choose New.
The New Communication Arrangement dialog box appears. 3. Enter scenario SAP_COM_0218 and an arrangement name. Choose Create.
The editing screen for the communication arrangement appears. 4. In the Communication System field, enter the communication system that you created earlier. 5. Activate all the outbound services by selecting the Active checkboxes. 6. Save and activate the communication arrangement.
82
PUBLIC
Integration Guide Integration Scenarios
Next Steps
Creating a LINE Account [page 83]
4.2.1.4.1.2 Creating a LINE Account
Create a LINE account in SAP Marketing Cloud.
Prerequisites
A business role that contains the Marketing - Master Data (SAP_CEC_BC_MKT_PRD_PC) business catalog is required. You can use the standard business role Marketing Expert (SAP_BR_MARKETING_EXPERT), which contains the Marketing - Master Data business catalog and other marketing-related catalogs. Alternatively, you can create custom business roles using the Maintain Business Roles app.
Procedure
1. Log into SAP Fiori launchpad with a business role that contains the Marketing - Master Data (SAP_CEC_BC_MKT_PRD_PC) business catalog.
2. Open the Digital Accounts app. 3. On the landing page, choose Create Digital Account.
The Select Digital Account Type dialog box appears. 4. Select LINE Account.
The editing screen for the LINE account appears. 5. Select the marketing area and enter the required information. Choose Create. 6. In the Channel Console, enter the URI of your servlet on the relevant configuration page.
Results
The LINE account appears with the Active status on the landing page of the Digital Accounts app. By default, the LINE account inherits the profile picture from the LINE platform. If there is no profile picture set on the LINE platform, the system sets the image assigned to the LINE communication medium in the Manage Images app as the profile picture of the LINE account. Clicking the account displays various tabs that contain different kinds of information about the official account. The Information tab contains basic information about the LINE account and the credentials. You can change the profile picture, credentials, and so on, by clicking the Edit button.
Integration Guide Integration Scenarios
PUBLIC
83
Next Steps
Creating and Scheduling Application Jobs [page 84]
4.2.1.4.2 Administering the LINE Integration
Learn about the system administration activities relevant to the LINE integration.
4.2.1.4.2.1 Creating and Scheduling Application Jobs
Learn about the application jobs required for the LINE integration.
Required Application Job
To use the LINE integration, you must create an application job using the following template:
Application Job Template Digital Accounts: Process Inbound Messages
Description
A job created using this template creates contacts and inter actions from digital accounts, including LINE official ac counts, in SAP Marketing Cloud. For more information, see Digital Accounts: Process Inbound Messages.
Checking the Application Log
You can find a log of the application job from the Application Logs app using category CUAN and subcategory CUAN_NTWRK as filters. Alternatively, you can find the log directly from the Marketing Application Jobs app. From the application job list, click the icon next to the application job.
Required Business Role
A business role that contains the Marketing - Business Administration (SAP_CEC_BC_MKT_ADM_PC) business catalog is required for scheduling application jobs and checking logs. You can use the standard business role
84
PUBLIC
Integration Guide Integration Scenarios
Administrator - Marketing (SAP_BR_ADMINISTRATOR_MKT), which already contains this business catalog. Alternatively, you can create custom business roles using the Maintain Business Roles app.
4.2.1.4.2.2 Activating, Deactivating, and Restricting a LINE Account
You can set a LINE account to any of these statuses in the Digital Accounts app: Active, Inactive, and Restricted.
Activating a LINE Account
To use the full functionality of the LINE integration, you must set a LINE account to Active status. When completing creating a LINE account, the status of the account is set to Active automatically. To set a LINE account from Restricted status to Active status, choose the Activate button. To set a LINE account from Inactive status to Active status, choose the Switch to Restricted Mode button and then the Activate button.
Deactivating a LINE Account
If you do not want to connect to a LINE account, for example, because the account is no longer in use, deactivate it by choosing the Deactivate button.
Restricting a LINE Account
When a LINE account is restricted, the outbound connection to the account stops working. Therefore, the following functions become unavailable: Execution of LINE campaigns through SAP Marketing Cloud Synchronization of basic follower information When a LINE account is restricted, there is no impact on the inbound connection from the account. The synchronization of interactions between followers and the account still works and the messages that followers send to the account are still synchronized. To set a LINE account to Restricted status, choose the Switch to Restricted Mode button.
Integration Guide Integration Scenarios
PUBLIC
85
4.2.1.4.2.3 Overview of Business Catalogs Required for Different Business Functions
Different business functions require different business catalogs. Learn about the business catalogs that are required for the functions related to the LINE integration and assign business roles to business users appropriately.
The following table lists the business catalogs that are required for different functions:
Business Function
Required Business Catalog
Standard Business Role That Can Be Used
Functions Available with the Digital Accounts App
Marketing - Data (fka Products) (SAP_CEC_BC_MKT_PRD_PC)
Marketing Expert (SAP_BR_MARKETING_EXPERT)
Contact Profiles of LINE Followers
Marketing - Contacts and Profiles Base (SAP_CEC_BC_MKT_DMB_PC)
Marketing - Contacts and Profiles Standard (SAP_CEC_BC_MKT_DMS_PC)
Segmentation
Marketing Segmentation (SAP_CEC_BC_MKT_SEG_PC)
LINE Campaigns
Marketing - Campaign Management (SAP_CEC_BC_MKT_CPM1_PC)
Custom analytical reports in the Query Marketing - Data (fka Products)
Browser app
(SAP_CEC_BC_MKT_PRD_PC)
Query Browser (SAP_CA_BC_VDM_BROWSE)
Quick Launch
Marketing - Quick Launch (SAP_CEC_BC_MKT_COM_PC, Depre cated as of 2011)
4.2.1.4.3 Extensibility
Customize the way that you use the LINE integration.
Custom Fields
You can add custom fields to the Digital Accounts app using the Custom Fields app. When creating custom fields in that app, use business context MKT_DIGITAL_ACCOUNT.
86
PUBLIC
Integration Guide Integration Scenarios
Due to ABAP DDIC restrictions, only a defined number of fields and characters can be created for each business context.
Business Context MKT_DIGITAL_ACCOUNT
Description
Maximum Number of Char Maximum Number of Fields acters
Marketing: Digital Account 100
1000
For general information about creating and enabling custom fields, see Custom Fields.
Required Business Role
A business role that contains the Extensibility (SAP_CORE_BC_EXT) business catalog is required for creating custom fields or custom logic. You can use the standard business role Administrator (BR_ADMINISTRATOR), which already contains this business catalog. Alternatively, you can create custom business roles using the Maintain Business Roles app.
4.2.1.5 Integration with Google Analytics
Overview of the integration scenario.
The integration with Google Analytics allows you to do the following: Enrich sales order interactions of type SALES_ORDER with Google Analytics data.
You can enrich a sales order interaction with its source campaign and device category information. For more information, see Interactions: Enrich Sales Orders with Google Analytics. Create interactions with web tracking data from Google Analytics or Google BigQuery. You create query configurations that identify the set of web hits data that you want to retrieve from Google Analytics or Google BigQuery. You define mapping values that identify how to map the data retrieved from Google to the interaction data in SAP Marketing Cloud. For more information, see Overview of Create Interactions Scenario. Match and merge additional contact ID information in SAP Marketing Cloud with data retrieved from Google Analytics or Google BigQuery. You create query configurations that identify the contact ID information that you want to retrieve. You import contact ID data which goes through the match and merge process. For more information, see Overview of Match and Merge Scenario.
Note
You can set up one or more of the scenarios, depending on your needs.
Integration Guide Integration Scenarios
PUBLIC
87
Configuration Settings
For a complete description of the configuration settings required for the integration scenario, see the Integration Guide.
Integration Package
For more information about the Google Analytics Integration with SAP Marketing Cloud/SAP Marketing integration package, see the SAP API Busines Hub .
4.2.1.6 Integration with Data Management Platforms
With this integration scenario, you can capture and replicate Data Management Platform (DMP) IDs from DMP providers, such as Adform. A DMP ID is mapped to a commerce contact ID and stored inside SAP Marketing Cloud. For more information about Adform, see Advertiser Edge by Adform A/S . The following graphic shows the overall process:
To use this integration, you must configure SAP Marketing Cloud.
4.2.1.6.1 Configuring SAP Marketing Cloud
To establish communication with the OData service, you perform procedures in SAP Marketing Cloud. The overall process is as follows:
1. Define a Communication User [page 89] You can use an existing communication user, or create a new one.
88
PUBLIC
Integration Guide Integration Scenarios
2. Set Up the Communication System [page 89] After defining your communication user, set up a communication system for the DMP integration scenario.
3. Set Up the Communication Arrangement [page 90] After setting up the communication system, set up the communication arrangement for the DMP integration scenario.
4.2.1.6.1.1 Define a Communication User
You can use an existing communication user, or create a new one.
Procedure
1. Log on to your SAP Marketing Cloud system with a user that has administrator authorizations. 2. Launch the Maintain Communication Users app and choose New. 3. Enter the required User Name, Description, and Password. 4. Create and save your user.
Note down the user data for further processes.
Task overview: Configuring SAP Marketing Cloud [page 88] Next task: Set Up the Communication System [page 89]
4.2.1.6.1.2 Set Up the Communication System
After defining your communication user, set up a communication system for the DMP integration scenario.
Prerequisites
To set up a communication system and communication arrangement, you require the Communication Management (SAP_CORE_BC_COM) business catalog role.
Procedure
1. Log on to your SAP Marketing Cloud system with a user that has administrator authorizations.
Integration Guide Integration Scenarios
PUBLIC
89
2. From the SAP Fiori launchpad, choose the Communication Systems app. 3. Choose New. 4. Enter a system ID and name for your communication system. 5. Choose Create. 6. On the Communication System page, enter the following:
a. Under Technical Data, enter dummy as the Host Name to assign a dummy host. This is a dummy communication system as its only purpose is to bind the communication user that you previously created to the communication arrangement that you will create in the next step.
b. Under User for Inbound Communication, choose (+) and enter your communication user name. c. For Authentication Method, select User Name and Password. 7. Save your changes and exit the app.
Task overview: Configuring SAP Marketing Cloud [page 88]
Previous task: Define a Communication User [page 89]
Next task: Set Up the Communication Arrangement [page 90]
4.2.1.6.1.3 Set Up the Communication Arrangement
After setting up the communication system, set up the communication arrangement for the DMP integration scenario.
Prerequisites
To set up a communication system and communication arrangement, you require the Communication Management (SAP_CORE_BC_COM) business catalog role.
Procedure
1. Log on to your SAP Marketing Cloud system with a user that has administrator authorizations. 2. From the SAP Fiori launchpad, choose the Communication Arrangements app. 3. Create a new communication arrangement. 4. Select SAP_COM_0343 (Marketing DMP Integration). 5. Choose Create. 6. In the Communication Arrangements screen, do the following:
a. Under Common Data, choose the communication system that you created previously.
90
PUBLIC
Integration Guide Integration Scenarios
b. Under Inbound Communication, choose the communication user name for inbound services that you assigned to the communication system.
7. Save your changes and exit the app.
Task overview: Configuring SAP Marketing Cloud [page 88]
Previous task: Set Up the Communication System [page 89]
4.2.2 Landing Pages and Forms
Integration options for landing pages and forms.
Landing Pages
Find out how to get data entered on external landing pages into SAP Marketing Cloud. For more information, see Landing Pages and Forms [page 91].
Note
If you create a landing page (with or without a form) using the landing page editor in the Content Studio, you can publish your page immediately. There is no configuration necessary. For more information, see Landing Page Design.
Forms
If you use forms standalone, the following documentation is relevant:
Custom integration allows you to host forms on your own Web server and connect them to your SAP Marketing Cloud system. For more information, see Custom Integration of Forms [page 92].
Note
If you use forms as part of landing pages, custom integration is not relevant. You need only the documentation for standard integration and form publication. Please also note that a form does not need to be published in order to use it in a landing page.
Standard integration allows you to host forms on your own Web server and to connect them to your SAP Marketing Cloud system using an SAP integration service on the SAP Business Technology Platform. For more information, see Standard Integration of Forms [page 102].
You can automate the process of making the form files available on customer web servers. For more information, see Form Publication [page 105].
You can captcha configuration to enhance the security of your forms and decrease vulnerability to malicious attacks by bots that send fraudulent contact data into your system. For more information, see Setting Up Captcha Configuration for Forms [page 264].
Integration Guide Integration Scenarios
PUBLIC
91
4.2.2.1 Custom Integration of Forms
Custom integration of forms supports the technical user with specific integration tasks when deploying forms in the customer's Web server. You can alternatively integrate a form into a landing page and publish it immediately out-of-the-box.
Use
This document provides details for the technical user to support with implementing an integration service between the HTML-based frontend and the OData-based backend when deploying forms in the customer's Web server.
Setting up Forms
In SAP Marketing Cloud , you are provided with the Forms content type in the Content Studio app. This allows you to design forms to collect interaction contact and marketing permission data. For security and performance reasons, you must deploy the forms you create on your Web server to make them available to the internet. The Web server must send the collected data to the server of SAP Marketing Cloud using the public OData service CUAN_CONTENT_PAGE_RESULT_SRV. The service saves the data and triggers follow-on actions. Implementation of forms includes of the following: Deploying the files onto your Web server Implementing the Web server in order to forward the results to SAP Marketing Cloud
Related Information
Forms Form Publication [page 105]
92
PUBLIC
Integration Guide Integration Scenarios
4.2.2.1.1 Creating the Communication Arrangement
To prepare for the technical implementation of forms, the administrator must create a user, a communication system, and a communication arrangement.
Create a Communication User
1. Open the Maintain Communication Users app and click New. 2. Enter a username, for example MKT_FORM_RESULT_USER, and a description, for example Marketing -
Form Result User. 3. Enter a password. 4. Click Create.
Create a Communication System
1. Open the Communication Systems app and click New. 2. Enter a system ID and Name, for example MKT_FORM_TEST_SERVER. 3. Enter the domain name of the server you host your form on. 4. Add the previously created communication user under User for Inbound Communication. 5. Click Save.
Create a Communication Arrangement
1. Open the Communication Arrangements app and click New. 2. Select the integration scenario SAP_COM_0023 (Marketing - Form Integration). 3. If you like, you can adjust the proposed Arrangement name before clicking Create. 4. Select the previously created communication system under Common Data. 5. The previously created communication user should appear automatically under Inbound Communication.
If one does not appear, return to the communication system and make sure that a user was added under User for Inbound Communication. 6. Click Save.
The communication user you created has the integration role assigned from the arrangement, and is ready for use in your integration.
4.2.2.1.2 Deploying the Form
The source code (HTML) for every form you design must be downloaded using the user interface and deployed on your Web server. The HTML file that is generated describes the design and the content of the specific form.
Integration Guide Integration Scenarios
PUBLIC
93
In addition, you must download a style sheet (CSS) and a JavaScript file and adapt them according to your requirements and your system setup. This step is required for your initial system setup and allows you to deploy the CSS and JavaScript files.
Note
You do not need to adapt these files again until you perform an upgrade to a new release. Adapting the files when you upgrade ensures that you can avail of new features.
By default, the HTML file tries to load both files with the names sapContentPage.css and sapContentPage.js from the same folder in which the HTML file is located. If you want to adjust those names or the file paths you must change the HTML file content.
4.2.2.1.3 Adjusting the JavaScript File
After downloading the JavaScript file you must adjust the Web service path written in the file.
The default base path is the path for the OData service on the SAP Marketing Cloud server:
/sap/opu/odata/sap/CUAN_CONTENT_PAGE_RESULT_SRV
You must adjust this path according to the Web server implementation (see section Implementing the Result OData Service [page 94]).
When a user opens a form, the path is loaded using an HTTP HEAD request to fetch a CSRF token. Further data requests are sent to the result path, which is added to the base path. The result path can be adjusted or left empty in the JavaScript file. The default path ResultHeaders describes the OData service entity used for the results.
You are not required to perform any implementation for the front end. The JavaScript that is delivered collects the user input independently. It is possible to adapt and enhance the form HTML file that is generated, but you must preserve the integrity of the standard structure.
4.2.2.1.4 Implementing the Result Service
You must implement your Web server to enable it to receive the requests of the form JavaScript files and forward them to theSAP Marketing Cloud server. By default, the requests are ready for the result service CUAN_CONTENT_PAGE_RESULT_SRV and do not need to be adjusted.
Note
In some usage scenarios, the request data must be enhanced to enable all features. To do this, you must decode the JSON payload string and add the appropriate attributes before encoding the JSON string again for the result service.
94
PUBLIC
Integration Guide Integration Scenarios
Caution
The actual implementation depends on the technology and development language that you use in your company. The sample code provided below is an example PHP implementation. SAP does not take responsibility if you use it in your productive system.
To use this PHP implementation, you must adjust the BasePath and ResultHeadersPath at the beginning of your Javascript file to read as follows:
(function () { "use strict"; var C = { BasePath: "./myLandingPageIntegrationScript.php", ResultHeadersPath: "",
...
Here myLandingPageIntegrationScript.php stands for the name of the PHP script, and must be replaced by the name of your PHP script.
PHP Example
Sample Code
<?php /**
* This class is an example implementation * of a PHP based form integration. * Note: This is a template, which is used at your own risk. */ class LandingPageIntegration {
/** * The BasePath is the URL for the system * including the form result service. * * @var string */
const BASE_PATH = "https://<server>:<port>/sap/opu/odata/sap/ CUAN_CONTENT_PAGE_RESULT_SRV/";
/** * The ResultHeadersPath is the name of the ResultHeaders entity * which is used for processing the form results. * * @var string */
const RESULT_HEADERS_PATH = "ResultHeaders"; /**
* The credentials are used for authenticating on the system. * This is usually a dedicated system or communication user * with the integration role assigned. * * @var string */ const CREDENTIALS = "USERNAME:PASSWORD"; /** * The cookies are remembered between consecutive OData requests * to implement the session handling * and security measures of the SAP Gateway. *
Integration Guide Integration Scenarios
PUBLIC
95
* @var string */ private $cookies = ""; /** * The CSRF-Token is required for the OData service communication * and must be fetched before it is possible * to perform any changing requests such as 'POST'. * * @var string */ private $csrfToken = null; /** * This method is the main entry point * for processing the requests received from forms. */ public function execute() {
switch ($_SERVER["REQUEST_METHOD"]) { case "POST": $this->handlePostRequest(); break;
} } /**
* POST requests must be forwarded to the system * and the responses must be passed to the client * to ensure correct form integration. */ private function handlePostRequest() {
// first fetch the csrf-token $this->fetchCsrfToken(); // read the POST data sent by the form $requestBody = @file_get_contents("php://input"); $requestData = json_decode($requestBody); // optional: enhance the request data with the IP address for tracking purposes $requestData->IpAddress = $_SERVER["REMOTE_ADDR"]; // optional: add the campaign id to connect all form interactions to your campaign // $requestData->CampaignId = "your-campaign-id"; // send the prepared request data to the system $requestString = json_encode($requestData); $response = $this->sendHttpRequest("POST", $this::BASE_PATH . $this::RESULT_HEADERS_PATH, $requestString); // print the response echo $response; } /** * Send a 'HEAD' request to fetch * the required CSRF-Token from the OData service. * If the HEAD request fails, a 'GET' request is performed. */ private function fetchCsrfToken() { $this->sendHttpRequest("HEAD", $this::BASE_PATH, null); if (! $this->csrfToken) {
// HEAD request failed -> fallback using GET $this->sendHttpRequest("GET", $this::BASE_PATH, null); } } /** * This method performs a synchronous HTTP request
96
PUBLIC
Integration Guide Integration Scenarios
* and returns its response.
*
* @param string $method
*
The HTTP method (e.g. 'HEAD', 'POST')
* @param string $path
*
The URL for the request
* @param string $body
*
The request payload (POST data)
* @return string The response
*/
private function sendHttpRequest($method, $path, $body)
{
// first create stream context
$context = $this->createStreamContext($method, $body);
// perform http request $response = file_get_contents($path, false, $context);
if ($response === false) { // request failed - print error for analysis $error = error_get_last(); if (is_array($error)) { echo $error["message"]; } else { echo $error; }
}
// process response headers $this->readResponseHeaders($http_response_header);
// return response
return $response;
}
/**
* This method creates a stream context, which is used for the HTTP
request.
* It configures the context for
* the authorization, content-type, cookies, and csrf-token.
*
* @param string $method
*
The HTTP method
* @param string $body
*
The request payload (POST data)
* @return resource The stream context
*/
private function createStreamContext($method, $body)
{
// basic authorization uses base64 encoded credentials
$credentials = base64_encode($this::CREDENTIALS);
// build http request headers $headers = array(
"Authorization: Basic " . $credentials, "Accept: application/json", "Content-Type: application/json" );
if ($this->cookies) { // add remembered cookies array_push($headers, "Cookie: " . $this->cookies);
}
token
// add x-csrf-token header for fetching or using the already fetched $csrfToken = ($this->csrfToken ?: "Fetch"); array_push($headers, "x-csrf-token: " . $csrfToken);
Integration Guide Integration Scenarios
PUBLIC
97
// build complete options array $options = array(
"http" => array( "header" => $headers, "method" => $method, "content" => $body, "ignore_errors" => true, "max_redirects" => 0
) ); // return stream context using the built options return stream_context_create($options); } /** * This method processes the HTTP response headers * in order to read the fetched CSRF-Token and cookies. * * @param array $responseHeaders */ private function readResponseHeaders($responseHeaders) { // loop response headers foreach ($responseHeaders as $responseHeader) {
// split header name from value $parts = explode(" ", $responseHeader); // handle response header based on name switch (strtolower($parts[0])) {
case "HTTP/1.0": // status code http_response_code($parts[1]); break;
case "x-csrf-token:": // save fetched csrf-token $this->csrfToken = $parts[1]; break;
case "set-cookie:": // set received cookies $this->cookies .= $parts[1]; break;
} } } } // initialize the integration class and start the processing $landingPageIntegration = new LandingPageIntegration(); $landingPageIntegration->execute();
Java Example
Sample Code
package com.sap.hpa.cei.cntpg.man.integration; /**
* This class is an example implementation * of a Java-based form integration. * Note: This is a template, which is used at your own risk. */ import java.io.BufferedReader; import java.io.IOException; import java.io.InputStream;
98
PUBLIC
Integration Guide Integration Scenarios
import java.io.InputStreamReader; import java.io.OutputStream; import java.net.CookieHandler; import java.net.CookieManager; import java.net.HttpURLConnection; import java.net.URL; import javax.servlet.ServletException; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import sun.misc.BASE64Encoder; public class IntegrationServlet extends HttpServlet {
private static final long serialVersionUID = 1L; /**
* The BasePath is the URL for the system including the form result * OData service. Note: It needs to include the trailing slash (/). * * @var String */ private static final String BASE_PATH = "https://<server>:<port>/sap/opu/ odata/sap/CUAN_CONTENT_PAGE_RESULT_SRV/"; /** * The ResultHeadersPath is the name of the ResultHeaders entity which is used * for processing the form results. * * @var String */ private static final String RESULT_HEADERS_PATH = "ResultHeaders"; /** * The credentials are used for authenticating on the system. This is usually a * dedicated system or communication user with the integration role assigned. * * @var String */ private static final String CREDENTIALS = "USERNAME:PASSWORD"; /** * The cookie manager remembers cookies between consecutive OData requests to * implement the session handling and security measures of the SAP Gateway. * * @var CookieManager */ private CookieManager cookieManager = null; @Override protected void doHead(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { } /** * Handle POST requests containing the results of forms */ @Override protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException { String content = this.readContent(request.getReader()); String csrfToken = this.fetchCsrfToken(); String responseText = this.postData(content, csrfToken); response.getWriter().write(responseText); } /** * Read request body */ private String readContent(BufferedReader reader) throws IOException { StringBuffer stringBuffer = new StringBuffer();
Integration Guide Integration Scenarios
PUBLIC
99
String line = null; while ((line = reader.readLine()) != null) {
stringBuffer.append(line); } return stringBuffer.toString(); } /** * Send a HEAD request to fetch the CSRF token */ private String fetchCsrfToken() throws IOException { HttpURLConnection connection = this.createConnection(BASE_PATH, "HEAD", null); connection.connect(); String csrfToken = connection.getHeaderField("x-csrf-token"); connection.disconnect(); return csrfToken; } /** * Send POST request to forward the form result to the backend system */ private String postData(String data, String csrfToken) throws IOException { // open HTTP connection and send body HttpURLConnection connection = this.createConnection(BASE_PATH + RESULT_HEADERS_PATH, "POST", csrfToken); connection.setDoOutput(true); OutputStream outputStream = connection.getOutputStream(); outputStream.write(data.getBytes()); connection.connect(); // read success or error response InputStream inputStream; if (200 <= connection.getResponseCode() && connection.getResponseCode() <= 299) {
inputStream = connection.getInputStream(); } else {
inputStream = connection.getErrorStream(); } InputStreamReader inputStreamReader = new InputStreamReader(inputStream); BufferedReader reader = new BufferedReader(inputStreamReader); String response = this.readContent(reader); connection.disconnect(); return response; } private HttpURLConnection createConnection(String path, String method, String csrfToken) throws IOException { if (this.cookieManager == null) {
// create the cookie manager this.cookieManager = new CookieManager(); CookieHandler.setDefault(this.cookieManager); } // open HTTP connection and set relevant headers HttpURLConnection connection = (HttpURLConnection) new URL(path).openConnection(); connection.setRequestMethod(method); connection.setRequestProperty("Accept", "application/json"); connection.setRequestProperty("Content-Type", "application/json"); connection.setRequestProperty("Connection", "keep-alive"); // set base64-encoded authorization header BASE64Encoder encoder = new BASE64Encoder(); String credentials = encoder.encode(CREDENTIALS.getBytes()); connection.setRequestProperty("Authorization", "Basic " + credentials); // set CSRF token header to 'Fetch' or to the actual token value if available if (csrfToken != null) { connection.setRequestProperty("x-csrf-token", csrfToken); } else {
100
PUBLIC
Integration Guide Integration Scenarios
connection.setRequestProperty("x-csrf-token", "Fetch"); } return connection; } }
System User Authentication
The result service CUAN_CONTENT_PAGE_RESULT_SRV can only be called by users with the corresponding authorization. You must use the user created for integration scenario SAP_COM_0023. The example PHP script shows the authentication using an HTTP header named Authorization using Basic Authentication (user and password).
Contact Identification
The forms integration offers different ways to identify the Web user who visits the form. The following usage scenarios are supported: Scenario A: The Web user is anonymous (unknown)
In this scenario, the user cannot be identified on the form. Scenario B: The Web user has accessed the form using a tracking link in an SAP Marketing Cloud email.
Scenario B does not require any additional implementation effort. The form script performs the required actions autonomously. If the form is accessed using a SAP Marketing Cloud email, the link contains a tracking ID that is sent along with the data requests. This ID is used to identify the user that received the email.
Prefill Contact Data
When a Web user who accesses a form is identified, it is possible to prefill data for the Input and Permission elements in the form.. Selecting the Prefill Contact Data checkbox allows the form elements to be filled with data for the identified contact, which is maintained in the SAP Marketing Cloud system. To support the prefill of contact data, the Web server implementation needs to pass the response data from the SAP Marketing Cloud system to the form (web client) that initiated the request. The SAP Marketing Cloud system provides all necessary data for forms with the Prefill Contact Data setting. There is no additional effort for the implementation, apart from the forwarding of response data.
Integration Guide Integration Scenarios
PUBLIC
101
Optional Attributes
In order to complete the form integration, you can enhance the OData requests with the following optional attributes: IPAddress
The IP address of the web client visiting a form can be saved in order to have additional evidence that the user submitted the form, and gave marketing permissions and contact data. CampaignId The campaign ID can be supplied to connect the interactions created out of the form to a specific SAP Marketing Cloud campaign. If the form is opened with a URL parameter sap-campaign-id with its value set to the ID, it is automatically added to all form requests. This connection will also be created if the form is opened out of a SAP Marketing Cloud email sent as part of a campaign.
4.2.2.2 Standard Integration of Forms
The SAP Marketing Cloud offers a built-in integration service, which allows you to use forms on your web server without having to implement a custom integration of forms service as described in Custom Integration of Forms [page 92].
Use This document provides details for the technical user to support with implementing an integration between the HTML-based based frontend and the OData-based backend when deploying forms in the customer's Web server.
Setting Up Forms
In SAP Marketing Cloud, you are provided with the Forms content type in the Content Studio app.. This allows you to design forms to collect interaction contact and marketing permission data.
For security and performance reasons, you must deploy the forms you create on your Web server to make them available to the internet. The form sends the collected data to an elastic service on the SAP Cloud Integration, which forwards the data to the SAP Marketing Cloud using the public OData service CUAN_CONTENT_PAGE_RESULT_SRV. The service saves the data and triggers follow-on actions.
Implementation of forms includes of the following: Preparing the form files Deploying the files onto your Web server
4.2.2.2.1 Deploying the Form
The source code (HTML) for every form you design must be downloaded using the user interface and deployed on your Web server. The HTML file that is generated describes the design and the content of the specific form.
102
PUBLIC
Integration Guide Integration Scenarios
In addition, you must download a style sheet (CSS) and a JavaScript file and adapt them according to your requirements and your system setup. This step is required for your initial system setup and allows you to deploy the CSS and JavaScript files.
Note
You do not need to adapt these files again until you perform an upgrade to a new release. Adapting the files when you upgrade ensures that you can avail of new features.
By default, the HTML file tries to load both files with the names sapContentPage.css and sapContentPage.js from the same folder in which the HTML file is located. If you want to adjust those names or the file paths you must change the HTML file content.
4.2.2.2.2 Adjusting the JavaScript File
After downloading the JavaScript file, you must adjust the configuration variables that are included. These variables define how the landing pages communicate with the backend system. Please be aware that the JavaScript file is only delivered in a minified version, which saves resources and increases performance for end users.
The following variables must be adjusted to use the standard landing page integration:
BasePath The default base path is the path for the OData service on the SAP Marketing Cloud server: /sap/opu/odata/sap/CUAN_CONTENT_PAGE_RESULT_SRV/ You must adjust this path to the respective SAP Cloud Integration service URL depending on the data center of your SAP Marketing Cloud system:
SAP Cloud Integration Service URLs Data Center
URL
Sydney (AP)
"https://s4cloudlpicb1aab197.ap1.hana.ondemand.com/ elastic-access/sap/lpi/"
Shanghai (CN)
"https://s4cloudlpiz4055ed249.cn1.hana.onde mand.com/elastic-access/sap/lpi/"
Rot (EU)
"https://s4cloudlpia9f27a988.hana.ondemand.com/elas tic-access/sap/lpi/"
Tokyo (JP)
"https://s4cloudlpib423c25653.jp1.hana.ondemand.com/ elastic-access/sap/lpi/"
Moscow (RU)
"https://s4cloudlpin6265058ca.ru1.hana.onde mand.com/elastic-access/sap/lpi/"
Integration Guide Integration Scenarios
PUBLIC
103
Data Center Sterling (US)
URL
"https://s4cloudlpihe4b6c67a.us3.hana.ondemand.com/ elastic-access/sap/lpi/"
CORS The default value is false and must be changed to true. This change ensures that the landing page sends its requests in the correct manner to support Cross-Origin-Resource-Sharing (CORS).
Note
The value is a boolean value, so you must write false and true without using apostrophes.
CSRFTokenHeader The default value "X-CSRF-Token" can be removed by changing it to an empty string "".
AppendScenarioParameter The default empty value "" must be changed to "_L54AD1F204_", which ensures that the landing page sends the technical parameter as part of its requests. This provides the elastic service on the SAP Cloud Integration with the required scenario information.
Tenant The default empty value "" must be filled with the domain name of your SAP Marketing Cloud system. The name value must respect the following format: "my123456-api.s4hana.ondemand.com".
It's not necessary to change any other parts of the JavaScript file to use the standard functionality.
Example Configuration
Sample Code
'The following is an example of the JavaScript file after you have implemented the above changes: [...](function(){"use strict";var C={BasePath:"https://s4cloudlpia9f27a988.hana.ondemand.com/elastic -access/sap/ lpi/",ResultHeadersPath:"ResultHeaders",CORS:true,CSRFTokenHeader:"",AppendSce narioPa rameter:"_L54AD1F204_",Tenant:"my123456api.s4hana.ondemand.com",Version:"1.2.3"};[...]
104
PUBLIC
Integration Guide Integration Scenarios
4.2.2.3 Form Publication
The automated form publication describes a scenario that makes it possible to automate the process of making the form files available on customer web servers. This scenario replaces the manual activities of downloading the files and uploading them to the web server.
Implementing the Publication Service
A standard solution can't take care of storing the files on the customer web server considering that there are many technologies available and customers might need to adjust the files and their locations to their needs. Therefore, SAP Marketing Cloud provides logic that calls a custom service on the desired target system making it possible to automatically store the files using your own implementation.
Request This publication service needs to be implemented to handle the requests sent by SAP Marketing Cloud. These requests use the HTTP method `POST' with a JSON payload. The format of the JSON body looks as follows:
Sample Code
{ "landingPageKey": "<Form key>", "landingPageName": "<Form name>", "systemId": "<System ID>", "targetId": "<Publication target ID>", "baseDirectory": "<Base directory/folder>", "htmlFileName": "<File name entered by the business user>", "html": "<Form HTML file content>", "css": "<Form CSS file content>", "js": "<Form JS file content>" }
Note
The placeholder texts in the above code sample are updated to mention forms. The technical names however still mention landing pages for compatibilty reasons.
The publication service handling these requests needs to store the form files contained in the JSON attributes "html", "css" and "js" on the file system according to your needs. For this purpose, the implementation can use additional details like the form name, system ID, target ID, or base directory to distinguish between multiple possible locations or projects. Before the request is sent, SAP Marketing Cloud adjusts the file contents using the parameters provided for the publication target. This involves changes the paths to the CSS and JavaScript files in the HTML file content and the service paths in the JavaScript file content. The service implementation needs to store the files in the correct location for the selected publication target. Otherwise the references in the files won't be correct and the form can't be used. If necessary, the implementation can also adjust the files on your side. However, there is also a Business Add-In (BAdI) available to do this in SAP Marketing Cloud.
Integration Guide Integration Scenarios
PUBLIC
105
Response SAP Marketing Cloud expects a response from the publication service containing details about the form address. This address will be displayed to the business user for further usage. The response body needs to conform to a JSON format that looks as follows:
Sample Code
{ "landingPageUrl": "<Public form URL>"
}
Creating the Communication System and Maintaining the Communication User
The communication between SAP Marketing Cloud and your web server is based on a communication arrangement. Therefore, it's necessary to create a related communication system for the desired target system.
1. Open the Communication Systems app and select New. 2. Enter a system ID and name and click Create. 3. Enter the host name of your web server and any additional details needed. 4. If necessary, create an outbound communication user to be used for the publication service on the web
server. You will need to select the appropriate authentication method and enter the related details, for example, a user name and password as well as credentials of a valid user. 5. Be sure to save before creating a communication arrangement.
Creating the Communication Arrangement
1. Open the Communication Arrangements app and select New. 2. Select the scenario SAP_COM_0148, Marketing - Form Publication Integration. 3. Enter a name for the publication target, which will appear on the business user interface, and click Create. 4. Select the previously created communication system. 5. Enter the following additional properties:
The paths to your form integration service and result headers that you prepared during your form integration
The desired folder for the form files as the base directory The paths to the stylesheet (CSS) and JavaScript (JS) files 6. If necessary, select the outbound communication user. 7. Enter the publication path in the section Outbound Services under the entry Deployment Service.
Once the communication arrangement has been created successfully and is active, the Forms content type in the Content Studio app will offer the option to publish a form automatically.
106
PUBLIC
Integration Guide Integration Scenarios
Optional: Implementing Custom Logic for Form Publication
In case the standard publication logic doesn't completely fit your needs, you can adjust it using a custom logic extension point, or Business Add-In (BAdI).
Change File Contents Before Form Publication The BAdI definition Change File Contents Before Form Publication makes it possible to automatically adjust the contents of the HTML, CSS, and JS files. Business Context: Marketing: Form Enhancement Spot: CUAN_ODATA_CONTENT_PAGE BAdI Definition: CUAN_CP_DEPLOY_ADJUST_FILES
Related Information
Custom Integration of Forms [page 92]
4.2.3 Survey
The documentation for survey explains the following: How to integrate survey metadata and survey responses from third-party survey tools into SAP Marketing
Cloud using an OData service. For more information, see Survey OData API [page 890]. How to integrate survey metadata and survey responses from third-party survey tools into SAP Marketing
Cloud using integration flows. For more information, see Integration with Third-Party Survey Providers [page 107].
4.2.3.1 Integration with Third-Party Survey Providers
Integration of Survey Data with SAP Marketing Cloud using SAP Cloud Integration.
For more information about the Survey Data Integration with SAP Marketing Cloud, see Third Party Survey Data Integration with SAP Marketing Cloud .
By supporting the integration of survey data with SAP Marketing Cloud, customers can benefit from the features of third-party tools, such as Qualtrics, Clicktools, SurveyMonkey, SurveyGizmo, and so on. This integration fetches and stores data easily from the third-party tools into SAP Marketing Cloud system.
To achieve this integration, the following iFlows are provided:
Create Survey Data in SAP Marketing Cloud. Retry Loading Buffered Survey Data to SAP Marketing Cloud.
Integration Guide Integration Scenarios
PUBLIC
107
For more information, see Integrating Survey Data with SAP Marketing Cloud.
4.2.4 Extensions
4.2.4.1 Import CSV Using SAP Cloud Integration (Deprecated)
With this integration you can do file-based data load to your SAP Marketing Cloud system. The data is fetched from an SFTP server or, alternatively, posted via HTTP request, and pushed to your system using an OData service.
The package enables you to load the following message types and also provides sample CSV templates: Interactions Accounts Contacts
For more information, see the integration package in the SAP API Business Hub under SAP Marketing Cloud File-Based Data Load .
4.3 Outbound
Sending Emails and Text Messages [page 109] The integration enables you to send emails and text messages using service providers, such as Sinch.
Setting Up External Campaign Execution [page 155] SAP Marketing Cloud allows you to execute campaigns in an external system, and to request the success data for further processing in SAP Marketing Cloud.
Open Channel Integration [page 194] With this integration you create own actions that send data for further processing to an external system, such as SAP Business Technology Platform, when the campaign has been executed. But you can also just implement the inbound side of this integration to get external data in your campaigns.
Mobile, Social, and Digital Channel [page 242]
Setting Up Captcha Configuration for Forms [page 264] Use captcha configuration to enhance the security of your forms and decrease vulnerability to malicious attacks by bots that send fraudulent contact data into your system.
108
PUBLIC
Integration Guide Integration Scenarios
4.3.1 Sending Emails and Text Messages
The integration enables you to send emails and text messages using service providers, such as Sinch. You find the list of integration options under Service Provider and Available Features [page 111]. For information about how to set up the integration with a service provider, see Setting Up Service Provider for Emails and Text Messages [page 110].
Campaign Processing in Detail
In the following you find an example of detailed processing steps for an automated campaign in the system. The campaign uses a dynamic target group and has the actions Send Email and Open Channel assigned.
When the user starts the campaign, the activation runs some consistency checks, for example, the system checks whether all actions and their parameters correct. The activation also schedules one or more background jobs which are started at the defined execution date and time.
Because the campaign uses a dynamic target group the activation schedules the following background jobs:
The first job rebuilds the dynamic target group. It is scheduled for the defined execution date and time. After the first background job has been finished the two other jobs are processing the actions Send Email
and Open Channel in parallel as successor.
Action job Send Email does the following steps:
The job reads the members of target group and split them into smaller packages, for example, into target groups of 500 members.
Packages are processed in parallel tasks in order to reduce the runtime of the complete action and use the available resources of the system in an optimal way. Steps within package: Check permission Create personalized emails Send out emails by handing over them to the email service provider Create interactions for all target group members, also for those where email cannot be sent, because, for example, marketing permission is missing.
After all packages have been executed, the execution status is updated and the background job ends.
Action job Open Channel does the following steps:
The job reads the members of target group and split them into smaller packages, for example, into target groups of 500 members.
Usually packages are processed in parallel tasks in order to reduce the runtime of the complete action and use the available resources of the system in an optimal way. Steps within package: Check permission (if activated by customer extension) Read values of attributes defined in export definition Transfer personalized payload to SAP Cloud Integration Create interactions for all target group members (if activated by customer extension)
After all packages have been executed, the execution status is updated and the background job ends.
Integration Guide Integration Scenarios
PUBLIC
109
After all background jobs have been finished the campaign's execution status is updated. See also Open Channel Integration [page 194].
4.3.1.1 Setting Up Service Provider for Emails and Text Messages
In the following you will find information about how to conduct your system for SAP Marketing Cloud with the required service providers, such as Sinch, for sending out emails and text messages directly out of the system.
Read the following chapters to set up the connection with an email or text message provider.
Note
A system of SAP Marketing Cloud enables you to design and organize marketing campaigns. But to reach your customers, you also need email and text message service provider who take over the data from the SAP system and finally send the text messages and emails.
This service provider must be able to send mass emails and text messages for marketing campaigns, and should also collect bounces and unsubscribes. These providers are also called marketing service providers (MSPs).
Don't mix them up with your email and cell phone providers for normal communication.
Service Provider and Available Features [page 111] The table gives you an overview about the features available for each service provider.
Setting Up Sinch [page 112] With Sinch as service provider, you send mass emails and text messages to your customers and inform them, for example, about your new developments. With this setup you are also enabled to get bounces and complaints for emails, and receive bounces and unsubscribes for text messages.
Setting Up a Generic Email and Text Message Interface [page 116] With this generic email and text message interface, you can conduct any email or text message service provider to a system of SAP Marketing Cloud to send mass messages. With this setup, you're also enabled to get bounces.
Amazon Setup [page 136] The integration with Amazon is very powerful and covers a wide span of functionality for email and text message campaigns.
Usage of Multiple Service Provider Instances [page 146] In case you want to run campaigns for different customers you can use several instances of the same service provider to gain a better overview about your figures and costs.
Campaign Execution Inclusion List [page 149] You use the Campaign Execution Inclusion List app to maintain allowed email addresses and telephone numbers.
Unsubscribe for Emails and Text Messages [page 150] In the following, you learn about the possibilities to unsubscribe from emails and text messages.
Complaints for Emails [page 152]
110
PUBLIC
Integration Guide Integration Scenarios
Complaints for email means that an email recipient classifies emails from dedicated senders as spam. For classifying emails as spam, the email recipient either drops the email to the spam folder of the email provider or declares the email as spam. This technology is also known as email feedback loops.
Troubleshooting for Campaigns [page 154] In case you have issues with the execution of your campaigns, we recommend to read also the troubleshooting in the Administration Guide.
Sender Profiles [page 155] A sender profile allows you to carry out campaigns for different channels in different markets. You can maintain sender profiles for channels, such as email, text message, and mobile push notifications.
4.3.1.1.1 Service Provider and Available Features
The table gives you an overview about the features available for each service provider.
Note
A system of SAP Marketing Cloud enables you to design and organize marketing campaigns. But to reach your customers, you also need email and text message service provider who take over the data from the SAP system and finally send the text messages and emails. This service provider must be able to send mass emails and text messages for marketing campaigns, and should also collect bounces and unsubscribes. These providers are also called marketing service providers (MSPs). Don't mix them up with your email and cell phone providers for normal communication.
Feature Documentation
Sending Emails Bounces for Emails Complaints for Emails Unsubscribe for Emails
Sinch
Amazon
Generic Interface
Setting Up Sinch [page 112] Setting Up Amazon [page 138]
Setting Up a Generic Email and Text Message Interface [page 116]
Yes
Yes
Yes
Scenario ID: SAP_COM_0040 Scenario ID: SAP_COM_0016 Scenario ID: SAP_COM_0234
Yes
Yes
Yes
Scenario ID: SAP_COM_0040 Scenario ID: SAP_COM_0039 Scenario ID: SAP_COM_0234
Yes
Yes
Yes
Scenario ID: SAP_COM_0040 Scenario ID: SAP_COM_0039 Scenario ID: SAP_COM_0234
Yes
Yes
Yes
Scenario ID: SAP_COM_0040 Scenario ID: SAP_COM_0289 Scenario ID: SAP_COM_0234
Integration Guide Integration Scenarios
PUBLIC
111
Feature
Best Sending Time (for emails)
Sinch Yes
Amazon No
Sending Text Messages
Yes
No
Scenario ID: SAP_COM_0041
Bounces for Text Messages
Yes
No
Scenario ID: SAP_COM_0299
Unsubscribes for Text Mes sages
Yes
No
Scenario ID: SAP_COM_0299
Generic Interface
Yes (if supported by con nected email service pro vider)
Yes Scenario ID: SAP_COM_0258
Yes Scenario ID: SAP_COM_0258
Yes Scenario ID: SAP_COM_0258
Related Information
Unsubscribe for Emails and Text Messages [page 150]
4.3.1.1.2 Setting Up Sinch
With Sinch as service provider, you send mass emails and text messages to your customers and inform them, for example, about your new developments. With this setup you are also enabled to get bounces and complaints for emails, and receive bounces and unsubscribes for text messages.
Context
As a preperation we recommend to read the following documents and recommendations in order to not get listed as a spammer Deliverability Best Practices . To be prepared for the onboarding for Sinch as email provider, see Sinch E-Mail 365 - Onboarding Guide (SAP Marketing Cloud customers) and fill out the form provided by Sinch on this page: Sinch E-Mail 365 Provisioning Form . To further ensure proper email deliverability, it is also important to consider IP warm-up. For more on this topic, see CX Works | E-mail Marketing - Trust with a Solid Warm-up Plan .
Note
For already existing customers: If you are changing something in the settings for your system connection after the upgrade from a lower release to release 1902 or higher, you must re-enter the following data: Credentials in the Communication Systems app
112
PUBLIC
Integration Guide Integration Scenarios
Path in the Communication Arrangements app under Outbound Services This is valid for the communication arrangement with scenario ID SAP_COM_0040 and SAP_COM_0041.
Procedure
Follow the steps below to get your service provider up and running:
1. Set up Sinch: You have a Sinch account for: sending emails using http service call sending text messages receiving bounces and unsubscribes for text messages If you need more details or have questions on this solution, send an email to Sinch at DI.email365.onboarding@sinch.com. Check that you got a User and a Password as well as a Host and a Path Prefix from Sinch.
2. To be able to establish the system connection, check that the apps Communication System and Communication Arrangements are assigned to your user.
3. Set up the communication system in the Communication System app.
Note
Use the data from the onboarding material for a proper set-up.
The technical details below may differ from the onboarding material you got from Sinch.
Communication System for Emails System ID: Enter a system ID, such as SINCH_EMAIL. System Name: Enter a system name, such as Sinch Email. Host Name: email-eu1.sapdigitalinterconnect.com User for Outbound Communication: Enter the user name and password you got from Sinch.
Communication System for Text Messages System ID: Enter a system ID, such as SINCH_TEXT_MESSAGE System Name: Enter a system name, such as Sinch Text Message. Host Name: sms-pp.sapmobileservices.com User for Outbound Communication: Enter the user name and password you got from Sinch.
Communication System Details Required for Bounces and Unsubscribes for Text Messages System ID: Enter a system ID, such as SINCH_TEXT_MESSAGE_BOUNCE_UNSUBSCRIBE System Name: Enter a system name, such as Sinch Text Message: Bounce and Unsubscribe. Host Name: livelink.sapmobileservices.com User for Outbound Communication: Enter the App Key as User Name and the Secret as Password.
In case you need to change user and password again later, you will do this also in the Communication System app. 4. Establish the communication arrangement in the Communication Arrangement app. 1. To create a new arrangement choose New, select the required Scenario and enter an Arrangement
Name.
Integration Guide Integration Scenarios
PUBLIC
113
Technical details for the communication arrangement: Communication Arrangement for Emails
Scenario: SAP_COM_0040 Communication Arrangement for Text Messages
Scenario: SAP_COM_0041 Communication Arragement for Bounces and Unsubscribes for Text Messages
Scenario: SAP_COM_0299 2. Select the previously created Communication System. 3. Depending on the used setup enter the following Additional Properties: Enter a Provider ID and Sender
Profile ID, and assign a suitable Marketing Area ID. Note that you use for the setup of SAP_COM_0041 and SAP_COM_0299 the same Provider ID. 4. Under Outbound Communication select the User Name, you created in the Communication System app, you got from Sinch. 5. Under Outbound Services check that the Service Status is activated, and Port 443 is used. In addition, maintain the Path as followed: Scenario: SAP_COM_0040
Path depending on the information you got from Sinch: /in365-api/<accountID>/ notifications or /email/<accountID>/notifications Scenario: SAP_COM_0041 Path: such as /cmn/<accountID>/<accountID>.sms Scenario: SAP_COM_0299 Path: no path 6. Now save your entries. During the save the system establishes the required system connections and creates a provider and sender profile. 5. Finally maintain your sender profiles. For more information, see Sender Profiles [page 155].
Using Several Accounts
If you want to use several accounts, you must do the steps above for each account seperately. To get more information about the dependencies in the setup, see Usage of Multiple Service Provider Instances [page 146].
Related Information
Consuming the Integration APIs [page 395]
114
PUBLIC
Integration Guide Integration Scenarios
4.3.1.1.2.1 Bounces and Unsubscribe for Text Messages
When you want to use unsubscribe and bounces offered by Sinch, you need a connection between your SAP system and Sinch.
Prerequisites
You set up the connection to Sinch. For more information, see Setting Up Sinch [page 112]. In addition, you have also set up the scenario SAP_COM_0041 and SAP_COM_0299.
How It Works
After you did all the settings, the recipients of text messages can unsubscribe and you can collect bounces for text messages. Unsubscribe If the contact does not want to get further text messages, she or he has to send a text message with the word STOP as reply to the received text message. These unsubscribes can happen at any time. The unsubscribe requests are collected on Sinch's side in a queue. A background job then pulls the unsubscribe requests from Sinch and creates corresponding interactions in the system. The system evaluates the interactions and updates marketing permissions for the contact.
Integration Guide Integration Scenarios
PUBLIC
115
In detail the following steps happen:
1. The marketing expert executes a text message campaign. 2. The system sends out the marketing text messages. 3. A recipient is getting the text message on the mobile. 4. The recipient unsubscribes by sending the word STOP as reply to the received text message. Optionally, the
recipient can send back the word STOP plus the campaign ID to unsubscribe from a specific campaign with a specific marketing area. Prerequisite is that the marketing area separation is active and the campaign ID is part of the sent text message, ideally using personalization attributes in the Content Studio. At the end an interaction with type MKT_PERM_OPTOUT and with the marketing area of this campaign is created. 5. The mobile service provider sends the text message with the unsubscribe request to Sinch. 6. Sinch collects unsubscribe requests and bounces in a queue. 7. SAP pulls the unsubscribe requests and bounces, and creates interactions. 8. Based on the interactions the system updates marketing permissions.
Bounces
To see the number of hard and soft bounces, open the corresponding campaign in the Campaigns app. On the Performance tab, you see the actuals under Outbound.
For more information regarding how to handle bounces, see Handling Bounces.
For more information regarding bounce classification, see Email-360 - Bounce Classificatioon - Sinch Community- 3532 .
Related Information
Sinch Live Link 365 Marketing Areas Setting Up Sinch [page 112]
4.3.1.1.3 Setting Up a Generic Email and Text Message Interface
With this generic email and text message interface, you can conduct any email or text message service provider to a system of SAP Marketing Cloud to send mass messages. With this setup, you're also enabled to get bounces.
SAP Marketing Cloud offers a generic interface that transfers the message header and body data in a JSON format.
The system calls
either the service provider directly, if it supports the defined JSON interface natively, or an integration engine like SAP Business Technology Platform (SAP BTP) to transform the message from
SAP format into any kind of legacy formats. The integration engine is optional in this scenario even though it's the most likely use case.
116
PUBLIC
Integration Guide Integration Scenarios
Note
A system of SAP Marketing Cloud enables you to design and organize marketing campaigns. But to reach your customers, you also need email and text message service provider who take over the data from the SAP system and finally send the text messages and emails.
This service provider must be able to send mass emails and text messages for marketing campaigns, and should also collect bounces and unsubscribes. These providers are also called marketing service providers (MSPs).
Don't mix them up with your email and cell phone providers for normal communication.
You've prepared the following data:
Connection data to connect SAP Marketing Cloud with SAP BTP: hostname of SAP BTP logon credentials such as user and password for the outbound communication to SAP BTP Instead of user and password, you can also work with certificates. You activate the certificates in the Communication Systems app during the setup.
Connection data to connect SAP BTP with your service provider: hostname of your service provider logon credentials such as user and password
Optional: Depended on the service provider, you must upload the provider's certificates to the SAP BTP. To upload the certificates on the platform, choose Operations View Manage Keystore Add Certificate and upload the certificate.
In addition, you have access to the following apps: Communication Systems Communication Arrangements Sender Profiles
Set Up with User and Password
Note
The following steps describe the setup by usage of SAP BTP. 1. In the Communication Systems app, you create the system entry by entering:
host name of SAP BTP
Integration Guide Integration Scenarios
PUBLIC
117
logon credentials such as user and password under User for Outbound Communication 2. In the Communication Arrangements app, create a new communication arrangement with the Scenario ID
SAP_COM_0234 or SAP_COM_0258 and a name. Add the communication system from the previous step and make sure that you activated the Service Status and you entered the Path under Outbound Services.
Note
The path doesn't need any path enhancement, such as /send, /bounces, /complaints, or / verifiedSenders.
Example
In SAP BTP you've defined an iFlow with the following settings:
Type of the adapter = HTTPS
Connection address = /sap_mkt_cloud/send
In the communication arrangement, you must enter the Path /http/sap_mkt_cloud without the path enhancement /send.
The Service URL looks, for example, like https://<hostname of SAP Cloud Integration>:443/ http/sap_mkt_cloud.
3. After the activation of your communication arrangement, choose the Sender Profiles app and complete the incomplete entries: Profile ID GNML for emails Profile ID GENS for text messages Open the profile GNML and enter a valid email address as Sender Address.
Set Up with Certificates
Note
The following steps describe the setup by usage of SAP BTP.
1. In the Communication Systems app, you create the system entry by entering host name of SAP BTP and choose the Athentification Method SSL Client Certificate under User for Outbound Communication .
2. In the Communication Arrangements app, create a new communication arrangement with the Scenario ID SAP_COM_0234 or SAP_COM_0258 and a name. Add the communication system from the previous step and make sure that you activated the Service Status and you entered the Path under Outbound Services.
118
PUBLIC
Integration Guide Integration Scenarios
Note
The path doesn't need any path enhancement, such as /send, /bounces, /complaints, or / verifiedSenders.
Example
In SAP BTP you've defined an iFlow with the following settings: Type of the adapter = HTTPS Connection address = /sap_mkt_cloud/send In the communication arrangement, you must enter the Path /http/sap_mkt_cloud without the path enhancement /send.
The Service URL looks, for example, like https://<hostname of SAP Cloud Integration>:443/ http/sap_mkt_cloud.
3. To use the certificates, you have to download them in the Communication Arrangements app for the corresponding communication arrangement under Outbound Communication Download Download Authentification Certificte .
4. Then switch to the SAP BTP, choose Design Artifacts . Then open the iFlow Adapter and select the outbound communication channel that needs the certificate. Under Connection Authorization , select Client Certificate, choose Add Select , and upload the certificate from the Communication Arrangements app. Don't forget to save and deploy the iFlow.
5. After the activation of your communication arrangement, choose the Sender Profiles app and complete the incomplete entries: Profile ID GNML for emails Profile ID GENS for text messages Open the profile GNML and enter a valid email address as Sender Address.
More Information
Consuming the Integration APIs [page 395] SAP Marketing Cloud Connect any email service provider to SAP Marketing Cloud SAP Marketing Cloud Connect any text message service provider to SAP Marketing Cloud Connecting a Customer System to Cloud Integration Cloud Integration How to Setup Secure HTTP Inbound Connection with Client Certificates
Integration Guide Integration Scenarios
PUBLIC
119
4.3.1.1.3.1 Generic Email and Text Message Integration
With this REST service and methods you integrate any email and text message servSAP Cloud Identity Services - Identity Authenticationice provider (SP) with a system of SAP Marketing Cloud. For email you use scenario ID SAP_COM_0234 and for text message you use SAP_COM_0258.
Using the campaign automation, you can send emails or text messages to your customers.
The email bodies contain personalized content and trackable links. Countable interactions are, for example, email opened, link clicked, and email hard bounce. Emails are sent using a REST service to an email SP.
The text messages contain personalized content. Text messages are sent using a REST service API to an SP for text messages.
The integration is a pure outbound scenario. You require an account and license on the email or text message SP's side.
Caution
When you connect an email or text message service provider, it's your responsibility to establish the connection by implementing the methods defined by SAP. This is also valid for required enhancements on the SAP Business Technology Platform (SAP BTP), such as doing the mapping or persisting data.
Methods for Email Integration
HTTP Method
Action
Send Emails POST
Mandatory method Email: Send Emails [page 121]
Get Bounces GET
Email: Get Bounces [page 125]
Get Complaints GET
Email: Get Complaints [page 126]
Get Unsubscribes GET
Email: Get Unsubscribes [page 127]
Path Enhancement (that must be the same in SAP BTP) /send
/bounces /complaints /unsubscribes
120
PUBLIC
Integration Guide Integration Scenarios
HTTP Method
Action
Path Enhancement (that must be the same in SAP BTP)
Get Verified Send ers
GET
Mandatory method Email: Get Verified Senders [page 129]
/verifiedSenders
Methods for Text Message Integration
HTTP Method
Action
Path Enhancement (that must be the same in SAP BTP)
Send POST
Mandatory method Text Message: Send [page 130]
/send
Collect Delivery Status
GET
Text Message: Collect Delivery Status [page 132]
/status
Get Unsubscribes GET
Text Message: Get Unsubscribes [page 134]
/unsubscribes
4.3.1.1.3.1.1 Email: Send Emails
With this method you send the emails to your email service provider (ESP).
Note
This method is mandatory for the integration.
Request
URI: /send HTTP Method: POST
Request Parameters
Parameter bodyContentHTML
Required Yes
Integration Guide Integration Scenarios
Data Type String
Description
Body Content. Format: HTML, JSON encoded
PUBLIC
121
Parameter
Required
bodyContentPlainTex Yes t
campaignId
No
listUnsubscribe
No
outboundId
No
recipient
Yes
recipientName
No
replyTo
Yes
replyToName
Yes
sendAt
No
sender
Yes
senderName
Yes
sourceSystem
No
subjectContentPlain Yes Text
type
No
Data Type String
String
String
String String String String String String String String String
String String
Description
Body Content (for multipart or alternative email MIME). Format: Plain Text, JSON en coded
Campaign ID of the campaign that generates this email. Can be empty for send tests in campaign content and sender profile. Helpful for support.
Header for list unsubscribe in raw format. Possible entries: mailto:<email address>, https::<URL>
Unique identifier of outbound message generated by SAP Marketing Cloud
Recipient (To field)
Recipient name. Not yet sup ported. Format: Plain Text, JSON encoded
Reply-To Address (Reply-To field)
Reply-To Name. Format: Plain Text, JSON encoded
Timestamp for scheduled sends. Format: YYYYMMDDHHMMSS
Sender Address (From field)
Sender Name. Format: Plain Text, JSON encoded
Logical System (Netweaver). Required to get correspond ing bounces and complaints related to outbound mes sages.
Subject; Format: Plain Text, JSON encoded
Indicates for the middleware which integration flow for which type of ESP should be processed
122
PUBLIC
Integration Guide Integration Scenarios
Request Example Sample Code
/send HTTP method POST
Content-Type: application/json Encoding: UTF-8
Body:
{
"type"
: "email",
"outboundId"
: "33fds34534r4",
"campaignId"
: "123456789",
"sourceSystem"
: "XYZCLNT100",
"sendAt"
: "20170328080000",
"sender"
: "john.miller@example.com",
"senderName"
: "John Miller",
"replyTo"
: "news@example.com",
"replyToName"
: "SAP News",
"recipient"
: "recipient@example.com",
"recipientName"
: "Recipient",
"listUnsubscribe"
: "<mailto:yyyy>, <http::zzz>"
"subjectContentPlainText" : "Hello Recipient",
"bodyContentHtml"
: "<b>Hello, this email body is HTML<b>",
"bodyContentPlainText" : "Hello, this email body is plain text"
}
Response
Response Parameters
Parameter errorCategory
Required No
errorText
No
messageId
Yes
Integration Guide Integration Scenarios
Data Type String
String String
Description
Permanently appearing er rors lead to a stop of the campaign execution. Retrya ble errors result in multiple retries to resolve the issue before the campaign stops. Throttling reduces the throughput that is generated by the backend. Possible val ues are Retriable, Permanent, or Throttling.
Error text is written to the log and shown to the end user. Format: Plain Text
Unique identifier for out bound message provided by ESP. Could be 'outboundId' if supported by ESP, but not necessarily.
PUBLIC
123
Response Codes The response refers only to the email sent using the connected service provider or SAP Business
Technology Platform. You can't get bounces, such as email address is not valid, with the response. For more information, see Email: Get Bounces [page 125]. Note that the success code must start with 2 followed by two digits, for example, 202. For erronous responses the following generic codes are used: 401 Unauthorized: This code stops the running campaign.
403 Forbidden: This code stops the running campaign. 429 Too Many Requests: With this code the system throttles the email delivery, such as in the case of
the throttling for Amazon: How the System Reacts on Amazon's Throttling [page 145].
Note
Keep in mind that these codes will only work when the errorCategory is empty. The errorCategory has always a higher priority then the error codes.
Response Example
Sample Code
Success Code 202
Content-Type: application/json {
"messageId": "33fds34534r4" }
Error Example Sample Code
Error Codes 4xx, 5xx:
{
"errorCategory" : "Retriable"
"errorText"
: "Sending messages failed and can be retried."
}
Sample Code
Error Codes 4xx, 5xx:
{
"errorCategory" : "Permanent"
"errorText"
: "Messages cannot be sent."
}
Sample Code
Error Codes 4xx, 5xx:
{
"errorCategory" : "Throttling"
"errorText"
: "Throughput for sending messages is too high. Sending
messages can be throttled."
124
PUBLIC
Integration Guide Integration Scenarios
}
4.3.1.1.3.1.2 Email: Get Bounces
With this method you request the bounces from your connected email service provider (ESP).
Request
URI: /bounces HTTP Method: GET
Request Parameters
Parameter sourceSystem
Required No
startTimeUTC
Yes
endTimeUTC
Yes
page
No
Data Type String String String Integer
Request Example /bounces GET sourceSystem=XYZCLNT100 startTimeUTC=20181115221500 endTimeUTC=20181115223000 Page=2
Description
Logical system that is required to get bounces and complaints related to outbound messages.
Timestamp to begin with query collected bounces on ESP side. Format: YYYYMMDDHHMMSS
Timestamp to end with query collected bounces on ESP side. Format: YYYYMMDDHHMMSS
Indicates the result page in case of multiple pages. Possible values are 0 to n
Response
Response Parameters
Parameter page
Required No
lastPage
Yes
Integration Guide Integration Scenarios
Data Type Integer
Boolean
Description
Indicates the result page in case of multiple pages. Possible values are 0 to n
Indicates the last page of the result.
PUBLIC
125
Parameter bounces messageId recipient type
timestamp errorCode
errorText
Required Yes No Yes Yes
No No
No
Data Type JSON Array String String String
String String
String
Description
Contains the bounce details.
Reference to outbound message, see sending in terface.
The email address that bounced or created a com plaint. Value: <email address>
Type of feedback, depending on bounce or com plaint use case. Possible values are: Hard, Soft, abuse, fraud, virus, other, not-spam
Timestamp when bounce occurred. Format: YYYYMMDDHHMMSS
Error code for bounces. Possible entries are: DSN error code (X.Y.Z), SMTP error code (XYZ)
Error text for bounce message.
Response Example
{
"page":"2",
"lastPage":"false",
"bounces": [
{
"messageId" : "12343243243413",
"recipient" : "bounce@example.com",
"errorCode" : "5.1.1.",
"errorText" : "Address does not exist",
"Type"
: "Hard",
"Timestamp" : "20181116093500"
}
]
}
4.3.1.1.3.1.3 Email: Get Complaints
With this method you request the complaints from the connected email service provider (ESP). For the parameter values please refer to Email: Get Bounces [page 125].
Request
URI: /complaints HTTP Method: GET
126
PUBLIC
Integration Guide Integration Scenarios
Request Example /complaints GET sourceSystem=XYZCLNT100 startTimeUTC=20180925211500 endTimeUTC=20180925213000 Page=2
Response
Response Example { "page":"2", "lastPage":"false", "complaints": [ { "messageId" : "12343243243413", "recipient" : "spam@example.com",
] }
"Type" "Timestamp" }
: "abuse", : "20180926093500"
4.3.1.1.3.1.4 Email: Get Unsubscribes
With this method you request the unsubscribes from your connected email service provider (ESP).
Request
URI: /unsubscribes HTTP Method: GET
Request Parameters
Parameter sourceSystem
Required No
startTimeUTC
No
Data Type String
String
Description
Logical system that is required to get unsubscribes related to outbound messages.
Timestamp in UTC to begin with query collected unsubscribes on ESP side. Not required for bounce queue. Format: YYYYMMDDHHMMSS
Integration Guide Integration Scenarios
PUBLIC
127
Parameter endTimeUTC
Required No
Data Type String
page
No
Integer
Request Example /unsubscribes GET sourceSystem=XYZCLNT100 startTimeUTC=20180815064512 endTimeUTC=20180815073422 Page=2
Description
Timestamp in UTC to end with query collected un subscribes on ESP side. Not required for bounce queue. Format: YYYYMMDDHHMMSS
Indicates the result page in case of multiple pages. Possible values are 0 to n
Response
Response Parameters
Parameter page
Required No
lastPage
Yes
unsubscribes
Yes
outboundId
No
messageId
No
recipient
Yes
timestamp
Yes
Data Type Integer Boolean JSON Array String
String String String
Description
Indicates the result page in case of multiple pages. Possible values are 0 to n
Indicates the last page of the result.
Contains the unsubscribe details.
Reference to outbound message, see sendingin terface. Unique identifier of outbound message generated by SAP Marketing Cloud .
This is the ESP-specific message ID provided by the generic provider.
The email address that unsubscribed. Value: <email address>
Timestamp in UTC when unsubscribe occurred. Format: YYYYMMDDHHMMSS
Response Example { "page":"2", "lastPage":"false", "unsubscribes": [ { "messageId" : "12343243243413", "recipient" : "unsubscribe@example.com" "timestamp" : "20180817163255" } ] }
128
PUBLIC
Integration Guide Integration Scenarios
In the SAP system, a multi-level approach is implemented and, for example, the outboundId is evaluated first. But in case the outboundId is not provided and is, for example, initial, the messageId is evaluated. And in case, the messageId is not provided, too, email address is evaluated (recipient).
Note
Note: If one of the regarding values (outboundId, messageId) is not initial, the system takes the entries as valid. A fall back on other levels only happens when the previous level values are initial.
4.3.1.1.3.1.5 Email: Get Verified Senders
With this method you get the verified senders from your connected email service provider (ESP).
Note
This method is mandatory for the integration. Only with this method implemented, you can: maintain sender profiles send test emails send emails out of a campaign
Recommendation
We recommend to use your customer domain as senderDomains instead of *.
Request
URI: /verifiedSenders HTTP Method: GET Request Example
/verifiedSenders GET
Integration Guide Integration Scenarios
PUBLIC
129
Response
Response Example
Response
{
"senders"
: [ "sender1@example.com", "sender2@example.com" ],
"senderDomains" : [ "news.sap.com", "sap.com", "example.com" ]
}
4.3.1.1.3.1.6 Text Message: Send
With this method you send text messages to your connected text messaging service provider.
Request
URI: /send HTTP Method: POST
Request Parameters
Parameter type
Required No
outboundId
No
campaignId
No
sourceSystem
No
sender
Yes
recipient
Yes
Data Type String
String String
String
String String
Description
Indicates for the middleware which integration flow for which type of service pro vider should be processed; entry 'sms'
Unique identifier of outbound message generated by SAP Marketing Cloud
Campaign ID of SAP Marketing Cloud that gener ates this email. Can be empty for send tests in campaign content and sender profile. Helpful for support.
Logical System (SAP Net Neaver). Required to get cor responding bounces or com plaints related to outbound messages.
Sender address; name or phone number
Recipient; phone number
130
PUBLIC
Integration Guide Integration Scenarios
Parameter
Required
bodyContentPlainTex Yes t
Request Example Sample Code Path /send HTTP method POST
Data Type String
Description
Body content as plain text and JSON encoded.
Content-Type: application/json Encoding: UTF-8
Body: {
"type" "outboundId" "campaignId" "sourceSystem" "sender" "recipient" "bodyContentPlainText" }
: "sms", : "33fds34534r4", : "123456789", : "ANACLNT100", : "SAP News", : "+49123456789", : "Hello, this is plain text"
Response
Response Parameters
Parameter messageId
Required Yes
errorCategory
No
errorText
No
Integration Guide Integration Scenarios
Data Type String String
String
Description
Unique identifier for out bound message provided by service provider. Could be outboundId if supported by service provider.
Permanent errors lead to a stop of the campaign execu tion. Errors that can be fixed by a retry result in multiple retries to resolve the issue before the campaign stops. Throttling reduces the throughput that is generated by the backend. Possible val ues are Retriable, Permanent, or Throttling.
Error text is written to the log and shown to the end user in plain text.
PUBLIC
131
Note
The response refers only to the text message sent using the connected service provider or SAP Business Technology Platform. You can't get bounces, such as phone number is not valid, with the response. For more information, see Text Message: Collect Delivery Status [page 132].
Note that the success code must start with 2 followed by two digits, for example, 202.
Response Example
Sample Code
Response: Success Code 202 Content-Type: application/json
{ "messageId": "33fds34534r4"
}
Error Example Sample Code Error Codes 4xx, 5xx:
{
"errorCategory" : "Retriable"
"errorText"
: "Internal Server Error"
}
4.3.1.1.3.1.7 Text Message: Collect Delivery Status
With this method you get back the status of your connected text messages sent.
Request
URI: /status HTTP Method: GET
132
PUBLIC
Integration Guide Integration Scenarios
Request Parameters
Parameter sourceSystem
Required No
Data Type String
startTimeUTC
No
String
endTimeUTC
No
String
page
No
Integer
Request Example /status GET sourceSystem=ANACLNT100 startTimeUTC=20170912144813 endTimeUTC=20170913144813 Page=2
Description
Logical System (SAP NetWeaver). Required to get corresponding bounces or complaints related to outbound messages.
Timestamp to begin with query collected bounces on service provider side. Not needed in case of a bounce queue; format: YYYYMMDDHHMMSS
Timestamp to end with query collected bounces on service provider side. Not needed in case of a bounce queue; format: YYYYMMDDHHMMSS
Indicates the result page in case of multiple pages; possible values: 0..n
Response
Response Parameters
Parameter page
Required No
lastPage
Yes
status
Yes
messageId
No
recipient
Yes
type
Yes
Integration Guide Integration Scenarios
Data Type Integer
Boolean JSON Array String
String
String
Description
Indicates the result page in case of multiple pages. Possible values are 0 to n
Indicates the last page of the result.
Contains the bounce details.
Reference to outbound message, see sending in terface. The phone number that bounced or created a complaint. Value: phone number
Type of feedback, depending on bounce or com plaint use case. Possible values are: Permanent or Temporary. Note that the type is mapped in the SAP system as followed:
Permanent - hard bounce
Temporary - soft bounce
PUBLIC
133
Parameter timestamp
statusCode
Required No
No
errorText
No
Data Type String String
String
Description
Timestamp when bounce occurred. Format: YYYYMMDDHHMMSS
The status code that your connected service pro vider sends back to inform you about the delivery status. Keep in mind that
status codes can't be mapped to statuses in the SAP system and
shall not be longer than 10 charakters due to further processing.
Error text for bounce message.
Response Example
Sample Code
{
"page": 2,
"lastPage": false,
"status": [
{
"messageId" : "12343243243413",
"recipient" : "+49123456789",
"statusCode" : "10",
"statusText" : "Number does not exist",
"type"
: "Permanent",
"timestamp" : "20170913144813"
}
]
}
4.3.1.1.3.1.8 Text Message: Get Unsubscribes
With this method you request the unsubscribes (also known as 'Stop Trigger') from your connected text message provider.
Request
URI: /unsubscribes HTTP Method: GET
134
PUBLIC
Integration Guide Integration Scenarios
Request Parameters
Parameter sourceSystem
Required No
startTimeUTC
Yes
Data Type String
String
endTimeUTC
Yes
page
No
String Integer
Request Example /unsubscribes GET sourceSystem=ABCCLNT100 startTimeUTC=20180815064512 endTimeUTC=20180815073422 Page=2
Description
Logical system that is required to get unsubscribes related to outbound messages.
Timestamp to begin with query collected unsub scribes on service provider side. Format: YYYYMMDDHHMMSS
Timestamp to end with query collected unsub scribes on ESP side. Format: YYYYMMDDHHMMSS
Indicates the result page in case of multiple pages; possible values: 0..n
Response
Response Parameters
Parameter page
Required No
lastPage
Yes
unsubscribes
Yes
outboundId
No
messageId
No
recipient
Yes
sender
No
timestamp
Yes
messageText
No
Integration Guide Integration Scenarios
Data Type Integer Boolean JSON Array String
String String
String String String
Description
Indicates the result page in case of multiple pages. Possible values are 0 to n
Indicates the last page of the result.
Contains the unsubscribe details.
Reference to outbound message, see sendingin terface. Unique identifier of outbound message generated by SAP Marketing Cloud .
Reference to an outbound ID provide by the ge neric ESP.
Phone number of the original text message that re plied with an unsubscribe (stop trigger). Value: phone number
Phone number to which the unsubscribe (stop trig ger) was sent. Value: phone number
Timestamp when unsubscribe occurred. Format: YYYYMMDDHHMMSS
Message text that was sent with the unsubscribe, for example, the campaign ID.
PUBLIC
135
Response Example Sample Code
{
"page": 2,
"lastPage": false,
"unsubscribes": [
{
"outboundId" : "AHGB789345",
"recipient"
: "+49123456789",
"messageText" : "Stop 0815",
"timestamp"
: "20180913144813"
}
]
}
In the SAP system, a multi-level approach is implemented and, for example, evaluates
outboundId first, in case that it is not provided messageId, in case it is not provided mobile number (recipient) only.
For this level the system evaluates the message text if it contains a campaign ID. In this case the campaignID is considered with regards to marketing area separation.
Note: If one of the regarding values (outboundId, messageId) is not initial, the system takes the values as valid ones.
A fall back on other levels only happens, when the previous level values are initial.
4.3.1.1.4 Amazon Setup
The integration with Amazon is very powerful and covers a wide span of functionality for email and text message campaigns. The following graphic gives you an overview how the integration roughly works and how the data flows. In addition there are links, where suitable for the setup or other useful information.
136
PUBLIC
Integration Guide Integration Scenarios
Integration Guide Integration Scenarios
PUBLIC
137
Enabling Automatic Unsubscribe for Emails by Amazon [page 143] Setting Up Amazon [page 138] Bounces, Unsubscribes, and Complaints Bounces, Unsubscribes, and Complaints
Related Information
Service Provider and Available Features [page 111]
4.3.1.1.4.1 Setting Up Amazon
To establish the connection to Amazon's Simple Email Service (SES) for email and bounce handling, you must do several steps at Amazon and at SAP.
Prerequisites
The following prerequisites exist for setting up Amazon as an email service provider:
Use the Campaign Execution Inclusion List app during the system setup and test phase. The settings in the app prevent that target group members (contacts) receive emails when you execute an email campaign for test purposes. For more information, see Campaign Execution Inclusion List [page 149].
You are familiar with the basics of the Amazon Service for Emails, Notifications and Queues: aws.amazon.com/de/documentation/ses/ aws.amazon.com/de/documentation/sns/ aws.amazon.com/de/documentation/sqs/
You have access granted on Amazon for the following API methods: SendRawEmail (SES) ListIdentities (SES) GetIdentityVerificationAttributes (SES) GetSendQuota (SES) ReceiveMessage (SQS) DeleteMessageBatch (SQS) For more information, see Controlling Access to Amazon SES .
Procedure
1. To send marketing emails to your customers, you have to configure Amazon Web Services (AWS). For more information, see Setting up Amazon [page 139].
138
PUBLIC
Integration Guide Integration Scenarios
2. After you did the configuration at Amazon, you go further with the configuration at SAP. Download the certificates and import them to the SAP system. For more information, see Importing Certificates [page 141].
3. Establish the system connection between Amazon and SAP. For more information, see Establishing System Connection [page 141].
Next Steps
Note
The following blog is not part of the official documentation of SAP Marketing Cloud and some of the information may be outdated.
Related Information
http://docs.aws.amazon.com/ses/latest/DeveloperGuide/before-you-begin.html http://docs.aws.amazon.com/ses/latest/DeveloperGuide/configure-sns-notifications.html http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqssubscribe.html How the System Reacts on Amazon's Throttling [page 145]
4.3.1.1.4.1.1 Setting up Amazon
Here you create an Amazon Web Services (AWS) account and verified email addresses. Then you configure your SNS topics and bounce queues, create Identity and Access Management (IAM) users, generate your credentials for the Simple Email Service (SES), and set up group administration for your users to assign policies.
Procedure
1. Create an Amazon Web Services (AWS) account to get an account ID and password. 2. Log in to https://console.aws.amazon.com with your credentials. 3. Ensure, to select the correct region you intend to use. You see the region beside your account ID in the AWS
Console itself and in the URL of your browser, for example, https://euwest-1.console.aws.amazon.com/ses/home?region=eu-west-1#. 4. In the AWS Console under Identiy Management, create the required verified sender email addresses under Email Addresses.
You need the verified sender address, when you define a sender profile later on.
Integration Guide Integration Scenarios
PUBLIC
139
Keep in mind that the MAIL FROM Domain of your verified email adresses must in the same region as the Host Name entered in the system connection later on.
For more information, see Regions and Amazon SES .
5. Now edit the notification configuration for the verified sender email address by choosing Notifications Edit Configuration Click here to create a ne Amazon SNS topic. .
An Edit Notification Configuration popup opens.
Create a new Amazon SNS topic, for example, for bounces and complaints. Give the new topic the same name as the feedback queue, such as AMAZON_BOUNCE. 6. Then under SNS Topic Configuration select the previously created topics for bounces and complaints.
Note that you don't maintain a topic for deliveries. The system is not able to handle the delivery notification. 7. Also in the Edit Notification Configuration popup under Email Feedback Forwarding, disable the email feedback forwarding. 8. Save your configuration.
After the saving you can find your Amazon Resource Names (ARN) under Notifications.
For more information, see also Amazon Resource Names (ARNs) and AWS Service Namespaces . 9. In the SQS console, create a new queue with the same name you gave the feedback queue in technical
configuration.
To do so, choose SQS Create New Queue and enter a topic name from the previous steps. Keep all other values as default and save your entries. 10. Subscribe to new queue to the SNS topic you created earlier. a. Go to your AWS-SES account and choose Security Credentials. b. Under Your Security Credentials, you create an IAM user required to send or used in Sender Profiles. We
recommend to use IAM users to send emails as you can control with them the permissions and authorizations. 11. To start, choose Get Started with IAM Users: a. Choose Create New Users. b. Enter the user names. c. Select Generate an access key for each user. d. Choose Create.
A confirmation message should appear that the users have been created. 12. Now you have set up an account at Amazon for and you receive the following parameters during account
set-up: Amazon Access Key ID (hash string) Secret Access Key (hash string) Feedback Queue Path
The Feedback Queue Path is the last individual portion of the queue URL at Amazon. For example, the path from https://sqs.eu-west-1.amazonaws.com/NNNNNNNNNNNN/ABC is /NNNNNNNNNNNN/ ABC.
Note that you need these parameters again in the apps Communication Systems and Communication Arrangements.
140
PUBLIC
Integration Guide Integration Scenarios
13. In the AWS Dashboard under Groups, create a new group to assign policies to users. For example, create a group named Administrator and assign all the admin policies in the Attach Policies step.
14. To assign users to the created group, choose Group Actions Add Users to Group .
4.3.1.1.4.1.2 Importing Certificates
Note
The following blogs are not part of the official documentation of SAP Marketing Cloud and some of the information may be outdated. The following blogs describe how to download and import the certificates to SAP Marketing Cloud: Heads-up: Amazon Simple Email Services (SES) change Certificates
4.3.1.1.4.1.3 Establishing System Connection
After you have downloaded and imported the certificated, you now have to establish the connection between Amazon and the SAP system.
Context
For already existing customers: If you are changing something in the settings for your system connection after the upgrade from a lower release to release 1902 or higher, you must re-enter data that you have maintained previously in the Provider Credentials app: For scenario ID SAP_COM_0016, you have maintained the credentials (access key and secret key) in the
Communication Systems app. For scenario IDs SAP_COM_0039 and SAP_COM_0289, you have maintained the corresponding paths in the
Communication Arrangements app under Outbound Services.
Using Several Accounts
If you want to use several accounts, you must do the steps above for each account seperately. To get more information about the dependencies in the setup, see Usage of Multiple Service Provider Instances [page 146].
Procedure
1. To be able to establish the system connection, check that the apps Communication System and Communication Arrangements are assigned to your user.
Integration Guide Integration Scenarios
PUBLIC
141
2. In the Communication Systems app you create the connection with the SAP system and define a communication user with user and password. a. Enter a System ID and System Name. b. Enter the host names, you got from Amazon. You require different hosts, depending whether you want to create a communication system for sending emails or for bounce and unsubscribe handling.
Host Name for emails (Amazon SES): email.eu-west-1.amazonaws.com
Host Name for bounce and unsubscribe handling (Amazon SQS): sqs.eu-west-1.amazonaws.com
Note that you have to use different host names when you are using Amazon in another region than, for example, EU-WEST. c. Under User for Outbound Communication create a user with your provider credentials by choosing Add.
You use for emails (Amazon SES) your real credentials, called Access Key (User) and Secret Key (Password).
Whereas for bounce and unsubscribe handling (Amazon SQS), you use a dummy user with a generic password. 3. Establish the communication arrangement in the Communication Arrangement app. a. To create a new arrangement choose New, select the required Scenario and enter an Arrangement Name.
Technical details for the communication arrangement:
Communication Arrangement for Emails Scenario: SAP_COM_0016
Communication Arrangement for Bounce Handling Scenario: SAP_COM_0039
Communication Arrangement for Unsubscribe Scenario: SAP_COM_0289
b. Select the previously created Communication System which fits to the scenario. c. Depending on which communication arragement you have set up, add the following Additional
Properties: For emails (SAP_COM_0016) enter a Provider ID, Sender Profile ID, and assign a relevant Marketing
Area ID. For bounce handling (SAP_COM_0039) and unsubscribe handling (SAP_COM_0289) you must
enter the EXACT SAME (!) Provider ID that is used for the related email instance (SAP_COM_0016). Note that if you want to use multiple Amazon instances, you must use the Provider ID of the related email instance (SAP_COM_0016) that you want to connect to the bounce and unsubscribe instances. d. Under Outbound Services check that the Service Status is activated, and Port 443 is used.
In addition, check the paths: Scenario: SAP_COM_0016
Path: no path Scenario: SAP_COM_0039
142
PUBLIC
Integration Guide Integration Scenarios
Path: The path (also known as Feedback Queue Path) is the last individual portion of the queue URL at Amazon. For example, the path from https://sqs.eu-west-1.amazonaws.com/ NNNNNNNNNNNN/ABC is /NNNNNNNNNNNN/ABC. Scenario: SAP_COM_0289 Path: The path is the last individual portion of the queue URL at Amazon for unsubscribe. For example, the path from https://sqs.eu-west-1.amazonaws.com/NNNNNNNNNNNN/ABC is / NNNNNNNNNNNN/ABC. For more information, see Enabling Automatic Unsubscribe for Emails by Amazon [page 143]. e. Now save your entries.
During the save the system establishes the required system connection and creates a provider and sender profile.
Note that if you change an already existing communication arrangement in release 1902 and higher, you must maintain your user credentials, called Access Key (User) and Secret Key (Password), in the
Communication Systems app. maintain the paths in the Communication Arrangements app.
4. Finally maintain your sender profiles. For more information, see Sender Profiles [page 155].
Related Information
Consuming the Integration APIs [page 395]
4.3.1.1.4.1.4 Useful Blog
Note
The following blog is not part of the official documentation of SAP Marketing Cloud and some of the information may be outdated: .
How to Set Up Amazon SES as Email Service Provider
4.3.1.1.4.2 Enabling Automatic Unsubscribe for Emails by Amazon
When you want to use the unsubscribe offered by Amazon, you need to do settings at Amazon and at SAP.
After you did all the settings, the header of the recipient's email contains the possibility to unsubscribe.
If the contact does not want to get further emails, she or he sends an unsubscribe request to the unsubscribe email address entered in the sender profile. The unsubscribe requests are collected on Amazon side in a queue. A background job then pulls the unsubscribe requests from Amazon and creates corresponding interactions in
Integration Guide Integration Scenarios
PUBLIC
143
the system. The system evaluates the interactions and updates marketing permissions or list subscriptions for the marketing contact.
In detail the following steps will happen: 1. The marketing expert executes an email campaign. 2. The system sends out the marketing emails. 3. A recipient is getting an email in the inbox. 4. The recipient unsubscribes by clicking on the option in the email header. 5. Email client sends an unsubscribe request to unsubscribe email address of Amazon. 6. Amazon collects unsubscribe requests in a queue. 7. SAP pulls the unsubscribe requests and creates interactions. 8. Based on the interactions the system updates marketing permissions and list subscriptions.
Prerequisites
You need the communication scenarios Marketing - Campaign Execution - Amazon E-Mail Integration (SAP_COM_0016) and optionally Marketing - Campaign Execution - Amazon E-Mail Bounce Integration (SAP_COM_0039).
144
PUBLIC
Integration Guide Integration Scenarios
Setup
At Amazon
1. Create and configure an AWS account. For more information, see Before You Begin . 2. Registering a New Domain . 3. Check and verify your domain. For more information, see Verify your Domain , Amazon SES Domain
Verification TXT Records , and Publishing an MX Record for Amazon SES Email Receiving . 4. Now you can create your rule set. For more information, see Set up a Receipt Rule .
Note that when you create a rule, choose action type SNS (instead of S3 mentioned in the documentation) and give the SNS topic a meaningful name such as unsubscribe. 5. Then create a queue with Amazon Simple Queue Service (SQS) by choosing Subscribe Queue to SNS Topic from the dropdown menu. Important here to know is that you must connect this queue with the previously created SNS topic. For more information, see Create a Queue in Amazon Simple Queue Service .
At SAP
1. Open the Communication Systems app and create, if not yet existing, an Amazon SQS system by maintaining the according data.
2. Open the Communication Arrangements app and create a communication arrangement for the communication system that was created in the previous step. Enter a / (slash) in the Path field. Use for the setup the Communication Scenario SAP_COM_0289.
3. Open the Sender Profiles app and add the Email Address for Unsubscribing. For more information, seeOpting-Out and Unsubscribing by Email. Create either a new domain or register an existing one using Amazon Route 53 for the Amazon Email sender profiles you use in the messages for your campaign execution.
4.3.1.1.4.3 How the System Reacts on Amazon's Throttling
When Amazon runs into throttling, Amazon returns an error message. The SAP system reacts on it by reducing the send rate and processing the failed messages. When Amazon SES runs into throttling, it returns an error message with the following text: API error: Code "400", Reason: "Bad Request", Message: "Throttling Maximum sending rate exceeded." This happens if the maximum send rate is exceeded. The campaign execution reacts on it by reducing the number of parallel sent request to Amazon SES. Messages that failed due to the Amazon SES error are automatically reprocessed by the campaign execution. As result of throttling the campaign execution needs more time to process all requests because it sends less in parallel to avoid that the maximum send rate is exceeded again.
Recommendation
If the issue still persists, we recommend to exceed the quota at Amazon.
For more information, see also information given by Amazon: What Happens When You Reach Your Sending Limits?
Integration Guide Integration Scenarios
PUBLIC
145
4.3.1.1.5 Usage of Multiple Service Provider Instances
In case you want to run campaigns for different customers you can use several instances of the same service provider to gain a better overview about your figures and costs.
But when you plan to create several instances of one service provider, you must keep the following in mind: For each service provider account, you create a communication system, a communication arrangement, a
provider ID, and a sender profile ID.
Recommendation
We recommend that you define all names and IDs upfront, BEFORE you start with the creation of the system connection.
Example
In the following example you got 2 accounts from Sinch: Both have the same host, but different users and passwords.
You define upfront that the provider IDs shall be sinch_01 and sinch_02 and the IDs for the generated sender profiles shall be sinch01 and sinch02.
You define upfront that the IDs of the communication systems shall be DI_01 and DI_02 with the corresponding names Digital Interconnect 1 and Digital Interconnect 2.
You define upfront that the name of the communication arrangement shall be Digital Interconnect 0040-1 and Digital Interconnect 0040-2.
Account of Service Provider Given by Provider
Host
User Password Defined by Customer Provider ID Sender Profile ID Communication System Defined by Customer System ID
Example Account 1
Example Account 2
email-eu1.sapdigitalinter email-eu1.sapdigitalinter
connect.com
connect.com
abc_def1234
xyz_def9876
6T5z)f§45d§
98(6/idRt$m
sinch_01 sinch01
sinch_02 sinch02
DI_01
DI_02
146
PUBLIC
Integration Guide Integration Scenarios
System Name
Digital Interconnect 1
Digital Interconnect 2
Assigned by Customer
Host (under Outbound Communication)
email-eu1.sapdigitalinter email-eu1.sapdigitalinter
connect.com
connect.com
User (under Outbound Communication)
abc_def1234
xyz_def9876
Password
6T5z)f§45d§
98(6/idRt$m
Communication Arrangement for Scenario SAP_COM_0040
Defined by Customer
Arrangement Name
Digital Interconnect 0040-1
Digital Interconnect 0040-2
Assigned by Customer
Communication System DI_01
DI_02
Provider ID
sinch_01
sinch_02
Sender Profile ID
sinch01
sinch02
Path
/in365-api/abc_def1234/ /in365-api/xyz_def9876/
notifications
notifications
For every communication arrangement you have to define an unique Provider ID and an unique Sender Profile ID. Unique means:
If you are defining the sending of emails and the collecting of the bounces, for example, using Amazon as service provider, you must use the same Provider ID in all of the related communication scenarios that you want to use: SAP_COM_0016 for sending emails, SAP_COM_0039 for collecting the bounces, and for enabling the unsubscribe using SAP_COM_0289. The same is valid for sending text messages and collecting the text message bounces using Sinch with the scenario IDs SAP_COM_0041 and SAP_COM_0299.
Integration Guide Integration Scenarios
PUBLIC
147
In the Communication Systems app, you create your system instance with the host given by your service provider. For every account of any service provider, you must create a communication system, where you assign the account credentials such as user and password. Depending on the service provider, it can be possible that you use for every account of the same provider the same host.
In the Communication Arrangements app, you create as many communication arrangements for service provider as required. In addition, select also the user you created in the Communication Systems app. For each additional arrangement entry of the same scenario, you must enter also new provider and sender profile IDs. That means that you must, in this case, overwrite the proposed ones.
Note
You cannot use IDs that are reserved for other service providers.
The following provider and sender profile IDs are reserved:
Provider ID sapGeneric genSmsAdap mobPush sapMS1025
Sender Profile ID GNML GENS MPN MSTS
Note that the Provider ID is case-sensitive and that the IDs are also reserving entries that are starting with these IDs as prefix.
For example, Provider ID aliMail reserves also entries starting with aliMail* (but not ALIMail*), whereas Sender Profile ID AM reserves also entries starting with AM*.
The steps for the setup itself are the same as described in the chapters Setting Up Sinch [page 112] and Setting Up Amazon [page 138].
Saving the communication arrangement, the system creates the corresponding providers and sender profiles, and establishes the required system connections.
In the Sender Profiles app then you must complete the generated sender profiles, with, for example, a sender address. There you can also change the assigned marketing area and also copy the profiles. But be aware that the copied profile uses the SAME provider ID as the source profile.
148
PUBLIC
Integration Guide Integration Scenarios
Service Provider Sinch: Sinch E-Mail 365
Scenario ID SAP_COM_0040
Sinch: SAP Intelligent Notification SAP_COM_0041 365, SMS API
Sinch: SAP Intelligent Notification 365, SMS API for Bounces and Un subscribe
SAP_COM_0299
Amazon SES for Email
SAP_COM_0016
Amazon SQS for Bounces
SAP_COM_0039
Amazon SQS for Unsubscribe
SAP_COM_0289
Specifics
In the Communication Systems app, you enter the user cre dentials you got from Sinch: User and Password
In the Communication Systems app, you enter the user cre dentials you got from Sinch: User and Password
In the Communication Systems app, you enter the user cre dentials you got from Sinch Live Link 365: User and Password
In the Communication Arrangements app, you must use the same Provider ID as in the setup for the related communica tion arrangement for scenario SAP_COM_0041.
In the Communication Systems app, you enter the user cre dentials you got from Amazon, called Access Key (User) and Secret Key (Password).
In the Communication Systems app, you create only a dummy user with a dummy password.
In the Communication Arrangements app, you must use the same Provider ID as in the setup for the related communica tion arrangement for scenario SAP_COM_0016.
In the Communication Systems app, you do not need to cre ate a new system. You can re-use the system for SAP_COM_0039.
In the Communication Arrangements app, you must use the same Provider ID as in the setup for the related communica tion arrangement for scenario ID SAP_COM_0016 and SAP_COM_0039. But note that the Path is different from the setup for scenario SAP_COM_0039.
4.3.1.1.6 Campaign Execution Inclusion List
You use the Campaign Execution Inclusion List app to maintain allowed email addresses and telephone numbers.
You maintain the allowed email addresses and telephone numbers that you want to use, when you create marketing campaigns for test purposes. With the entries, you avoid sending test emails and test text messages to your customers.
Note
You use this app only in your test system. As soon, as you have maintained email addresses or telephone numbers in the app, only those
recipients from this list can be contacted.
Integration Guide Integration Scenarios
PUBLIC
149
When you create an inclusion list entry, the system checks whether there's already an existing exclusion list entry with the same email address or email domain or mobile phone number. When an entry exists in the exclusion list, the system rejects this entry in the inclusion list.
This behaviour is also valid for overlapping email domains. For example, if the exclusion list has an email entry @example.org, you can't add the email address joe.public@example.org to the inclusion list.
4.3.1.1.7 Unsubscribe for Emails and Text Messages
In the following, you learn about the possibilities to unsubscribe from emails and text messages.
Automatic Unsubscribe for Emails (List Unsubscribe)
With the automatic unsubscribe, you don't need to maintain the unsubscribe email collect the unsubscribe information provided from email client. handle the permissions based on an email unsubscribe All these steps are automatically done by the system.
To enable the automatic unsubscribe, you have created the required communication arrangements for Sinch (SAP_COM_0040) and/or Amazon (SAP_COM_0289) for unsubscribe. To get also the bounces, we recommend to also set up the communication scenario (SAP_COM_0039).
For the setup, you must enter an Email Address for Unsubscribing in the Sender Profiles app and the system adds the unsubscribe information to the email header. Most email clients then show an unsubscribe button at the very top of the email.
Note
For Sinch, the email address is preset and can be changed.
For Amazon, the email address must be added manually as the address is account-specific.
After the recipient has unsubscribed, the email client sends an email with the information back to the service provider. The SAP system collects the data from the service provider and maintains the marketing permissions (Opt-out) automatically.
In a newsletter campaign, the unsubscribe also contains the communication category. With the communication category and contact data, the unsubscribe from a newsletter can be realized and the system knows that this unsubscribe is one for a newsletter.
For more information, see: Opting-Out and Unsubscribing by Email Enabling Automatic Unsubscribe for Emails by Amazon [page 143]
150
PUBLIC
Integration Guide Integration Scenarios
Automatic Unsubscribe for Text Messages (STOP Trigger)
To enable the automatic unsubscribe for text messages, you have created the required communication arrangements for Sinch (SAP_COM_0041 and SAP_COM_0299). After the recipient has unsubscribed by sending back the word STOP, the SAP system collects the data from the service provider and maintains the marketing permissions (opt-out) automatically. For more information, see Bounces and Unsubscribe for Text Messages [page 115].
Manual Unsubscribe for Emails
For the manual unsubscribe, you don't need any configuration, beside of adding an Email Address for Unsubscribing and/or a Follow-Up Page for Unsubscribing to the used sender profile in the Sender Profiles app. Using the Email Address for Unsubscribing or the Follow-Up Page for Unsubscribing you can collect the required data and update your subscriptions and permissions (opt-out) manually in the Contacts app.
Easy Opting-Out and Easy Unsubscribe for Email
With this option, you add a link to the email body that triggers the unsubscribe. The option is independent from any service provider. For more information, see Opting-Out and Unsubscribing by Email.
Unsubscribe and Marketing Areas
The following explains in more detail how the system behaves, whether marketing areas are activated for campaign execution or not.
Sinch: Unsubscribe from Text Messages Sending Back STOP From text messages sent by Sinch can be unsubscribed by sending back the word STOP, also when marketing areas are acitvated for campaign execution. The system uses the mobile number to determine the contacts. If the text message with the word STOP contains also a valid campaign ID, the marketing area of this campaign is used for the opt-out of the corresponding contact mobile number. For this scenario it is irrelevant whether the marketing areas are activated for campaign execution or not. Only for the case no campaign ID has been sent back with the STOP trigger: If marketing area is not activated in the configuration, the system looks for all marketing areas that are assigned to sender profiles for sending text messages and creates an opt-out for one marketing area of the contact(s) related to the mobile number. If marketing area is activated, the system looks for all marketing areas that are assigned to sender profiles for sending text messages and creates opt-outs for each found marketing area of the contact(s) related to the mobile number.
Integration Guide Integration Scenarios
PUBLIC
151
Email Unsubscribe by Amazon Amazon provides an identification with which the outgoing email can be identified, and campaign, contact, and marketing area are determined. The system creates one opt-out (independent whether the separation is activated or not) with the data determined from the outgoing email.
Email Unsubscribe by Sinch Sinch provides an identification with which the outgoing email can be identified, and campaign, contact, and marketing area are determined. The system creates one opt-out (independent whether the separation is activated or not) with the data determined from the outgoing email.
For more information, see Marketing Area for Campaigns.
4.3.1.1.8 Complaints for Emails
Complaints for email means that an email recipient classifies emails from dedicated senders as spam. For classifying emails as spam, the email recipient either drops the email to the spam folder of the email provider or declares the email as spam. This technology is also known as email feedback loops.
Process
1. Email recipient classifies a received campaign email as spam. 2. The classification is sent to the email service provider (ESP). 3. The ESP sends complaint information to the SAP system, and the complaint information is stored in the
system and visible for the marketer. 4. Depending on the campaign scenario, a complaint will have the following results:
If the email has been sent by a subscription-based campaign, the SAP system does an unsubscribe for the email address of the recipient/contact and for the corresponding communication category. The global opt-in for marketing permission is not changed.
152
PUBLIC
Integration Guide Integration Scenarios
If the email has been sent by a non-subscription-based campaign, the SAP system does a permission opt-out for the email address of the recipient/contact.
Note
The described complaint handling is only possible if the email provider of the recipient sends a notification back to SAP, which means the provider supports email feedback loops. Not all email providers support this technology.
The email service provider you used to send the emails out of the SAP system (Sinch, Amazon SES, or the generic email interface) stores the returned complaint information on a suppression list. If you use another campaign to send again an email to the recipient that sent a complaint, the email is not delivered to this recipient even if the marketing subscription or permission is still Opted-In in the SAP system. The email is not delivered by the email service provider because the email address is part of the suppression list of the email service provider.
Note that your used ESP in your generic email adapter can have such a suppression list and collect the emails with complaints. But that's not certain and there can be ESPs without that complaint process.
Performance Tab
To see the number of email complaints, open the corresponding campaign in the Campaigns app. On the Performance tab, you see the actuals in the Email Complaints tile.
Related Information
Enabling Complaints [page 153] Removing a Contact from Suppression List [page 154]
4.3.1.1.8.1 Enabling Complaints
The steps guide you to enable complaint handling in your SAP system.
Prerequisites
This function is available if you are using the email services from Sinch or Amazon SES. In case you are using the generic email service provider interface, the availability of the functionality depends on the capabilities of the email service provider behind the interface.
Integration Guide Integration Scenarios
PUBLIC
153
Procedure
Create an incident for the SAP component CEC-MKT-CPG-EXE and request the activation for one of the following options: Update of marketing permission during processing of complaints for email Update of marketing subscription during processing of complaints for email Update of marketing permission and subscription during processing of complaints for email
Results
After the enabling the system updates the marketing permissions or subscriptions during the processing of complaints for email.
4.3.1.1.8.2 Removing a Contact from Suppression List
In case, your customer wants to be contacted again, you must remove the email address of the contact again from the suppression list.
Procedure
To remove a contact again from the service provider's suppression list, you do the following steps. 1. For Sinch, send an email to essupport.digitalinterconnect@sinch.com and ask Sinch to remove the contact
again from the suppression list. 2. For Amazon, log on at your AWS Management Console and remove the customer manually. For more
information, see Removing an Email Address from the Amazon SES Suppression List .
4.3.1.1.9 Troubleshooting for Campaigns
In case you have issues with the execution of your campaigns, we recommend to read also the troubleshooting in the Administration Guide.
Related Information
Troubleshooting Campaigns
154
PUBLIC
Integration Guide Integration Scenarios
4.3.1.1.10 Sender Profiles
A sender profile allows you to carry out campaigns for different channels in different markets. You can maintain sender profiles for channels, such as email, text message, and mobile push notifications.
Prerequisites
You have set up the service provider for emails and text messages and you have maintained the communication arrangements before creating sender profiles. For more information, see Setting Up Service Provider for Emails and Text Messages [page 110].
You have registered the Sender Address and the Reply-To Address at Sinch and/or Amazon.
Note
Note that the registered email address is case-sensitive for Amazon and Sinch.
Recommendation: Test Sender Profiles
To test the maintained sender profiles, we recommend to use Send Test Email or Send Test Text Message to ensure that the settings are working. Otherwise the issues can appear during campaign execution.
Related Information
Mobile Campaigns Opting-Out and Unsubscribing by Email
4.3.2 Setting Up External Campaign Execution
SAP Marketing Cloud allows you to execute campaigns in an external system, and to request the success data for further processing in SAP Marketing Cloud.
Implement Interfaces
Optionally implement a set of interfaces, either directly in the external system, or using a suitable middleware, such as SAP HANA Cloud Integration, to map the interfaces in SAP Marketing Cloud to the interfaces of the external system. For the implementation details, see Implementing Interfaces for External Campaign Execution [page 157].
Integration Guide Integration Scenarios
PUBLIC
155
Set up a Communication Arrangement
Finally, set up a communication arrangement for the external campaign execution, and the success data requests. For the details, see Communication Arrangement for External Campaign Execution [page 192].
Process
Once you have set up your system for external campaign execution, executing the campaigns occurs as follows:
1. Plan Campaign In SAP Marketing Cloud, plan your campaigns from program down to detailed spend (optional).
2. Release Campaign In SAP Marketing Cloud, create and release your campaign. A corresponding campaign is created automatically in the external system. You can optionally assign a target group to the campaign and schedule the transfer of the target group to the external system. Once the campaign is activated, your target group will be updated periodically according to the schedule you set. Alternatively, you can link an existing campaign manually from the external system.
3. Execute Campaign In the external system, execute the campaign. If you choose to use a marketing agency, they can execute the campaign in the external system without needing users in SAP Marketing Cloud. You need technical users in the external system to set up the connectivity. Targeting can be done in the external system, or you can transfer a target group as described in the Release Campaign step. Once the target group is in the external system, the marketing agency, if you choose to use one, can use it for targeting.
4. Track Success In SAP Marketing Cloud, you can track the success of your campaign. Success data is automatically retrieved from the external system. You also can upload success data manually as a CSV file.
5. Delete Contacts Once per day a batch report is executed to check if contacts have been deleted, the permissions for the contacts were changed, or the contacts became expired on external system. If one those conditions is met, then the action for the external campaign execution will be executed. This process will be executed until the campaign is stopped, except if the action is placed directly after the first node in the campaign workflow. In this case, the process will be executed until the end date of the campaign is reached.
Example
Baidu Paid Search Campaign You can use the method described in this chapter to implement Baidu Paid Search Campaigns. For a more detailed explanation on how to accomplish this with Baidu Paid Search Campaigns specifically, see the blog Handling Baidu Paid Search Campaigns using External Campaigns in SAP Marketing Cloud .
156
PUBLIC
Integration Guide Integration Scenarios
4.3.2.1 Implementing Interfaces for External Campaign Execution
You implement a set of interfaces to enable the creation of campaigns in the external system, and to obtain the success data for the executed campaigns.
Overview
Executing campaigns in an external system is set up as follows:
The user creates a campaign for external execution in SAP Marketing Cloud. As a result, your system calls the external system for a list of parameters (including possible values) required for the creation of the campaign in the external system.
The application displays the received parameters allowing the user to specify the parameter values. The user releases the campaign. As a result, the corresponding campaign is created in the external system
and any assigned target group is transferred to the external system. Once the campaign is created in the external system, your system requests success data for the campaign.
The request is repeated every 4 hours, until the external system indicates that no more success data is expected.
The services available with SAP Marketing Cloud, are based on OData Version 2.0. The OData messages are sent in the JSON format. In the communication, the marketing edition system acts as a client. The server side implementation of the services is done by the external system, or a middleware, such as SAP Cloud Integration.
For the server side implementation, the required methods and entity sets are specified in the following sections, and it is explained how to use OData features, such as filtering, sorting, or paging. For the responses, the metadata ("__metadata") is optional.
The following types are included in the list of required entity types:
Entity Type
Description
Campaign
The campaign, as required to integrate with an external system executing the campaign
CampaignParameter
A generic parameter of a campaign that is specific to an external system, and not known to your system in detail
CampaignParameterCode A code list value of a campaign parameter for parameters that have the type CODE_LIST ListValue
CampaignParameterValue A value of a campaign parameter, for example, the selected code list value for a parameter of the type CODE_LIST
MarketingSuccess
All marketing success KPIs for a given set of characteristics including campaign, date, gender, and age
ExtTargetGroup
The target group, as needed to integrate with an external system executing a campaign
Integration Guide Integration Scenarios
PUBLIC
157
Entity Type
Description
ExtTargetGroupParame terValue
A value of a target group parameter, for example,.the selected code list value for a parameter of the type CODE_LIST
ExtTargetGroupSupporte An ID origin requested by the external system executing a campaign dIdOrigin
ExtTargetGroupMember Facet
A member of the target group
ExtTGContactTransfer HeaderSet
The personalized attributes of a target group member
The identification of an externally executed campaign by SAP Marketing Cloud can require additional parameters, for example, when the externally assigned campaign ID is not unique. In this case, the external system can indicate that certain parameters, specifically ADVERTISER and EXT_CAMPAIGN_MANAGING_PARTY, are included in the campaign key. Then, your system can use the additional parameters when filtering for a set of campaigns.
Example: Advertiser is an additional key, the combination of Advertiser and Campaign ID makes a unique key of an external campaign. During the GetEntitySet request of an external campaign, the client sends the additional key in the request filters like below:
((Filter/KeyPart2Id eq 'ADVERTISER') and (Filter/KeyPart2Value eq 'SAP_GLOBAL_MARKETING'))
Additional Filter Parameters
ServerCampaignIDContextCT (Complex Type)
Used for filtering in GetEntitysetMethods
KeyPart2Id (Edm.String, length-50)
KeyPart2Value (Edm.String, length-50)
ID of the first parameter marked to be part of the campaign key Value of the first additional parameter
KeyPart3Id (Edm.String, length-50)
ID of the second parameter marked to be part of the campaign key
KeyPart3Value (Edm.String, length-50)
Value of the second additional parameter
For more information about OData Version 2.0, see http://www.odata.org/documentation/odata-version-2-0/
158
PUBLIC
Integration Guide Integration Scenarios
4.3.2.1.1 Requesting Parameters for Campaign Creation
The request for campaign parameters is triggered when the user creates an externally executed campaign.
For the parameter retrieval, SAP Marketing Cloud calls the GetEntitySet method of the CampaignParameterSet entity set with an expand to the CampaignParameterCodeListValueSet without any filter. As a result, the following list of the parameters is expected:
Campaign Parameters CampaignParameter (Entity Type)
Usage in GetEntitySet Method
Properties and Data Type
Id (Edm.String, length-50)
Stable (language independent) ID of the parameter For Type ADVERTISER the ID mst be set to ADVERTISER For Type EXT_CAMPAIGN_MANAGING_PARTY the ID must be set to EXT_CAM PAIGN_MANAGING_PARTY ADVERTISER and EXT_CAMPAIGN_MANAGING PARTY are key parameters Mandatory in response
Name (Edm.String, length-255)
Potentially language dependent parameter name displayed in SAP Marketing Cloud
Optional in response (ID is displayed when name is missing)
Type (Edm.String, length-30)
Supported types: CODE_LIST, TEXT, AMOUNT, NUMBER, ADVERTISER, EXT_CAMPAIGN_MANAGING_PARTY
Mandatory in response
Navigation Properties
CampaignParamCodeListValues
List of possible values for parameters of type CODE_LIST
For parameters of the types CODE_LIST, ADVERTISER and EXT_CAMPAIGN_MANAGING_PARTY , the following additional list of possible values is required.
Note
For amount parameters, a list of supported currencies can be provided. If no list of currencies is given, the user can select from all currencies available in SAP Marketing Cloud.
Additional Code List Parameters CampaignParamterCodeListValue (Entity Type) Usage in GetEntitySet Method Properties and Data Type
Integration Guide Integration Scenarios
PUBLIC
159
CampaignParamterCodeListValue (Entity Type) Usage in GetEntitySet Method
Code (Edm.String, length-50)
Stable (language independent) code Mandatory in response
Description (Edm.String, length-255)
Potentially language dependent description of the code displayed in SAP Marketing Cloud
Indicates (true or false) whether the type parameter is included
Optional in response Code is displayed when description is missing.
CampaignParameterId (Edm.String, length-50)
Reference to the campaign parameter Mandatory in response
An example as sent by SAP Marketing Cloud: Request URL: https://<HostName>/.../<YourService>/CampaignParameterSet?
$expand=CampaignParamCodeListValues&$format=json . HTTP Method: GET Sample Response, as sent by the external system:
Sample Code
{ "d": { "results": [{ "Id": "ADVERTISER", "Name": "Advertiser", "Type": "ADVERTISER", "CampaignParamCodeListValues": { "results": [{ "CampaignParameterId": "ADVERTISER", "Code": "SAP_GLOBAL_MARKETING ", "Description": "SAP Global Marketing" }, { "CampaignParameterId": "ADVERTISER", "Code": "SAP_GERMANY", "Description": "SAP Germany" }] } }, { "Id": "METRIC", "Name": "Metric", "Type": "CODE_LIST", "CampaignParamCodeListValues": { "results": [{ "CampaignParameterId": "METRIC", "Code": "CLICKS", "Description": "Number of Clicks" }, { "CampaignParameterId": "METRIC", "Code": "IMPRESSIONS", "Description": "Number of Impressions" }] },
160
PUBLIC
Integration Guide Integration Scenarios
{ "Id": "CAMPAIGN_DESC", "Name": "Campaign description", "Type": "TEXT",
}, {
"Id": "DAILY_BUDGET", "Name": "Daily Budget", "Type": "AMOUNT", "CampaignParamCodeListValues": {
"results": [{ "CampaignParameterId": "DAILY_BUDGET", "Code": "EUR", "Description": "Euro"
}, {
"CampaignParameterId": "DAILY_BUDGET", "Code": "USD", "Description": "American Dollars" }] } }, { "Id": "DAILY_IMPRESSIONS", "Name": "Target Daily Impressions", "Type": "NUMBER", }] } }
4.3.2.1.2 Handling Campaigns in the External System
The user releases the externally executed campaign. As a result, SAP Marketing Cloud calls the Create method of the CampaignSet entity set including a deep create of the CampaignParameterValueSet.
For the campaign ID value help, available in the Campaigns app, the GET method is used to retrieve the relevant information. CampaignName must be enabled for filtering.
Create Campaign Method Campaign (Entity Type)
Usage in Create Method
Properties and Data Type
ClientCampaignId (Edm.String, length-10)
ID of the campaign as provided by SAP Marketing Cloud Ignored in response
CampaignName (Edm.String, length-40
Name of the campaign as provided by SAP Marketing Cloud Needs to be enabled for filtering Ignored in response
StartDate (Edm.DateTime)
Start date of the campaign as provided by SAP Marketing Cloud Ignored in response
Integration Guide Integration Scenarios
PUBLIC
161
Campaign (Entity Type)
Usage in Create Method
EndDate (Edm.DateTime) ServerCampaignId (Edm.String, length-32) ServerCampaignUrl (Edm.String) MainKPI (Edm.String, length-50) SuccessDataEndDate (Edm.DateTime)
SuccessDataTimeZone (Edm.String, length-6) Navigation Properties CampaignParameterValues
End date of the campaign as provided by SAP Marketing Cloud Ignored in response EndDate >= StartData; no further constraints
ID of the externally created campaign as provided by the external sys tem Mandatory in response
Link to the external campaign, optionally provided by the external sys tem Enables navigation from SAP Marketing Cloud to the campaign Optional in response
Main KPI displayed in SAP Marketing Cloud, such as IMPRESSIONS, or CLICKS Optional in response Can be provided with success data
Last date by which SAP Marketing Cloud requests administrative, and success data for the campaign Can be changed until the date is reached, and can be provided with success data retrieval Optional in response If not provided in response, the campaign end date is used
Not used, ignored in response Not provided by SAP Marketing Cloud
List of parameters with corresponding values
Campaign Creation OData Request An example of a campaign creation request , as sent by SAP Marketing Cloud: Request URL: https://<HostName>/.../<YourService>/CampaignSet HTTP Method: POST Sample Request Payload:
{ "ClientCampaignId" : "12345", "CampaignName" : "My Test Campaign", "StartDate" : "\/Date(1452470400000)\/", "EndDate" : "\/Date(1454112000000)\/", "CampaignParameterValues" :
162
PUBLIC
Integration Guide Integration Scenarios
[ { "ClientCampaignId" : "12345", "Id" : "ADVERTISER", "Value" : "SAP_GLOBAL_MARKETING" }, { "ClientCampaignId" : "12345", "Id" : "METRIC", "Value" : "IMPRESSIONS" }, { "ClientCampaignId" : "12345", "Id" : "DAILY_BUDGET", "AmountValue" : "100.00" "CurrencyValue" : "EUR" }, { "ClientCampaignId" : "12345", "Id" : "DAILY_IMPRESSIONS", "NumberValue" : 100000 }
] }
Sample Response Payload: { "d" : { "ServerCampaignId" : "54321", "ServerCampaignUrl" : "www.example.com/54321", "MainKPI" : "CLICKS", "SuccessDataEndDate" : "\/Date(1455494400000)\/" } }
For each parameter required by the external system, a value is sent with the creation of the external campaign:
Create Campaign Method
CampaignParameterValue (Entity Type)
Usage in Create Method
Properties and Data Type
ClientCampaignId (Edm.String, length-10)
Reference to the campaign as provided by SAP Marketing Cloud Ignored in response
Id (Edm.String, length-50)
Stable ID of the parameter as provided by SAP Marketing Cloud Ignored in response
Value (Edm.String, length-256)
Value the user specifies in SAP Marketing Cloud; provided by SAP Marketing Cloud (all parameters assumed to be mandatory)
Ignored in response
For code lists the code is provided, but not the description.
Integration Guide Integration Scenarios
PUBLIC
163
CampaignParameterValue (Entity Type) NumberValue (Edm.Int32, length 10)
AmountValue (Edm.Decimal, Precision- 31, scale -2)
CurrencyValue (Edm.String, length 5)
Usage in Create Method
Value entered by the user in SAP Marketing Cloud for the parameter of the type CODE_LIST or TEXT For code lists, the code is provided but not the description. Provided by SAP Marketing Cloud Ignored in response
Value entered by the user in SAP Marketing Cloud for the parameter of the type AMOUNT Provided by SAP Marketing Cloud Ignored in response
Currency selected by the user in SAP Marketing Cloud SAP Marketing Cloud Ignored in response
Note
Some servers expect a CSRF token for modifying requests, such as POST. Send a non-modifying request, such as GET from the client to retrieve the token. If the server does not support CSRF token mechanism, the client sends POST requests without a token header.
Campaign ID Value Help OData Request An example of a campaign ID value help request follows, as sent by SAP Marketing Cloud. This example corresponds with the outbound service in the communication arrangement that retrieves information for the value help for campaign assignment (CampaignValueHelpSet):
Request URL: https://<HostName>/../<YourService>/CampaignSet? $filter=(CampaignNameeq'Summer Campaign'and ((Filter/KeyPart2Id eq 'ADVERTISER')and(Filter/KeyPart2Valueeq'GLOBAL_MARKETING')&$inlinecount=allpages &$top=100&$skip=0$format=json
HTTP Method: GET
Sample Response Payload:
Sample Code
{ "d": { "results": [{ "ServerCampaignId": "54321", "CampaignName": "Summer Campaign 2018", "StartDate": "\/Date(1455494400000)\/", "EndDate": "\/Date(1455494700000)\/", "ExternalCampaignStatus": "RELEASED" }, { "ServerCampaignId": "54322", "CampaignName": "Jumpstart Summer Campaign", "StartDate": "\/Date(1455495400000)\/",
164
PUBLIC
Integration Guide Integration Scenarios
"EndDate": "\/Date(1455495700000)\/", "ExternalCampaignStatus": "FINISHED" }] } }
4.3.2.1.3 Creating an External Target Group
To create a target group in the external system, SAP Marketing Cloud calls the create method of the ExtTargetGroup entity.
You can create a target group in the external system by transferring member IDs.
Target Group Entity Types
ExtTargetGroup (Entity Type)
Usage in Create Method
Properties
TargetGroupId (Edm.String, length-10)
ID of the target group in SAP Marketing Cloud Always provided by SAP Marketing Cloud Ignored in response
ExtTargetGroupId (Edm.String, length-32)
ID of the created external target group Never provided by SAP Marketing Cloud Mandatory in response
ExtTargetGroupUrl (Edm.String)
Link to the external target group
Never provided by SAP Marketing Cloud
Optional in the response if not provided there is no naviga tion from the UI in SAP Marketing Cloud to the external tar get group
ExtTargetGroupName (Edm.String, length-255)
Name of the external target group as entered on the UI in SAP Marketing Cloud
Always provided by SAP Marketing Cloud
Ignored in response
TransferMaxBatchSize (Edm.Int32, length-10)
The maximum number of target group member facets bun dled in one batch
Never provided by SAP Marketing Cloud
Optional in response with this parameter the external sys tem can limit the batch size to a suitable value down to 1 in case that no batches are supported at all
Integration Guide Integration Scenarios
PUBLIC
165
ExtTargetGroup (Entity Type) TransferMethod (Edm.String, length-10)
MktPermissionCommMedium (Edm.String, length-20)
Navigation Properties ExtTargetGroupParameterValues Target Group Parameter Entity Types ExtTargetGroupParameterValue (Entity Type) Properties TargetGroupId (Edm.String, length-10) Id (Edm.String, length-50)
Usage in Create Method
The way target group member facets are transferred: Must be FULL or DELTA In case of FULL, each update of the target group (re) creates all member facets In case of DELTA, facets of joiners to the target group are created, facets of leavers are deleted Never provided by SAP Marketing Cloud Optional in response DELTA is assumed as default The communication medium to check marketing permis sions for Only contacts with valid marketing permissions for the com munication medium are transferred from SAP Marketing Cloud Never provided by SAP Marketing Cloud Optional in response if no communication medium is pro vided no marketing permissions are checked.
List of campaign parameters with corresponding values Always provided by SAP Marketing Cloud if requested Ignored in response
Usage in Create Method
ID of the SAP Marketing Cloud target group Always provided by SAP Marketing Cloud Ignored in response Stable ID of the parameter Always provided by SAP Marketing Cloud If the type is ADVERTISER, the ID must be set to ADVER TISER Ignored in response
166
PUBLIC
Integration Guide Integration Scenarios
ExtTargetGroupParameterValue (Entity Type) Value (Edm.String, length-255)
ExtTargetGroupDescription (Edm.String)
Usage in Create Method
Value entered by the user in SAP Marketing Cloud for the pa rameter; for code lists the code list ID is provided (and not the name) Always provided by SAP Marketing Cloud as all parameters are assumed to be mandatory Ignored in response
Description of the external target group as entered in SAP Marketing Cloud Optional field provided by SAP Marketing Cloud Ignored in response
For the creation of an external target group, arbitrary parameters are not supported. The only supported parameter is the Advertiser.
If in the step Requesting Parameters for Campaign Creation a parameter of the type ADVERTISER is requested, this advertiser becomes a mandatory field on the campaign UI. The entered value is then provided with the OData request creating the external target group.
Any other parameter from the step Requesting Parameters for Campaign Creation will be ignored for the external target group creation and is only available for external campaign creation.
OData Request
An example of an external target group creation request, as sent by SAP Marketing Cloud: Request URL: https://<HostName>/.../<YourService>/ExtTargetGroupSet HTTP Method: POST Sample Request Payload:
Sample Code
{ "TargetGroupId": "123", "ExtTargetGroupName": "Customers Germany", "ExtTargetGroupParameterValues": [{ "TargetGroupId": "123", "Id": "ADVERTISER", "Value": "GLOBAL_MARKETING" }]
}
Integration Guide Integration Scenarios
PUBLIC
167
Sample Response Payload: Sample Code { "d": { "ExtTargetGroupId": "Ext123", "ExtTargetGroupUrl": "https://www.example.com/TG/Ext123", "TransferMaxBatchSize": 500, "TransferMethod": "DELTA", "MktPermissionCommMedium": "DISPLAY_ADS" } }
4.3.2.1.3.1 Requesting ID Origins
After creating the external target group the needed ID origins are requested by SAP Marketing Cloud with a GetEntitySet call for the ExtTargetGroupSupportedIdOrigin.
Target Group ID Origin Entity Types ExtTargetGroupSupportedIdOrigin (Entity Type)
Usage in GetEntitySet Method
Properties
IdOrigin (Edm.String, length-10)
ID origin to transfer IDs for (e.g. request transfer of email ad dresses and phone numbers)
Never provided by SAP Marketing Cloud
Mandatory in response
HashingMethod (Edm.String, length-10)
Hashing algorithm to hash the IDs to be transferred.
Supported methods: SHA256
Never provided by SAP Marketing Cloud
Optional in response - if no hashing method is provided the IDs of the target group members are transferred without hashing
OData Request
An example of a target group ID origins request as sent by SAP Marketing Cloud: Request URL: https://<HostName>/.../<YourService>/
ExtTargetGroupSupportedIdOriginSet?$format=json HTTP Method: GET
168
PUBLIC
Integration Guide Integration Scenarios
Sample Response Payload: Sample Code { "d": { "results": [{ "IdOrigin": "EMAIL", "HashingMethod": "SHA256" }, { "IdOrigin": "PHONE", "HashingMethod" : "" } ] } }
4.3.2.1.3.2 Transferring Contact IDs
The Target Group Members are transferred either as a single member or in batch. This depends on the parameter `TransferMaxBatchSize`. With this parameter the external system can limit the batch size to a suitable value down to 0 or 1 in case that no batches are supported at all. The default maximum batch size is 10,000 members. If the external system sends a larger batch number, it will be reduced to 10,000.
Target Group Contact ID Entity Types ExtTargetGroupMemberFacet (Entity Type)
Usage in Create method / Delete Method
Properties
ExtTargetGroupId (Edm.String, length-50)
ID of the external target group to add the member to Always provided by SAP Marketing Cloud Ignored in response
ExtTGKeyPart2Id (Edm.String, length-50)
The ADVERTISER parameter Or for compatibility: ID of the first parameter marked to be part of the external target group key Provided by SAP Marketing Cloud if available Ignored in response
ExtTGKeyPart2Value (Edm.String, length-50)
Value of this first parameter Provided by SAP Marketing Cloudif available Ignored in response
Integration Guide Integration Scenarios
PUBLIC
169
ExtTargetGroupMemberFacet (Entity Type) ExtTGKeyPart3Id (Edm.String, length-50)
ExtTGKeyPart3Value (Edm.String, length-50) IdOrigin (Edm.String, length-20) Id (Edm.String, length-100)
Usage in Create method / Delete Method
The EXT_CAMPAIGN_MANAGING_PARTY parameter Or for compatibility: ID of the second parameter marked to be part of the external target group key Provided by SAP Marketing Cloud if available Ignored in response
Value of this second parameter Provided by SAP Marketing Cloud if available Ignored in response
Origin of the target group member ID (EMAIL, PHONE, ...) Always provided by SAP Marketing Cloud Ignored in response
ID of the target group member to be created (the actual email address, the phone number, ...), hashed if hashing was requested Always provided by SAP Marketing Cloud Ignored in response
There are 4 different types of call that are sent from SAP Marketing Cloud for external member transfer.
Single Creation Batch Creation Single Deletion Batch Deletion
Example of Single Creation of External Target Group Member
OData Request An example of a single creation request as sent by SAP Marketing Cloud: Request URL: https://<HostName>/.../<YourService>/ExtTargetGroupMemberFacetSet HTTP Method: POST
Request Payload Sample Request Payload
{ "ExtTargetGroupId": "Ext123", "ExtTGKeyPart2Id": "ADVERTISER", "ExtTGKeyPart2Value": "SAP_GLOBAL_MARKETING", "ExtTGKeyPart3Id": "",
170
PUBLIC
Integration Guide Integration Scenarios
"ExtTGKeyPart3Value": "", "IdOrigin": "EMAIL", "Id": "75304ebddec51e37966325d7950229110177ec502248d106cc29ccd8612bb75f" }
Response Payload It is mandatory that the http header contains the value ( ~status_code: 201 ~status_reason : Created ) after successful creation of members in external system. Sample Response Payload
{ "d": { "results": [{ "ExtTargetGroupId": "Ext123", "ExtTGKeyPart2Id": "ADVERTISER", "ExtTGKeyPart2Value": "SAP_GLOBAL_MARKETING", "ExtTGKeyPart3Id": "", "ExtTGKeyPart3Value": "", "IdOrigin": "EMAIL", "Id":
"75304ebddec51e37966325d7950229110177ec502248d106cc29ccd8612bb75f" }]
} }
Example of Batch Creation of External Target Group Member
OData Request An example of a batch creation request as sent by SAP Marketing Cloud: Request URL: https://<HostName>/.../<YourService>/$batch. HTTP Method: POST HEADERS: Content-Type: multipart/mixed;boundary=batch_01869434-0008
Note
Please be aware of the blank lines in the sample batch payloads, they must be maintained and kept empty.
Request Payload Sample Batch Request Payload
--batch_01869434-0008 Content-Type: multipart/mixed; boundary=changeset_01869434-0005-0002 --changeset_01869434-0005-0002 Content-Type: application/http Content-Transfer-Encoding: binary
POST ExtTargetGroupMemberFacetSet HTTP/1.1 Accept-Language: en Accept: application/json MaxDataServiceVersion: 2.0 DataServiceVersion: 2.0
Integration Guide Integration Scenarios
PUBLIC
171
Content-Type: application/json
{"ExtTargetGroupId":"Ext123","ExtTGKeyPart2Id":"ADVERTISER","ExtTGKeyPart2Value": "SAP_GLOBAL_MARKETING","ExtTGKeyPart3Id":"","ExtTGKeyPart3Value":"","IdOrigin":"E MAIL","Id":"75304ebddec51e37966325d7950229110177ec502248d106cc29ccd8612bb75f"} --changeset_01869434-0005-0002 --changeset_01869434-0005-0002 Content-Type: application/http Content-Transfer-Encoding: binary
POST ExtTargetGroupMemberFacetSet HTTP/1.1 Accept-Language: en Accept: application/json MaxDataServiceVersion: 2.0 DataServiceVersion: 2.0 Content-Type: application/json
{"ExtTargetGroupId":"Ext123","ExtTGKeyPart2Id":"ADVERTISER","ExtTGKeyPart2Value": "SAP_GLOBAL_MARKETING","ExtTGKeyPart3Id":"","ExtTGKeyPart3Value":"","IdOrigin":"E MAIL","Id":"76304ebddec51e37966325d7950229110177ec502248d106cc29ccd8612bb75e"} --changeset_01869434-0005-0002---batch_01869434-0008--
Response Payload
The batch request response headers should contain ~status_reason: Accepted, ~status_code: 202 for a valid request.
It's mandatory to maintain the order of response on batch response payload to match with the requests in request payload. For every request there is a response expected in the response payload.
The value `201 Created' in response is mandatory which denotes the status code and status reason of a successful response.
In case of error suitable error message and status code, should be available in response. Please check odata documentation for batch handling. http://www.odata.org/documentation/odata-version-2-0/ batch-processing/
Sample Batch Response Payload
--8ECFC9976DBAAC45349E7A1DAC19BE200
Content-Type: multipart/mixed; boundary=8ECFC9976DBAAC45349E7A1DAC19BE201
Content-Length:
2995
--8ECFC9976DBAAC45349E7A1DAC19BE201 Content-Type: application/http Content-Length: 1348 content-transfer-encoding: binary
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 927
--8ECFC9976DBAAC45349E7A1DAC19BE201 Content-Type: application/http Content-Length: 1348 content-transfer-encoding: binary
172
PUBLIC
Integration Guide Integration Scenarios
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 927 --8ECFC9976DBAAC45349E7A1DAC19BE201---8ECFC9976DBAAC45349E7A1DAC19BE200--
Example of Single Deletion of External Target Group Member
OData Request An example of a single deletion request as sent by SAP Marketing Cloud: Request URL: https://<HostName>/.../<YourService>/
ExtTargetGroupMemberFacetSet(ExtTargetGroupId='Ext123',ExtTGKeyPart2Id='ADVERTIS ER',ExtTGKeyPart2Value='SAP_GLOBAL_MARKETING',ExtTGKeyPart3Id='',ExtTGKeyPart3Va lue='',IdOrigin='EMAIL',Id='75304ebddec51e37966325d7950229110177ec502248d106cc29 ccd8612bb75f'). HTTP Method: DELETE There is no request payload, and no response payload is returned from the external system. The HTTP response header field (~status_code :204, ~status_reason: No Content) represents successful deletion of member at the external system and it is mandatory.
Response Payload
Example of Batch Deletion of External Target Group Member
OData Request An example of a batch deletion request as sent by SAP Marketing Cloud: Request URL: https://<HostName>/.../<YourService>/$batch. HTTP Method: POST HEADERS: Content-Type: multipart/mixed;boundary=batch_01869434-0008
Note
Please be aware of the blank lines in the sample batch payloads, they must be maintained and kept empty.
Request Payload Sample Batch Request Payload
--batch_01869434-0008 Content-Type: multipart/mixed; boundary=changeset_01869434-0005-0002 --changeset_01869434-0005-0002 Content-Type: application/http Content-Transfer-Encoding: binary
DELETE ExtTargetGroupMemberFacetSet(ExtTargetGroupId='Ext123',ExtTGKeyPart2Id='ADVERTISE
Integration Guide Integration Scenarios
PUBLIC
173
R',ExtTGKeyPart2Value='SAP_GLOBAL_MARKETING',ExtTGKeyPart3Id='',ExtTGKeyPart3Valu e='',IdOrigin='EMAIL',Id='75304ebddec51e37966325d7950229110177ec502248d106cc29ccd 8612bb75f') HTTP/1.1 --changeset_01869434-0005-0002 Content-Type: application/http Content-Transfer-Encoding: binary DELETE ExtTargetGroupMemberFacetSet(ExtTargetGroupId='Ext123',ExtTGKeyPart2Id='ADVERTISE R',ExtTGKeyPart2Value='SAP_GLOBAL_MARKETING',ExtTGKeyPart3Id='',ExtTGKeyPart3Valu e='',IdOrigin='EMAIL',Id='76304ebddec51e37966325d7950229110177ec502248d106cc29ccd 8612bb75e') HTTP/1.1 --changeset_01869434-0005-0002--
--batch_01869434-0008--
Response Payload
The batch response headers should contain ~status_reason: Accepted, ~status_code: 202 for a valid request.
It's mandatory to maintain the order of response in the batch response payload to match with the requests in the request payload. For every request there is a response expected in the response payload.
The value `204 No Content' in the response is mandatory which denotes the status code and status reason of a successful response.
In case of error, a suitable error message and status code should be available in the response. Please check OData documentation for batch handling. http://www.odata.org/documentation/odataversion-2-0/batch-processing/
Sample Batch Response Payload
--5113C8BC9FF8909118DE29520A93D9430
Content-Type: multipart/mixed; boundary=5113C8BC9FF8909118DE29520A93D9431
Content-Length:
437
--5113C8BC9FF8909118DE29520A93D9431 Content-Type: application/http Content-Length: 71 content-transfer-encoding: binary
HTTP/1.1 204 No Content Content-Length: 0 dataserviceversion: 2.0
--5113C8BC9FF8909118DE29520A93D9431 Content-Type: application/http Content-Length: 71 content-transfer-encoding: binary HTTP/1.1 204 No Content Content-Length: 0 dataserviceversion: 2.0
--5113C8BC9FF8909118DE29520A93D9431--
174
PUBLIC
Integration Guide Integration Scenarios
--5113C8BC9FF8909118DE29520A93D9430--
4.3.2.1.3.3 Transferring Contact Attributes (Deprecated)
Caution
This feature has been deprecated. To transfer contact attributes to external systems, we recommend that you set up an Open Channel Integration. For more information, see Open Channel Integration [page 194].
4.3.2.1.4 Requesting Campaign Success Data
The periodic request for success data consists of two steps: The call for campaign-related administrative data The call for success data The call for success data can result in either a synchronous transfer of data or an asynchronous transfer using a ReportID.
Calling Administrative Data
The administrative data includes the following: The date up to which SAP Marketing Cloud is supposed to request success data for the campaign.
Typically, the date differs from the campaign termination date since the success data is collected after the campaign has ended, based on an attribution window, or because a terminated campaign is resumed for a certain period of time. Indication of the most important KPI for the campaign, which is displayed in SAP Marketing Cloud Since the KPI may not yet be determined when the campaign is created, it is requested with the success data.
For the administrative data, SAP Marketing Cloud calls the GetEntitySet method of the CampaignSet entity set to filter for a list of campaigns (see the following table).
Note that each additional part of the campaign key (from ServerCampaignIDContextCT) is called separately (no filtering for multiple key parts in one GetEntitySet call).
Starting in 1611, there are different calls for ADVERTISER and EXT_CAMPAIGN_MANAGING_PARTY.
Integration Guide Integration Scenarios
PUBLIC
175
GetEntitySet Method Campaign (Entity Type) ClientCampaignId CampaignName StartDate EndDate ServerCampaignId
ReportId
ServerCampaignUrl
Usage in GetEntitySet Method
Not used, ignored in response
Not used, ignored in response No update of the campaign name in SAP Marketing Cloud from the external campaign
Not used, ignored in response No update of the campaign start date in SAP Marketing Cloud from the external campaign
Not used, ignored in response No update of the campaign end date in SAP Marketing Cloud from the external campaign
ID of the campaign in the external system; used as filter by SAP Marketing Cloud Mandatory in response The ID is considered to be the first part of the campaign key on server side.
ID used for asynchronous data transfer Combination of ReportId, ServerCampaignId, and Advertiser must be unique Optional in response, not needed for synchronous transfer
Not used, ignored in response Link to the external campaign No update of the link to the external campaign in the campaign in SAP Marketing Cloud
176
PUBLIC
Integration Guide Integration Scenarios
Campaign (Entity Type) MainKPI
Usage in GetEntitySet Method
Most important KPI, displayed in SAP Marketing Cloud Determines the first measure tiles on the Perfomance tab of the campaign.
Main KPI Options Main KPI NumberOfAppEngagements NumberOfAppInstalls NumberOfClicks
NumberOfDownloads NumberOfEventResponses NumberOfImpressions NumberOfLeads NumberOfMktgOfferClaims NumberOfOrders NumberOfPageLikes NumberOfPostEngagements NumberOfRegistrations NumberOfVideoViews
NumberOfWebsiteConversions
First Tiles
NumberOfAppEngagements, AdSer vingCostAppEngagementInDC
NumberOfAppInstalls, AdServing CostPerAppInstallInDC
NumberOfClicks, AdServingCostPer ClickInDC, AdServing CostPer1000ClicksInDC, Click ThroughRateInPercent
NumberOfDownloads, AdServingCost PerDownloadInDC
NumberOfEventResponses, AdSer vingCostPerEventRspInDC
NumberOfImpressions, AdServing Cost1000ImprsnsInDC
NumberOfLeads, AdServingCostPer LeadInDC
NumberOfMktgOfferClaims, AdSer vingCostPerOfferClaimInDC
NumberOfOrders, AdServingCostPer OrderInDC, OrderAmountInDC
NumberOfPageLikes, AdServingCost PerPageLikeInDC
NumberOfPostEngagements, AdSer vingCostPerPostEngmntInDC
NumberOfRegistrations, AdServing CostRegistrationInDC
NumberOfVideoViews, AdServing CostPerVideoViewInDC, AdServing Cost1000VidViewsInDC, VideoViewe dAverageInPercent
NumberOfWebsiteConversions, Ad ServingCostWebsiteCnvrsnInDC
Optional in response If main KPI is not provided, NumberOfImpressions is the default.
Integration Guide Integration Scenarios
PUBLIC
177
Campaign (Entity Type)
Usage in GetEntitySet Method
SuccessDataEndDate SuccessDataTimeZone
Last date by which SAP Marketing Cloud requests administrative and success data for the campaign
Mandatory in response
The date can be changed until it is reached.
The date can be provided some time after the creation of the campaign, how ever, it is required to prevent endless success data requests.
The time zone for which the success data is requested
Optional in response
If the time zone is missing, the success data is requested for UTC.
Examples: For timezone UTC+05:30, the expected value from the SuccessDataTime
Zone field is UTC+53 For timezone UTC-8:30, the expected the value from the SuccessDataTime
Zone field is UTC-83
Filter CampaignParameterValues
Filter by ServerCampaignIDContextCT
Not used No update of external campaign parameters in SAP Marketing Cloud from the external campaign
An example of a request without additional parameters in the campaign key, as sent by SAP Marketing Cloud:
Request URL: https://<HostName>/../<YourService>/CampaignSet? $filter=(ServerCampaignId eq '54321' or ServerCampaignId eq '54322')& $format=json
HTTP Method: GET
An example of a request including the parameter ADVERTISER in the campaign key, as sent by SAP Marketing Cloud:
Request URL: https://<HostName>/../<YourService>/CampaignSet? $filter=(ServerCampaignId eq '54321' or ServerCampaignId eq '54322') and ((Filter/KeyPart2Id eq 'ADVERTISER') and (Filter/KeyPart2Value eq 'SAP_GLOBAL_MARKETING'))&$format=json
HTTP Method: GET
Note that "Filter": {...} is optional for the SAP Marketing Cloud, and is therefore omitted after the following example.
Sample Response Payload:
Sample Code
{ "d": {
178
PUBLIC
Integration Guide Integration Scenarios
"results": [{ "Filter": { "KeyPart2Id": "", "KeyPart2Value": "", "KeyPart3Id": "", "KeyPart3Value": "" }, "ServerCampaignId": "54321", "MainKPI": "CLICKS", "SuccessDataEndDate": "\/Date(1455494400000)\/", "SuccessDataTimeZone": "UTC"
}, {
"ServerCampaignId": "54322", "MainKPI": "",
"SuccessDataEndDate": "\/Date(1455494400000)\/", "SuccessDataTimeZone": "UTC" }] } }
Calling Actual Success Data
For the actual success data, SAP Marketing Cloud calls the GetEntitySet method of the MarketingSuccessSet to filter for a list of campaigns, and a date range (see the following table). Note that each additional part of the campaign key is called separately. The success data is requested for all relevant campaigns, for today, and for yesterday (as today's data still may change). If the success data changes for a longer period, it can be returned in addition (beyond the requested dates). SAP Marketing Cloud can request success data for the past to recover from errors, or to reconciliate historic data in case of data inconsistencies. SAP Marketing Cloud requests success data using paging. The number of pages (data) is specified in $top and $skip of a request. If the call for one page fails, the already received success data for all campaigns and dates is completely persisted, the partially retrieved data, such as the data for one gender, is discarded. To enable this procedure, SAP Marketing Cloud requests the success data sorted by ServerCampaignId and Date. SAP Marketing Cloud stores the success data completely per campaign, and per date, and it overwrites existing success data completely even when more data is returned than actually requested.
Synchronous and Asynchronous Response The external system can respond with the success data immediately (synchronous response) or with a ReportID (asynchronous response). If a ReportID is received, a second GET request will be sent with ReportID. This process repeats every four hours.
Integration Guide Integration Scenarios
PUBLIC
179
GetEntitySet Method MarketingSuccess (Entity Type)
Usage in GetEntitySet Method
ServerCampaignId (Edm.String, length-32)
ID of the campaign in the external system. The ID is expected to be the first part of the campaign key on server side. Semantic key (characteristic) Used as filter by SAP Marketing Cloud Mandatory in response; to be sorted
Date (Edm.DateTime)
Date of the success data Semantic key (characteristic) Used as filter by SAP Marketing Cloud Mandatory in response, to be sorted YearWeek or YearMonth may be used instead. However, only one of the three is al lowed in a single record.
YearWeek (Edm.String, length-6)
The year and week associated with the success data. Semantic key (characteristic) Used as filter by SAP Marketing Cloud Mandatory in response, to be sorted Date or YearMonth may be used instead. However only one of the three is allowed in a single record.
YearMonth (Edm.String, length-6) The year and month associated Semantic key (characteristic) Used as filter by SAP Marketing Cloud Mandatory in response, to be sorted Date or YearWeek may be used instead. However only one of the three is allowed in a single record.
180
PUBLIC
Integration Guide Integration Scenarios
MarketingSuccess (Entity Type) Usage in GetEntitySet Method
TimeZone (Edm.String, length-6)
Time zone to which the date refers
Time zone is not characteristic (not part of semantic success data key)
Used as filter by SAP Marketing Cloud
Optional in response. If no time zone is provided, UTC is used.
Examples: For timezone UTC+05:30, the expected value from the TimeZone field is UTC
+53 For timezone UTC-8:30, the expected the value from the TimeZone field is
UTC-83
A filter for TimeZone is set when a SuccessDataTimeZone is provided with Campaign/GetEntitySet
CommunicationMedium (Edm.String, length-20)
The communication medium Semantic key (characteristic) Mandatory in response Relevant communication media: DISPLAY_ADS MOBILE_ADS
Gender (Edm.String, length-1)
Gender to which the success data is related SAP Marketing Cloud provides a mapping of external to internal gender codes. Standard: FEMALE | MALE Semantic key (characteristic) Optional in response; if not provided, the gender is considered as unknown
Country(Edm.String, length 40) Region(Edm.String, length 40)
Country that the success data is related to SAP Marketing Cloud provides a mapping of external to internal country codes. Semantic key (characteristic) Optional in response; if not provided, the country is considered as unknown
Region that the success data is related to SAP Marketing Cloud provides a mapping of external to internal region codes. Semantic key (characteristic) Optional in response; if not provided, the region is considered as unknown
Integration Guide Integration Scenarios
PUBLIC
181
MarketingSuccess (Entity Type) Usage in GetEntitySet Method
AgeRangeLow (Edm.Byte, length-3) Lower boundary of age
AgeRangeLow and AgeRangeHigh specify the age range to which the success data is related. The age ranges should not differ for all success data from the same external system. If data is available for each exact age, set AgeRangeLow and AgeRangeHigh to the same value.
Semantic key (characteristic)
Optional in response; if not provided, the age is considered as unknown
AgeRangeHigh (Edm.Byte, length-3)
Higher boundary of age Semantic key (characteristic) Optional in response; if not provided the age is considered as unknown
CampaignContentLinkName (Edm.String)
Name of the link in the campaign content that the success data refers to Typically only provided for the KPIs "Clicks" and "UniqueClicks" Semantic key (characteristic) Optional in response
SpendAmount (Edm.Decimal, Pre cision- 31, scale -2)
Amount spend for the campaign on the external platform KPI
Optional in response
SpendCurrency (Edm.String, length-5)
Currency of SpendAmount One currency per campaign is supported Mandatory in response when SpendAmount is provided
UniqueImpressions (Edm.Int32, length-10)
Number of unique impressions KPI Optional in response
Impressions (Edm.Int32, length-10) Number of impressions KPI Optional in response
UniqueClicks (Edm.Int32, length-10)
Number of unique clicks KPI Optional in response
182
PUBLIC
Integration Guide Integration Scenarios
MarketingSuccess (Entity Type) Usage in GetEntitySet Method
Clicks (Edm.Int32, length-10)
Number of clicks KPI Optional in response
Orders (Edm.Int32, length-10)
Number of orders KPI Optional in response
OrderAmount (Edm.Decimal, Preci Monetary value of the orders
sion- 31, scale -2)
KPI
Optional in response
OrderAmountCurrency (Edm.String, length-5)
Currency of OrderAmount KPI Optional in response
VideoViews (Edm.Int32, length-10
Number of video views KPI Optional in response
VideoViewedAverageInPercent (Edm.Decimal, Precision- 5, scale -2)
Average percentage of video viewed KPI Optional in response
Registrations (Edm.Int32, length-10)
Number of registrations KPI Optional in response
Downloads (Edm.Int32, length-10) Number of downloads KPI Optional in response
SentMessages (Edm.Int32, length-10)
Number of sent messages KPI Optional in response
RejectedMessages (Edm.Int32, length-10)
Number of rejected messages KPI Optional in response
Integration Guide Integration Scenarios
PUBLIC
183
MarketingSuccess (Entity Type) Usage in GetEntitySet Method
DeliveredMessages (Edm.Int32, length-10)
Number of delivered messages KPI Optional in response
OpenedMessages (Edm.Int32, length-10)
Number of opened messages KPI Optional in response
HardBounces (Edm.Int32, length-10)
Number of hard bounces KPI Optional in response
SoftBounces (Edm.Int32, length-10)
Number of soft bounces KPI Optional in response
PageLikes (Edm.Int32, length-10)
Number of page likes KPI Optional in response
PostEngagements (Edm.Int32, length-10)
Number of post engagements KPI Optional in response
OfferClaims (Edm.Int32, length-10) Number of offer claims KPI Optional in response
WebsiteConversions (Edm.Int32, length-10)
Number of website conversions KPI Optional in response
AppInstalls (Edm.Int32, length-10) Number of app installs KPI Optional in response
AppEngagements (Edm.Int32, length-10)
Number of app engagements KPI Optional in response
184
PUBLIC
Integration Guide Integration Scenarios
MarketingSuccess (Entity Type) Usage in GetEntitySet Method
Filter
Filter by ServerCampaignIDContextCT
GrossRatingPoints (Edm.Decimal, The number impressions for a defined population in relation to the size of this popula
Precision- 15, scale -2)
tion.
Gross rating points are defined as 100 * impressions / size of defined population
KPI
Optional in response
GrossRatingPointBase (Edm.String, The population the gross rating points relate to for example, "US M18-39", which in
length-80)
dicates that the gross rating points relate to male adults from 18 to 39 in the US.
Semantic key (characteristic)
Optional in response; it's recommended to always provide a gross rating point base together with gross rating points.
InteractionReason (Edm.String, length-20)
Reason for the interaction Possible values can be found in configuration. For more information, see Managing In teraction Content. Semantic key (characteristic) Optional in response
InteractionType (Edm.String, length-20)
Type of interaction Possible values can be found in configuration. For more information, see Managing In teraction Content. Semantic key (characteristic) Optional in response
InteractionStatus (Edm.String, length-2)
Status of interaction
Possible values: 01 (In Process) 02 (Released) 03 (Completed) 04 (Canceled) 05 (Converted) 06 (Successful) 07 (Unsuccessful) 00 (New)
Semantic key (characteristic)
Optional in response
Integration Guide Integration Scenarios
PUBLIC
185
MarketingSuccess (Entity Type) Usage in GetEntitySet Method
DeviceType (Edm.String, length-60)
The type of device, for example tablet or desktop Semantic key (characteristic) Optional in response
AdNetwork (Edm.String, length-60) The company that connects advertisers to the websites that host advertisements Semantic key (characteristic) Optional in response
CampaignContentName (Edm.String, length-100)
Name of the campaign content that the success data refers to Semantic key (characteristic) Optional in response
ExecutedInteractions (Edm.Int64, length-10)
Number of executed interactions KPI Optional in response
EventResponses (Edm.Int64, length-10)
Number of event responses KPI Optional in response
Leads (Edm.Int64, length-10)
Number of leads KPI Optional in response
Opportunities (Edm.Int64, length-10)
Number of opportunities KPI Optional in response
PhoneCalls (Edm.Int64, length-10) Number of phone calls KPI Optional in response
Appointments (Edm.Int64, length-10)
Number of appointments KPI Optional in response
FailedInteractions (Edm.Int64, length-10)
Number of failed interactions KPI Optional in response
186
PUBLIC
Integration Guide Integration Scenarios
MarketingSuccess (Entity Type) Usage in GetEntitySet Method
OfferViews (Edm.Int64, length-10) Number of offer views KPI Optional in response
EmailComplaints (Edm.Int64, length-10)
Number of email complaints KPI Optional in response
Tasks (Edm.Int64, length-10)
Number of Tasks KPI Optional in response
UniqueImpressionsInPercent (Edm.Decimal, Precision-5, scale-2)
Reach in percent KPI Optional in response
OpportunityAmount (Edm.Decimal, Monetary value of the opportunity
Precision- 31, scale -2)
KPI
Optional in response
OpportunityAmountCurrency (Edm.String, length-5)
Currency for opportunity value Semantic key (characteristic) Mandatory in response when OpportunityAmount is provided
An example of a campaign success data request, with no additional parameters in the campaign key, as sent by SAP Marketing Cloud:
Note
Certain aggregated KPIs don't have values for "Date" or "Timezone". To support ;, the OData request calls have additional filters in the request: ((TimeZone eq `'), (Date eq null)) .
Request URL: https://<HostName>/.../<YourService>/MarketingSuccessSet? $filter=((ServerCampaignId eq '54321') or (ServerCampaignId eq '54322')) and ((TimeZone eq `UTC') or (TimeZone eq `')) and ((Date ge datetime'2016-01-27T00:00:00' and Date le datetime'2016-01-28T00:00:00') or (Date eq null))&$top=50&$skip=50&$format=json&$orderby=ServerCampaignId,Date desc
HTTP Method: GET
An example of a campaign success data request, including the parameter ADVERTISER in the campaign key, as sent by SAP Marketing Cloud:
Integration Guide Integration Scenarios
PUBLIC
187
Request URL: https://<HostName>/.../<YourService>/MarketingSuccessSet? $filter=((ServerCampaignId eq '54321') or (ServerCampaignId eq '54322')) and (Filter/KeyPart2Id eq 'ADVERTISER' and Filter/KeyPart2Value eq 'SAP_GLOBAL_MARKETING')and ((TimeZone eq `UTC') or (TimeZone eq `')) and ((Date ge datetime'2016-01-27T00:00:00' and Date le datetime'2016-01-28T00:00:00') or (Date eq null))&$top=50&$skip=50&$format=json&$orderby=ServerCampaignId,Date desc
HTTP Method: GET
Sample Response Payload (Synchronous):
Sample Code
{ "d": {
Date(1487635200000)\/", "DISPLAY_ADS",
"0.00",
"results": [{ "ServerCampaignId": "54321", "Date": "\/ "CommunicationMedium": "CampaignContentLinkName": "", "TimeZone": "UTC", "Gender": "2", "Country": "", "Region": "", "AgeRangeLow": 55, "AgeRangeHigh": 64, "SpendAmount": "60.00", "SpendCurrency": "USD", "UniqueImpressions": 0, "Impressions": 511, "Clicks": 5660, "UniqueClicks": 0, "Orders": 0, "OrderAmount": "70.00", "OrderCurrency": "USD", "Registrations": 0, "Downloads": 0, "HardBounces": 0, "SoftBounces": 0, "SentMessages": 0, "RejectedMessages": 0, "OpenedMessages": 0, "DeliveredMessages": 0, "PageLikes": 0, "PostEngagements": 0, "OfferClaims": 0, "VideoViews": 0, "VideoViewedAverageInPercent": "WebsiteConversions": 0, "AppInstalls": 0, "AppEngagements": 0, "GrossRatingPoints": "0.00", "GrossRatingPointBase": "", "YearWeek": "201751", "YearMonth": "", "InteractionReason": "", "InteractionType": "", "InteractionStatus": "06", "DeviceType": "DESKTOP", "AdNetwork": "GOOGLE_SEARCH", "CampaignContentName": " ", "ExecutedInteractions": 0,
188
PUBLIC
Integration Guide Integration Scenarios
"0.00",
"USD", }
}
"EventResponses": 0, "Leads": 100, "Opportunities": 20, "PhoneCalls": 3612, "Appointments": 200, "FailedInteractions": 0, "OfferViews": 0, "EmailComplaints": 0, "Tasks": 0, "UniqueImpressionsInPercent": "OpportunityAmount": "70.00", "OpportunityAmountCurrency": }]
Sample Response Payload with Report ID (Asynchronous):
Sample Code
{ "d": { "results": [{ "ServerCampaignId": "54321", "ReportId": "4711" }, { "ServerCampaignId": "54322", "ReportId": "4711" }] }
}
An example of a campaign success data request with ReportId: Request URL: https://<HostName>/.../<YourService>/MarketingSuccessSet?
$filter=( ReportId eq '4711') and (Filter/KeyPart2Id eq 'ADVERTISER' and Filter/ KeyPart2Value eq 'SAP_GLOBAL_MARKETING') &$top=50&$skip=50&$format=json HTTP Method: GET
Sample Response Payload:
Sample Code
{ "d": { "results": [{ "ServerCampaignId": "54321", "Date": "\/Date(1474588800000)\/", "CommunicationMedium": "DISPLAY_ADS", "SpendAmount": "60.00", "SpendCurrency": "USD", "UniqueImpressions": 0, "Impressions": 511, "Clicks": 32, "ReportId": "4711" }, "ServerCampaignId": "54322", "Date": "\/Date(1474588800000)\/", "CommunicationMedium": "DISPLAY_ADS", "AppEngagements": 300,
Integration Guide Integration Scenarios
PUBLIC
189
"ReportId": "4711" }] } }
If no data is available, an empty response will be received. It may also be the case that there is not data available for all campaigns with the ReportID, and the response will only contain campaigns for which there is data available.
Related Information
Creating Custom OData Fields for Campaign Success Data [page 190]
4.3.2.1.4.1 Creating Custom OData Fields for Campaign Success Data
Prerequisites
Define the custom field in the Custom Fields application with the business context Marketing: Campaign Performance Actual Measure. For more information about setting up custom fields, see Creating Custom Fields. For more information about custom fields for campaign performance, including dimensions and target measures in addition to actual measures, see Custom Fields for Campaign Performance. When you enter a label, an identifier is automatically generated. Example custom field label: Tickets Sold Generated identifier: YY1_TicketsSold_MCS The prefix YY1 and suffix MCS are automatically generated.
In the external campaign interface, add the custom field under MarketingSuccess Entity as a property. The field name must be the same throughout. Example: YY1_TicketsSold_MCS
Once defined, the external interface can send the value for the new field. Sample OData response with the custom field YY1_TicketsSold_MCS:
Sample Code
{ "d": {
Date(1487635200000)\/", "DISPLAY_ADS",
"results": [{ "ServerCampaignId": "54321", "Date": "\/ "CommunicationMedium": "SpendAmount": "60.00", "SpendCurrency": "USD", "Impressions": 511,
190
PUBLIC
Integration Guide Integration Scenarios
"Clicks": 5660, "YY1_TicketsSold_MCS": "3443" }] } }
4.3.2.1.5 Handling Errors
If an error occurs when retrieving the required parameters, or when creating the campaign in the external system, SAP Marketing Cloud blocks the process until the error is resolved. The error messages are displayed in your application. If an error occurs when tranferring target group members, the error log can be accessed on the Automation panel, in the Create External Target Group section. If an error occurs when retrieving the success data, a red status for the success data retrieval is displayed in your application. Clicking the red status provides the detailed error messages. If one request for success data fails, the already retrieved success is still available. If requests for success data fail, the requests are automatically repeated with the next success data retrieval. For the error response, error-code, and error-message-value are mandatory. Further error messages can be returned as error-innererror. Example of an error response:
Sample Code
{ "error":{ "code":"123", "message":{ "lang":"en", "value":"Your error message describing the issue" }, "innererror":{ "errordetails":[{ "code":"234", "message":"Your description for the error resolution", "severity":"error" }] } }
}
For more information about error handling, see http://www.odata.org/documentation/odata-version-2-0/ operations/ .
Integration Guide Integration Scenarios
PUBLIC
191
4.3.2.2 Communication Arrangement for External Campaign Execution
You set up a communication arrangement to enable the external campaign execution, and the requesting of success data from the external system. To set up a communication arrangement, you require the business catalog role Marketing Business Administration (SAP_BCR_CEC_MKT_ADM_PC).
To set up a communication arrangement for external campaign execution you create a communication system, and a communication arrangement.
Communication System
Create the communication system as follows:
1. In the SAP Fiori launchpad, click Communication Systems. In Communication Systems, click New. 2. In the New Communication System dialog, define the ID for the communication system, for example,
Z_CUAN_ECPG. Define a System Name. You can freely define a name; note that the name is used when you create the communication arrangement. Click Create. 3. Under Technical Data, Host Name, specify the external system you want to use for the campaign execution, such as Facebook, or Twitter. Indicate the pure host name, no path, no port. Note that Log System ID, Client Name, and Business System are not relevant for the external campaign execution. 4. Optionally, you can provide your Contact Information for the communication system you are defining. 5. Under User for Outbound Communication, click + to add a set of access details for the external server. One option is to use the Authentication Method user and password by entering the information in the corresponding fields. Alternatively, you can use authentication via an SSL client certificate. For this option, you need to select Default Client Certificate as the certificate type and then download the certificate before creating the outbound user. 6. Click Save to save the new or edited communication system in an active status.
If you chose the SSL client certificate as your authentication method, you will need to upload the certificated you downloaded to your external server. For example, if you have implemented the interface for externally executed campaigns on SAP Cloud Integration, the certificate has to be uploaded to the HTTP channel of your integration flow.
Communication Arrangement for Use of External Platforms in Multichannel Campaigns
Create the communication arrangement as follows: 1. In the SAP Fiori launchpad, click Communication Arrangement. In Maintain Communication Arrangement,
click New. 2. In the New Communication Arrangement dialog, under Scenario, use the value help to select the predefined
scenario Marketing - External Campaign Execution Integration (SAP_COM_0037). Under Arrangement Name, define a name.
192
PUBLIC
Integration Guide Integration Scenarios
3. Under Common Data, Communication System, use the value help to select the communication system you have created (see section Communication System). Note that My System is not relevant for external campaign execution.
4. Under Outbound Communication, use the value help to select the relevant system access details, which you have specified in the communication system you are using for the communication arrangement. For multichannel campaigns, OAuth authentication is not supported.
5. Under Additional Properties, define an External Campaign System ID. If you are setting up a communication for Google Campaign Manager, use the code SDM. For other external platforms, use a three letter code that starts with Z. This ID cannot be changed later. Here you can also define an action name. This name will be used for the multichannel action in the campaign designer.
6. Under Additional Properties, you can specify a marketing area for which this action is relevant. If you do, the action will only be available in a multi-channel campaign that has the same marketing area.
7. Under Outbound Services, specify the paths for the predefined outbound services using the following pattern: /<your_service>/<your_entity>. The predefined services map to the following actions (specified as entity): Request campaign parameters (CampaignParameterSet)
Create campaign (CampaignSet)
Request success data for the executed campaign (MarketingSuccessSet)
Transferring external target group (ExtTargetGroupSet)
Transferring external target group members (ExtTargetGroupMemberFacetSet)
Read supported ID origins for external system (ExtTargetGroupSupportedIdOriginSet)
Retrieve information for the value help for campaign assignment (CampaignValueHelpSet) Note that the outbound services are defined in the Scenario you have selected when creating the communication arrangement. 8. Click Save to save the new or edited communication arrangement in an active status.
Communication Arrangement for External-Only Campaigns
You require a campaign category for campaigns that are externally executed only. Your system comes with a general category that can be set up for use with the external system of your choice. Only one external campaign category is available, but may be edited using the configuration app Define Campaign Categories and Actions. If you need more external campaign categories, you can copy the delivered entry and enter a unique ID and your desired name for the new category.
Typically, one campaign category corresponds to one external campaign execution system.
Note
To perform HTTP calls to an external system from SAP Marketing Cloud, a trust relationship with the external system is required. If this relationship is not established by default, such as when using SAP Cloud Integration, you have to upload the root certificate of the external system's host in the Maintain Certificate Trust List app in SAP Marketing Cloud.
Create the communication arrangement as follows: 1. In the SAP Fiori launchpad, click Communication Arrangement. In Maintain Communication Arrangement,
click New.
Integration Guide Integration Scenarios
PUBLIC
193
2. In the New Communication Arrangement dialog, under Scenario, use the value help to select the predefined scenario Marketing - External Campaign Execution Integration (SAP_COM_0037). Under Arrangement Name, define a name using the following pattern: ExtCampaignExec_<campaign_category>, for example, ExtCampaignExec_EEC. For authorization purposes, you can optionally include a marketing area in the arrangement name. To include the marketing area, extend the pattern as follows: ExtCampaignExec_<campaign_category>_<marketing_area>. If you add a marketing area ID in the communication arrangement name, such arrangement will be use to send data to the external system when executing external campaigns which have the same marketing area. If more marketing areas are used, you need to create one communication arrangement per marketing area. If a communication arrangement for a given marketing area is not found, the system uses a more generic arrangement which name pattern is ExtCampaignExec_<campaign_category>.
3. Under Common Data, Communication System, use the value help to select the communication system you have created (see section Communication System). Note that My System is not relevant for external campaign execution.
4. Under Outbound Communication, use the value help to select the relevant system access details, which you have specified in the communication system you are using for the communication arrangement. For external-only campaigns, OAuth authentication is not supported.
5. Do not define an External Campaign System ID under Additional Properties. This will mark the communication arrangement for use in multichannel campaigns and not external-only campaigns.
6. Under Outbound Services, specify the paths for the predefined outbound services using the following pattern: /<your_service>/<your_entity>. The predefined services map to the following actions (specified as entity): Request campaign parameters (CampaignParameterSet) Create campaign (CampaignSet) Request success data for the executed campaign (MarketingSuccessSet) Transferring external target group (ExtTargetGroupSet) Transferring external target group members (ExtTargetGroupMemberFacetSet) Read supported ID origins for external system (ExtTargetGroupSupportedIdOriginSet) Retrieve information for the value help for campaign assignment (CampaignValueHelpSet) Note that the outbound services are defined in the Scenario you have selected when creating the communication arrangement.
7. Click Save to save the new or edited communication arrangement in an active status.
4.3.3 Open Channel Integration
With this integration you create own actions that send data for further processing to an external system, such as SAP Business Technology Platform, when the campaign has been executed. But you can also just implement the inbound side of this integration to get external data in your campaigns.
Technology: OData Service using SAP BTP
194
PUBLIC
Integration Guide Integration Scenarios
Benefits
Develop custom logic for the campaign automation in SAP Marketing Cloud:
Programmatically connect external applications using SAP BTP by developing custom actions in the campaign automation.
Automatically provide follow-up data for any external system such as lettershop, mobile app, web shop, or service portal.
Pass over all personalization data automatically for each contact using SAP BTP. In-place analytics for outbound and inbound interactions Campaign (with all actions) is executed in the SAP system Targeted contact is known. Guaranteed delivery. You can use SAP or partner infrastructure, as Amazon or SAP Cloud for Customer. Content needs to be provided by receiving system (not part of SAP Marketing)
Integration Guide Integration Scenarios
PUBLIC
195
System Setup and Integration Steps
For setting up the Open Channel Integration you walk through the following steps:
1. Check that the business catalog role Marketing - Segmentation and Campaign Configuration (SAP_CEC_BC_MKT_CPC_PC) has been assigned to your user.
2. Adapt Enhancements [page 206] (mandatory for outbound) For a minimal integration you have to implement only the enhancement (1) Open Channel: Define Implementations and define an Implementation ID.
3. Setting Up SAP Business Technology Platform [page 217] (mandatory for outbound) 4. Create Communication Systems and Arrangements [page 218] (mandatory for outbound) 5. Setup SAP BTP according to your needs. (mandatory for outbound)
For more information for this step and the following ones, see Inbound Service Settings API [page 229]. 6. Then adapt the enhancement (5) Open Channel: Define Template for Outbound Interaction. (mandatory for
inbound) For more information, see Processing Details [page 198] and Inbound Service Settings API [page 229].
196
PUBLIC
Integration Guide Integration Scenarios
7. Create communication systems and arrangements for the inbound side. (mandatory for inbound) 8. Dependent on how you set up your integration and to be able to use the Open Channel action in your
system, you create an export definition: 1. Choose the Export Definitions app and under Details choose New. 2. Then enter a Definition. You can freely define a name; note that the name is used when you assign the
Open Channel action in the campaign user interface (UI). 3. Select Usage Open Channel. 4. Select a Segmentation Profile, for example, All Contacts. 5. Select an Export Profile, for example, File Export. 6. Under Available select these attributes you want to use in your export definition and bring them to the
list Selected for Export Definition. 7. Choose Save to save the new export definition.
Note
This step is optional.
In the following you find some useful thoughts for the implementation:
We recommend to plan the integration flow beforehand, because at least you need to implement the Processing integration flow, which is mandatory, and you can do everything in this implementation. But you can also do all three or only two of the offered open channel implementations, just depending of your needs.
Preprocessing and Processing send their data in the deep create format that means the whole data structure is created directly.
All processing steps of the integration send messages by HTTP Post method, but only the creation mode is supported which means this integration enforces the creation of new object instances in the external system, but not any updates and deletions.
We recommend to use the HTTP sender channel at least for the processing step, because scripting might be required anyway for transforming the attribute IDs and values of the TargetGroupMemberAttributeData entity set into a new message.
Read the information about the message choreography and the error handling in chapter OData Service Settings for Outbound [page 220].
Create a Campaign
Now you can create a campaign and use the action Open Channel.
For more information about the general handling, see Creating a Campaign under Use Cases.
Integration Guide Integration Scenarios
PUBLIC
197
4.3.3.1 Processing Details
With the implementation, you can execute a campaign and send outbound objects also to an external system using SAP Business Technology Platform.
When the work has been done in the external system, you can get back data to analyze your success and create follow-up triggers in your system, for example, by using a trigger-based campaign. The selection of transferred data is done by using an export definition.
198
PUBLIC
Integration Guide Integration Scenarios
The graphic shows the process steps and the systems that are involved:
Integration Guide Integration Scenarios
PUBLIC
199
Note
The following description is an example and demonstrates the steps and the data required to link outbound and inbound records for open channel processing.
Campaign Execution
The campaign has a target group with the following members: Julie Armstrong John Miller Michael Adams The campaign executes the open channel action. The action transfers data using the OData service CUAN_CAMPAIGN_OPEN_CHANNEL and the entity sets CampaignExecutionRunPackages, CampaignTargetGroupMembers, and TargetGroupMemberAttributeData:
Sample Code
{ "d": { "Campaign": { "CampaignId": "0000381379", "Name": "Open Channel Demo 1", "MarketingAreaId": "CXXGLOBAL", "SegmentationObject": "SAP_CONTACT_ENGAGEMENT_SIN", "ImplementationId": "ZOC_EXPORT" }, "PackageId": 1, "ExecutionStartDateTime": "2016-07-07T07:44:40Z", "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "CampaignTargetGroupMembers": [ { "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10", "PackageId": 1, "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "TargetGroupMemberAttributeData": [ { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-
NAME_FIRST", "Value": "Julie", "EdmTypeId": "Edm.String", "OutboundId":
"1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-
NAME_LAST", "Value": "Armstrong", "EdmTypeId": "Edm.String", "OutboundId":
"1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-
CONTACT_KEY", "Value": "005056AC4A181ED598D20A84AB8AC6E9", "EdmTypeId": "Edm.Binary", "OutboundId":
"1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, {
200
PUBLIC
Integration Guide Integration Scenarios
"AttributeId": "OUTBOUND_INTERACTION", "Value": "8CDCD4A847681EE69182D4A1498E1EF5", "EdmTypeId": "Edm.String", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "ZOC_EXPORT_DESCRIPTION", "Value": "Open Channel Demo 1", "EdmTypeId": "Edm.String", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "ZOC_EXPORT_DATE", "Value": "2016-07-07", "EdmTypeId": "Edm.Date", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "ZOC_EXPORT_PRIORITY", "Value": "PRIORITY_1", "EdmTypeId": "Edm.String", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" } ] }, { "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23", "PackageId": 1, "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "TargetGroupMemberAttributeData": [ { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMERNAME_FIRST", "Value": "John", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMERNAME_LAST", "Value": "Miller", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMERCONTACT_KEY", "Value": "005056AC4A181ED598D20A84AB8B06E9", "EdmTypeId": "Edm.Binary", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "OUTBOUND_INTERACTION", "Value": "8CDCD4A847681EE69182D4A1498EDEF5", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "ZOC_EXPORT_DESCRIPTION", "Value": "Open Channel Demo 1", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "ZOC_EXPORT_DATE", "Value": "2016-07-07", "EdmTypeId": "Edm.Date",
Integration Guide Integration Scenarios
PUBLIC
201
"OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23"
}, { "AttributeId": "ZOC_EXPORT_PRIORITY", "Value": "PRIORITY_1", "EdmTypeId": "Edm.String", "OutboundId":
"EA297547B0DBBDF81C308FD14A3757C1420ABB23" }
] }, {
"OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF", "PackageId": 1, "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "TargetGroupMemberAttributeData": [
{ "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-
NAME_FIRST", "Value": "Michael", "EdmTypeId": "Edm.String", "OutboundId":
"CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-
NAME_LAST", "Value": "Adams", "EdmTypeId": "Edm.String", "OutboundId":
"CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-
CONTACT_KEY", "Value": "40F2E93065BD1ED598D1DCFDB65F97C0", "EdmTypeId": "Edm.Binary", "OutboundId":
"CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "OUTBOUND_INTERACTION", "Value": "8CDCD4A847681EE69182D4A1498F3EF5", "EdmTypeId": "Edm.String", "OutboundId":
"CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "ZOC_EXPORT_DESCRIPTION", "Value": "Open Channel Demo 1", "EdmTypeId": "Edm.String", "OutboundId":
"CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "ZOC_EXPORT_DATE", "Value": "2016-07-07", "EdmTypeId": "Edm.Date", "OutboundId":
"CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "ZOC_EXPORT_PRIORITY", "Value": "PRIORITY_1", "EdmTypeId": "Edm.String", "OutboundId":
"CA5F1FE120237480E6054B06D61371081AE095DF" }
] } ] } }
202
PUBLIC
Integration Guide Integration Scenarios
Note
The transferred OutboundId is kept by the external system because this ID serves as external anchor to link outbound and inbound records.
Outbound Interactions
The campaign must create outbound interactions, otherwise the inbound data cannot be linked to the campaign.
To create outbound interactions you implement the enhancement (5) Open Channel: Define Template for Outbound Interaction.
Sample Code
template-id_origin
= 'SAP_HYBRIS_MKT_IC'.
template-interaction_type
= 'ZOC_CALL_CENTER_OUTB'.
template-communication_medium = 'BUSINESS_DOCUMENT'.
The following outbound interactions have been created:
DB_KEY 1
2
3
ID_ORIGIN ID
COMM_MEDI
UM
IA_TYPE
SOURCE_OB SOURCE_OB
INITIATIV
JECT_TYPE JECT_ID TIMESTAMP E_ID
SAP_HYBRI 005056AC4 BUSINESS_ ZOC_CALL_ CUAN_MARK 1202654B2 2016-07-0 381379
S_MKT_IC A181ED598 DOCUMENT CENTER_OU ETING_ORC 1C72A50A0 7T07:48:4
D20A84AB8
TB
HESTRATIO D4E5CB35E 8Z
AC6E9 =
N
6D2FBE916
contact key
EA10
of Julie
Armstrong
SAP_HYBRI 005056AC4 BUSINESS_ ZOC_CALL_ CUAN_MARK EA297547B 2016-07-0 381379
S_MKT_IC A181ED598 DOCUMENT CENTER_OU ETING_ORC 0DBBDF81C 7T07:48:4
D20A84AB8
TB
HESTRATIO 308FD14A3 8Z
B06E9 =
N
757C1420A
contact key
BB23
of John
Miller
SAP_HYBRI 40F2E9306 BUSINESS_ ZOC_CALL_ CUAN_MARK CA5F1FE12 2016-07-0 381379
S_MKT_IC 5BD1ED598 DOCUMENT CENTER_OU ETING_ORC 0237480E6 7T07:48:4
D1DCFDB65
TB
HESTRATIO 054B06D61 8Z
F97C0 =
N
371081AE0
contact key
95DF
of Michael
Adams
Integration Guide Integration Scenarios
PUBLIC
203
Meaning of the attributes:
ID_ORIGIN: set by enhancement coding, see template-id_origin ID: key of contact, set by campaign execution COMM_MEDIUM: set by enhancement coding, see template-communication_medium IA_TYPE: set by enhancement coding, see template-interaction_type SOURCE_OBJECT_TYPE: always CUAN_MARKETING_ORCHESTRATION, set by campaign execution SOURCE_OBJECT_ID: this ID is the OutboundId, set by campaign execution TIMESTAMP: time stamp when outbound happened, set by campaign execution INITIATIVE_ID: ID of the campaign, set by campaign execution
Inbound Interactions
In the external system, the transferred data is processed and the processing of the data for the contact Michael Adams results into an inbound interaction.
Note
Before calling the import service, the external system must request the X-CSRF-token: /sap/opu/ odata/sap/API_MKT_INTERACTION_SRV/InteractionsDeepInsert
The external system uses the OData service API_MKT_INTERACTION and transfers the following data using the entity set ImportHeaders:
Sample Code
{ "UUID": "32575914-a9db-476c-a51a-2b0d4a899b95", "Interactions": [ { "InteractionUUID":
"00000000-0000-0000-0000-000000000000", "InteractionType": "ZOC_CALL_CENTER_INB", "InteractionSourceObjectType":
"CUAN_CAMPAIGN_OUTBOUND", "InteractionSourceObject":
"18D3620CC1DBAEB8E5F97AFB922E84E092F271F0", "InteractionTimeStampUTC":
"2019-06-13T08:55:00" }, { "InteractionUUID":
"00000000-0000-0000-0000-000000000000", "InteractionType": "ZOC_CALL_CENTER_INB", "InteractionSourceObjectType":
"CUAN_CAMPAIGN_OUTBOUND", "InteractionSourceObject":
"0FB6D7D9DCDB8616A4A39D0E931C01DA57B5E48F", "InteractionTimeStampUTC":
"2019-06-13T08:55:00" }
] }
The OutboundId is transferred with the SourceObjectId. By setting SourceObjectType to CUAN_CAMPAIGN_OUTBOUND the OData service knows that the given OutboundId belongs to an open channel
204
PUBLIC
Integration Guide Integration Scenarios
scenario and copies data from the outbound to the inbound record: InteractionContact, Campaign, CampaignExecutionRun, and so on, are determined by the OutboundId and therefore not provided by the external system.
For more information, see Inbound Service Settings API [page 229].
After a successful processing of the OData service, the interaction table contains the following outbound (DB_KEY: 1 - 3) and inbound (DB_KEY: 4) records:
DB_KEY
ID_ORIGIN ID
COMM_MEDI
UM
IA_TYPE
SOURCE_OB SOURCE_OB
INITIATIV
JECT_TYPE JECT_ID TIMESTAMP E_ID
1
SAP_HYBRI 005056AC4 BUSINESS_ ZOC_CALL_ CUAN_MARK 1202654B2 2016-07-0 381379
S_MKT_IC A181ED598 DOCUMENT CENTER_OU ETING_ORC 1C72A50A0 7T07:48:4
D20A84AB8
TB
HESTRATIO D4E5CB35E 8Z
AC6E9 =
N
6D2FBE916
contact
EA10
key of
Julie
Armstrong
2
SAP_HYBRI 005056AC4 BUSINESS_ ZOC_CALL_ CUAN_MARK EA297547B 2016-07-0 381379
S_MKT_IC A181ED598 DOCUMENT CENTER_OU ETING_ORC 0DBBDF81C 7T07:48:4
D20A84AB8
TB
HESTRATIO 308FD14A3 8Z
B06E9 =
N
757C1420A
contact
BB23
key of
John
Miller
3
SAP_HYBRI 40F2E9306 BUSINESS_ ZOC_CALL_ CUAN_MARK CA5F1FE12 2016-07-0 381379
S_MKT_IC 5BD1ED598 DOCUMENT CENTER_OU ETING_ORC 0237480E6 7T07:48:4
D1DCFDB65
TB
HESTRATIO 054B06D61 8Z
F97C0 =
N
371081AE0
contact
95DF
key of
Michael
Adams
4
SAP_HYBRI 40F2E9306 BUSINESS_ ZOC_CALL_ CUAN_MARK CA5F1FE12 2016-07-2 381379
S_MKT_IC 5BD1ED598 DOCUMENT CENTER_IN ETING_ORC 0237480E6 3T19:56:2
D1DCFDB65
B
HESTRATIO 054B06D61 9Z
F97C0 =
N
371081AE0
contact
95DF
key of
Michael
Adams
The OData service API_MKT_INTERACTION changes the source object type from CUAN_CAMPAIGN_OUTBOUND back to CUAN_MARKETING_ORCHESTRATION. CUAN_MARKETING_ORCHESTRATION is the source object type of the corresponding outbound record.
Integration Guide Integration Scenarios
PUBLIC
205
4.3.3.2 Adapt Enhancements
You define an implementation for an enhancement to enable the campaign execution to use the open channel action.
To define an implementation, you require the business catalog role Communication Management (SAP_CORE_BC_COM).
Create the implementation as follows:
1. Open the Custom Logic app and choose Create (+ icon).. 2. In the New Enhancement Implementation dialog select Marketing: Campaign as Business Contextand
as Enhancement Option the following enhancements depending of what you want to do: (1) Open Channel: Define Implementations (mandatory) (2) Open Channel: Define Parameters for Implementation (optional) (3) Open Channel: Define Global Settings for Execution (optional) (4) Open Channel: Enhance Payload for Data Transfer (optional) (5) Open Channel: Define Template for Outbound Interaction (mandatory)
Note
The implementation of this enhancement is mandatory for creating any kind of interactions such as contact has been rejected by permission checks, and for processing inbound interactions. But it is optional for the outbound interactions.
3. Then enter a name and choose Create. 4. The example coding is automatically used in the draft version. You can use this coding or modify it. 5. Choose Test to test the coding. 6. Choose Publish to release your coding.
Note
The Implementation ID, such as ZOC_EXPORT, will be used in the communication arrangement as property value.
For more information, see:
Data Flow [page 233]
BAdI Details [page 207] Here you find additional information about the offered BAdIs for the open channel integration.
Activating Marketing Permissions [page 215] With the following adaptations in the example coding of the enhancements you can activate marketing permissions for your open channel integration.
Get Deviating Communication ID Based on Origin ID [page 216] You can get deviating communication IDs based on origin IDs, doing some coding in enhancements. You need this switch, in case you have activated the enhancement (5) Open Channel: Define Template for Outbound Interaction. If the communication ID does not fit to the origin ID, the system cannot create interactions.
206
PUBLIC
Integration Guide Integration Scenarios
4.3.3.2.1 BAdI Details
Here you find additional information about the offered BAdIs for the open channel integration.
Recommendation
We recommend to adapt the BAdIs according the given numbering.
We also recommend that you review the provided examples for each BAdI in the Custom Logic app.
(1) Open Channel: Define Implementations [page 207] This enhancement is mandatory. You have to define an Implementation ID which represents your open channel action. Once activated, you will see your open channel action in the campaign automation user interface (UI), for example Open Channel: Letter Export in the Add Action value help.
(2) Open Channel: Define Parameters for Implementation [page 208] This enhancement is optional and you can use it to add additional parameters for your open channel action (defined in (1) Open Channel: Define Implementations) to the campaign automation UI, such as Description, Date or Priority. Without this implementation your open channel action will offer only the Export Definition as action parameter.
(3) Open Channel: Define Global Settings for Execution [page 209] This enhancement is optional and you can use it for activating the marketing permission check of open channel actions. In addition, you can also check and change, for example, the values of the action parameter or scale the package size that is used during the parallel processing of the campaign execution.
(4) Open Channel: Enhance Payload for Data Transfer [page 211] This enhancement is optional and you can use it to check, change and enhance the data of the target group members that shall be transferred.
(5) Open Channel: Define Template for Outbound Interaction [page 214] This enhancement is optional and you can use it to write interactions for your target group members. This enables you to contact only target group members with a campaign restart whose have not any interaction.
Related Information
Data Flow [page 233]
4.3.3.2.1.1 (1) Open Channel: Define Implementations
Here you find additional information regarding the Define Implementation enhancement for the open channel integration.
This enhancement is mandatory and it should also be the first enhancement that you implement. You must define an Implementation ID which represents your open channel action. Once activated, you will see your open channel action in the campaign automation user interface (UI), for example, Open Channel: Letter Export in the Add Action value help.
Integration Guide Integration Scenarios
PUBLIC
207
In the background, you create with this enhancement the action name and the icon as well as the Implementation ID, which is itself required as the filter value for the enhancements (2) to (5) and in the communication arrangements as the property value.
Changing Parameters
IMPLEMENTATIONS Each entry in the table IMPLEMENTATIONS represents a campaign action. It will appear in the campaign Designer UI in the menu of the Add Action button. An entry contains the following attributes. IMPLEMENTATION is a character of length 20 containing the technical ID of your implementation. This is also the ID of your action. The ID is used as the filter value in the next enhancements of Campaign Open Channel. The ID is mandatory and must start with character Z, such as ZOC_EXPORT. IMPLEMENTATION_NAME is a character of length 40 containing the description of the action. ICON_NAME is a string containing the URL of the icon that will be shown for the action. If ICON_NAME and ICON_URL are both given, then the UI will take the value of the ICON_URL. COMMUNICATION_MEDIUM is a character of length 20 containing the tehnical ID of a communication medium, such as PAPER or PHONE.
If you activate the check for marketing permission by setting CHECK_PERMISSION to abap_true in enhancement (3) Open Channel: Define Global Settings for Execution, then the value of COMMUNICATION_MEDIUM will be taken for the marketing permission checks. To check email-based marketing permissions, the COMMUNICATION_MEDIUM should be EMAIL.
4.3.3.2.1.2 (2) Open Channel: Define Parameters for Implementation
Here you find additional information regarding the Define Parameters for Implementation enhancement for the open channel integration. This enhancement is optional and you can use it to add additional parameters for your open channel action (defined in (1) Open Channel: Define Implementations [page 207]) to the campaign automation UI, such as Description, Date, or Priority. Without this implementation your open channel action will offer only the Export Definition as action parameter.
Note
In case you have implemented this enhancement with additional parameters and these parameters shall also appear in the payload, you must also implement (4) Open Channel: Enhance Payload for Data Transfer [page 211] and add the parameters in the payload. The parameters are also optional.
208
PUBLIC
Integration Guide Integration Scenarios
Changing Parameters
ACTION_PARAMETERS The table contains the parameters for the action you have defined within the coding of enhancement (1) Open Channel: Define Implementations [page 207]. An entry contains the following attributes: ACTION_PARAMETER is a short string of length 255 containing the technical ID of the action. ACTION_PARAMETER_NAME is a character of length 40 containing the description of the parameter. ACTION_PARAMETER_TYPE is a character of length 30 containing the technical type of the parameter. The following values are allowed: if_cuan_mkt_orch_constants=>action_param_type-boolean = 'Edm.Boolean' if_cuan_mkt_orch_constants=>action_param_type-date = 'EDM.Date' if_cuan_mkt_orch_constants=>action_param_type-time = 'Edm.Time' if_cuan_mkt_orch_constants=>action_param_type-string = 'Edm.String'. When your implementation is called, the table already contains the following data:
ACTION_PARAMETER EXPORT_DEFINITION
ACTION_PARAMETER_NAME Export Definition
ACTION_PARAMETER_TYPE Edm.String
You can add additional action parameters. If you remove the values for action parameter EXPORT_DEFINITION, the campaign UI will not offer the export definition as action parameter.
ACTION_PARAMETER_VALUES The table can be empty or it can be filled with one or more allowed values for an action parameter. An entry contains the following attributes: ACTION_PARAMETER is a short string of length 255 containing the technical ID of the action. ACTION_PARAMETER_VALUE is a short string of length 255 containg the technical ID of the parameter value. ACTION_PARAMETER_VALUE_NAME is a short string of length 255 containing the description of the parameter value.
4.3.3.2.1.3 (3) Open Channel: Define Global Settings for Execution
Here you find additional information regarding the Define Global Settings for Execution enhancement for the open channel integration.
This enhancement is optional and you can use it for activating the marketing permission check of open channel actions.
Note
However, keep in mind that the checkbox Ignore Marketing Permission in the campaign automation user interface under Marketing Information skips the marketing permission checks for open channel actions as well.
Integration Guide Integration Scenarios
PUBLIC
209
In addition, you can also check and change, for example, the values of the action parameter or scale the package size that is used during the parallel processing of the campaign execution.
For more information, see Activating Marketing Permissions [page 215].
Changing Parameters
CHECK_PERMISSION is a boolean controlling if marketing permission shall be checked. Set it to value abap_true if you want that the campaign execution checks the marketing permission for every target group member. The check can be executed only if you have set a COMMUNICATION_MEDIUM in the implementation of enhancement (1) Open Channel: Define Implementations [page 207]. if the target group member has the permission, it will be processed in further steps of the execution. If the targte group member has no permission, the campaign execution will create a corresponding interction to log the missing permission.
PACKAGE_SIZE is an integer of length 10 containing the size of a package. The campaign execution transfers the data in parallel processed packages. With this parameter you can define the number of target group members processed in one package. The parameter contains the default value 50 which can be changed in your implementation.
HEADER_ATTRIBUTES The table contains the name and value of header attributes (for example the campaign ID). An entry contains the following attributes:
PARAM_NAME is a short string of length 255 containing the name of a parameter.
PARAM_VALUE is a short string of length 255 containing the value of a parameter. The table HEADER_ATTRIBUTES initially contains the following data which can be used in your implementation:
PARAM_NAME CAMPAIGN EXECUTION_RUN_KEY
SEGMENTATION_OBJECT OC_IMPLEMENTATION_ID
EXPORT_DEFINITION
PARAM_VALUE
<ID of the current campaign with leading zeros; you see the ID in the campaign UI>
<GUID of the execution run; acts as session ID and is a unique ID of every execution of the action, every execution has its own run ID (if action is executed periodically)>
<ID of the segmentation object>
<ID of your implementation, defined in enhancement(1) Open Channel: Define Implementations; for example, ZOC_EXPORT>
<ID of the export definition (if you did not remove it as ac tion parameter in the enhancement(2) Open Channel: Define Parameters for Implementation)>
This table also contains the action parameters you have defined in the enhancement (2) Open Channel: Define Parameters for Implementation [page 208].
210
PUBLIC
Integration Guide Integration Scenarios
ERROR_OCCURED is a character of length 1 indicating if an error occurred and controlling that campaign execution will stop. Set it to abap_true if your implementation wants to indicate an error and wants to stop the complete campaign execution.
ERROR_MESSAGES is a table of messages (each message has 200 characters length) that will appear in the log of the campaign execution.
4.3.3.2.1.4 (4) Open Channel: Enhance Payload for Data Transfer
Here you find additional information regarding the Enhance Payload for Data Transfer enhancement for the open channel integration. This enhancement is optional and you can use it to check, change and enhance the data of the target group members that shall be transferred.
Importing Parameters
HEADER_ATTRIBUTES The table contains the name and value of header attributes (for example the campaign ID). Its content could have been changed by your implementation of enhancement (3) Open Channel: Define Global Settings for Execution [page 209]. An entry contains the following attributes: PARAM_NAME is a short string of length 255 containing the name of a parameter. PARAM_VALUE is a short string of length 255 containing the value of a parameter.
Changing Parameters
TARGET_GROUP_MEMBER_ATTRIBUTES The table contains the meta-data of the transferred data. This is the information of fields which have been defined in the export definition. The export definition will be assigned by the marketing expert, if this user adds your open channel implementation as an action to the campaign. In addition, you can add your own (additional) attributes. In such a case, you should also fill such an attribute with values in table TARGET_GROUP_MEMBER_DATA. An entry contains the following attributes: ATTRIBUTE_ID is a short string of length 255 containing the ID of an attribute defined in the export definition. It has the following format:DA-<ID of Data Source>-<ID of Attribute>. For example, DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-NAME_FIRST First Name Edm.String. The data source ID is shown in the UI of Export Definition. ATTRIBUTE_NAME is a character of length 40 containing the description of an attribute defined in the export definition. The attribute name is shown in the UI of Export Definition. ATTRIBUTE_TYPE is a character of length 30 containing the technical type of an attribute defined in the export definition. Types are EDM types like Edm.Boolean, Edm.Date, Edm.Time, Edm.String etc.
Integration Guide Integration Scenarios
PUBLIC
211
Here is an example of content of table TARGET_GROUP_MEMBER_ATTRIBUTES:
ATTRIBUTE_ID
ATTRIBUTE_NAME
DA-SAP_CE_CON TACT_IA_ERP_CUSTOMERNAME_FIRST
First Name
DA-SAP_CE_CON TACT_IA_ERP_CUSTOMERNAME_LAST
Last Name
DA-SAP_CE_CON TACT_IA_ERP_CUSTOMER-COUN TRY
Country
DA-SAP_CE_CON
City
TACT_IA_ERP_CUSTOMER-CITY
ATTRIBUTE_TYPE Edm.String Edm.String Edm.String Edm.String
TARGET_GROUP_MEMBER_DATA The table contains the data of the target group members that shall be transferred. An entry contains the following attributes:
TG_MEMBER_KEY is a binary GUID containing the technical key of a target group member. Example: 12345678901234567890123456789012.
TG_MEMBER_INTERACTION_CONTACT is a binary GUID containing the technical key of the interaction contact which is member of the target group. Example: 09876543210987654321098765432109; representing the interaction contact: William Smith, Springfield, CA, US.
TG_MEMBER_INTERACTION is a binary GUID containing the technical key of the interaction which is member of the target group. This attribute is only filled if your action is used in a follow-up trigger of campaign automation, such as TriggerClick Through.
ATTRIBUTE_ID is a short string of length 255 containing the technical ID of an attribute defined in the export definition. Example: NAME_FIRST.
ATTRIBUTE_VALUE is a short string of length 255 containing the value of the attribute for the target group member. Example: William. Here is an example of content of table TARGET_GROUP_MEMBER_DATA:
TG_MEMBER_KEY
TG_MEMBER_IN TERACTION_CON TACT
TG_MEMBER_IN TERACTION
ATTRIBUTE_ID
12345678901234567 0987654321098765 890123456789012 4321098765432109
00000000000000 00000000000000 0000
NAME_FIRST
12345678901234567 0987654321098765 890123456789012 4321098765432109
00000000000000 00000000000000 0000
NAME_LAST
ATTRIBUTE_VALUE William
Smith
212
PUBLIC
Integration Guide Integration Scenarios
TG_MEMBER_KEY
TG_MEMBER_IN TERACTION_CON TACT
TG_MEMBER_IN TERACTION
ATTRIBUTE_ID
2345678901234567 8901234567890123
9876543210987654 3210987654321098
00000000000000 00000000000000 0000
NAME_FIRST
2345678901234567 8901234567890123
9876543210987654 3210987654321098
00000000000000 00000000000000 0000
NAME_LAST
ATTRIBUTE_VALUE Adam
Miller
TARGET_GROUP_MEMBER_STATUS The table allows you to control if one or several target group members shall not be transferred. When a target group member shall not be transferred, set an INTERACTION_TYPE and a corresponding FAILURE_REASON in order to remove the target group member from the data transfer. Campaign execution will take given interaction type and failure reason to write a corresponding interaction. All entries of this table having an empty interaction type will be treated as successful and transferred. An entry of table TARGET_GROUP_MEMBER_STATUS contains the following attributes:
TG_MEMBER_KEY is a binary GUID containing the technical key of a target group member.
TG_MEMBER_INTERACTION_CONTACT is a binary GUID containing the technical key of the interaction contact which is member of the target group.
TG_MEMBER_INTERACTION is a binary GUID containing the technical key of the interaction which is member of the target group. This attribute is only filled if your action is used in a follow-up trigger of campaign automation, such as TriggerClick Through.
FAILURE_REASON is a character of length 20 containing the ID of an interaction reason (can be defined in configuration/customizing). It corresponds to the field IA_REASON of the interaction table. Example: NAME_MISSING.
INTERACTION_TYPE is a character of length 20 containing the technical ID of an interaction type. (can be defined in configuration/customizing). It corresponds to the field IA_TYPE of the interaction table. Example: OUTBOUND_FAILED.
OUTBOUND_INTERACTION is a binary GUID containing the key of the interaction that will be written for this target group member. It corresponds to the key field of the interaction table. You can use this unique identifier and transfer it to use it as transactional identifier per target group member. For example: on HCI you can take the OUTBOUND_INTERACTION as identifier for a "preceding document" if you create a new document via HCI.
COMMUNICATION_ID is a short string of length 255 initially containing the GUID of the Interaction Contact. Its value is identical to the value of TG_MEMBER_INTERACTION_CONTACT. It corresponds to the field COMM_ID of the interaction table. If you activate the check for marketing permission by setting CHECK_PERMISSION to abap_true in enhancement (3) Open Channel: Define Global Settings for Execution, set the value of COMMUNICATION_ID to the value to be checked. For example, to check email-based marketing permissions, the COMMUNICATION_ID should contain an email address.
CONTACT_PROJ_KEY is the key of a Contact-to-Account Relationships. If not empty, that means that the target group member is a relationship.
ERROR_OCCURED is a character of length 1 indicating if an error occurred and controlling that campaign execution will stop. If ERROR_OCCURED is set to abap_true, the campaign execution will not write any interactions for this package of target group members. Because campaign execution processes the
Integration Guide Integration Scenarios
PUBLIC
213
amount of target group members in packages, it can happen that other packages are processed without errors. ERROR_MESSAGES is a table of messages (each message has 200 characters length) that will appear in the log of the campaign execution.
4.3.3.2.1.5 (5) Open Channel: Define Template for Outbound Interaction
Here you find additional information regarding the Define Template for Outbound Interaction enhancement for the open channel integration.
This enhancement is optional and you can use it to write interactions for your target group members. This enables you to contact only target group members with a campaign restart who have not had any interaction.
Note
Note that the enhancements (1) Open Channel: Define Implementations [page 207] and (2) Open Channel: Define Parameters for Implementation [page 208] are required to enhance the campaign user interface (UI) with theOpen Channelaction. You can find the technical details and examples in the example coding of the enhancements. If you want to use more than oneImplementation ID,which means you want to have more than one
open channel action, then: you have to define all of them in one implementation of enhancement(1) Open Channel: Define
Implementations. you have to separate implementations for the other enhancements (2-5) and use
theImplementation IDas filter.
Importing Parameters
HEADER_ATTRIBUTES The table contains the name and value of header attributes (for example the campaign ID). Its content could have been changed by your implementation of enhancement (3) Open Channel: Define Global Settings for Execution [page 209]. An entry contains the following attributes: PARAM_NAME is a short string of length 255 containing the name of a parameter. PARAM_VALUE is a short string of length 255 containing the value of a parameter.
Changing Parameters
TEMPLATE The structure is the template for the interactions that will be created. It contains the following attributes: ID_ORIGIN is a character of length 20 containing the technical ID of an origin (can be defined in configuration/customizing). When permission check is active, enter the same origin ID (ID_ORIGIN)
214
PUBLIC
Integration Guide Integration Scenarios
as used for retrieving the communication identifier in the enhancement(4) Open Channel: Enhance Payload for Data Transfer [page 211]. Both interaction attributes INTERACTION_TYPE and COMMUNICATION_MEDIUM are used for interaction creation of all contacts that passed the permission check successfully.
INTERACTION_TYPE is a character of length 20 containing the technical ID of an interaction type (can be defined in configuration/customizing).
COMMUNICATION_MEDIUM is a character of length 20 containing the technical ID of a communication medium (can be defined in configuration/customizing).
4.3.3.2.2 Activating Marketing Permissions
With the following adaptations in the example coding of the enhancements you can activate marketing permissions for your open channel integration.
Note
We recommend that you review the provided examples for each enhancement in the Custom Logic app.
(1) Open Channel: Define Implementations You set the communication medium to run the permission checks. The following example checks emailbased marketing permissions.
Sample Code
APPEND VALUE #( implementation = 'ZOC_MKTG_PRMSSN' implementation_name = 'Check Marketing
Permission (Email)' icon_name = 'email' icon_url = '' " communication_medium = 'EMAIL' ) TO
implementations.
(2) Open Channel: Define Parameters for Implementation No code adaptations necessary.
(3) Open Channel: Define Global Settings for Execution Activate the marketing permission checks.
Sample Code
check_permission = abap_true.
(4) Open Channel: Enhance Payload for Data Transfer Determine the communication identifier for running the permission checks. The communication identifier depends on the communication medium. In the example code, the email address is taken from the contact details under Email as communication identifier.
Note
To see a sample code, please refer to the BAdI documentation in the Custom Logic app.
(5) Open Channel: Define Template for Outbound Interaction
Integration Guide Integration Scenarios
PUBLIC
215
Set the interaction attributes and the origin ID (contact). Enter the same origin ID (ID_ORIGIN) as used for retrieving the communication identifier in the enhancement Enhance Payload for Data Transfer. Both interaction attributes INTERACTION_TYPE and COMMUNICATION_MEDIUM are used for interaction creation of all contacts that passed the permission check successfully.
Sample Code
template-id_origin
= 'EMAIL'.
template-interaction_type
= 'Z_OPEN_CHANNEL'. " Example for a customer
defined interaction type.
template-communication_medium = 'BUSINESS_DOCUMENT'.
Note
The implementation of this enhancement is mandatory for creating any kind of interactions such as contact has been rejected by permission checks, and for processing inbound interactions. But it is optional for the outbound interactions.
Example
The following table shows the written interactions in your system: the first row shows an entry of a refused permission whereas the entries of the second and third row are granted permissions.
ID_ORIGIN EMAIL
EMAIL EMAIL
ID
COMMUNICATION_MEDIUM INTERACTION_TYPE
j.armstrong@example.c BUSINESS_DOCUMENT om
OUTBOUND_CHCK_FAILED
j.miller@example.com BUSINESS_DOCUMENT
Z_OPEN_CHANNEL
m.adams@example.com BUSINESS_DOCUMENT
Z_OPEN_CHANNEL
4.3.3.2.3 Get Deviating Communication ID Based on Origin ID
You can get deviating communication IDs based on origin IDs, doing some coding in enhancements. You need this switch, in case you have activated the enhancement (5) Open Channel: Define Template for Outbound Interaction. If the communication ID does not fit to the origin ID, the system cannot create interactions.
Example
Example 1
You have done an example implementation for the enhancement (4) Open Channel: Enhance Payload for Data Transfer as described in Activating Marketing Permissions [page 215].
In the enhancement (5) Open Channel: Define Template for Outbound Interaction, the templateid_origin is EMAIL.
216
PUBLIC
Integration Guide Integration Scenarios
Example 2 In the enhancement (5) Open Channel: Define Template for Outbound Interaction, the templateid_origin is SAP_C4C_BUPA. For this origin ID you need the following example coding in the enhancement (4) Open Channel: Enhance Payload for Data Transfer:
Sample Code
LOOP AT target_group_member_status ASSIGNING FIELDSYMBOL(<ls_target_group_member_stat>) WHERE tg_member_interaction_contact IS NOT INITIAL.
CL_CUAN_INTERACT_CNTCT_HELPER=>GET_CONTACT_FACETS( EXPORTING IT_CONTACT_KEYS = value #( ( conv #( <ls_target_group_member_stat>tg_member_interaction_contact ) ) )
IMPORTING ET_CONTACT_FACET = data(lt_contact_facet) ).
READ TABLE lt_contact_facet ASSIGNING FIELD-SYMBOL(<ls_contact_facet>) WITH KEY id_origin = 'SAP_C4C_BUPA'.
IF SY-SUBRC EQ 0. <ls_target_group_member_stat>-communication_id = <ls_contact_facet>-id.
ENDIF.
4.3.3.3 Setting Up SAP Business Technology Platform
In the following you find some futher information about an integration example using SAP Business Technology Platform. Keep the following hints and recommendations in mind when you are using SAP BTP: HTTP status code shall be 200 (OK) and 201 (Created) for a successful processing in SAP BTP. Other
HTTP status codes of the group Success will lead to a warning with a lower priority in the application log. That means it is not visible in the execution log of the campaign user interface (UI). Structure of the export definition and implementation of the enhancement (4) Open Channel: Enhance Payload for Data Transfer defines the content of the OData entity TargetGroupMemberAttributeData. The type of property Value of the OData entity TargetGroupMemberAttributeData is always Edm.String and the property EdmTypeId defines the type for formatting property Value. Example for the formatting:
Sample Code
Edm.String: "Value": "Jane", "Value": "0002", "Value": "047D7B8BFC411EE596DA0E15129A2367", Edm.Date: "Value": "2016-09-23", Edm.Guid: "Value": "8cdcd4a8-4768-1ed6-87ca-79a6c5fdf291", Edm.Int16: Value": "-255" Edm.Boolean: "Value": "false", "Value": "true", Edm.Double: "Value": "-2345.66",
Integration Guide Integration Scenarios
PUBLIC
217
Related Information
OData Service Settings for Outbound [page 220]
4.3.3.4 Create Communication Systems and Arrangements
After you have set up your enhancements and the SAP Business Technology Platform you have to create a communication system. With the communication system and the communication arrangements you create your Implementation IDs.
Prerequisite
To set up a communication system and communication arrangement, you require the business catalog role Communication Management (SAP_CORE_BC_COM). You require HTTPS 1.1 for your HTTP requests.
Communication System
1. Choose the Communication Systems app and then New. 2. In the popup enter a system ID, such as Z_HCI_CPG_OPEN_CHANNEL, and system name. You can freely
define a name; but note that the name is used when you create the communication arrangement. Then choose Create. 3. Under Technical Data enter the SAP BTP instance you want to use for the campaign execution as Host Name. Enter only the pure host name without any path and port. Note that Log System ID, Client Name, and Business System are not relevant for the campaign execution. 4. Optionally, you can provide your contact information. 5. Under User for Outbound Communication, choose Add (+) to add a set of access details for the external server. Select SSL Client Certificate as Authentication Method and Default Client Certificate as Certificate Type. To finish choose Create. 6. Choose Save to save the new or edited communication system in an active status.
Communication User
Recommendation
We recommend to use certificates instead of communication users. But in case you are using your own communication users, please take care that the communication user is not longer then 32 characters.
218
PUBLIC
Integration Guide Integration Scenarios
Communication Arrangement
You set up a communication arrangement to enable the campaign execution.
1. Choose Communication Arrangement app and then New. 2. In the New Communication Arrangement dialog use the predefined scenario Marketing - Campaign
Open Channel Integration (SAP_COM_0049) from the value help of the Scenario define an Arrangement Name using the following pattern: SAP_COM_0049_<Implementation_ID>, for example, SAP_COM_0049_ZOC_EXPORT. 3. Under Common Data, select a Communication System from the value help that you have created in the Communication System app. Note that My System is filled automatically. You will need this entry later in your mapping script in SAP BTP. 4. Under Additional Properties, select the Implementation ID of your enhancement from the value help.
Note
Note that -as a mandatory prerequisite- you have to define the Implementation ID in the mandatory enhancement (1) Open Channel: Define Implementations. For more information, see Adapt Enhancements [page 206] and BAdI Details [page 207].
5. Optionally you can set Retry Send Active to True (X) which enables your system to resend the requests in case of fails. For more information, see Retry Sending Using Idempotency [page 234].
6. Under Outbound Communication all required fields are filled automatically from the selected Communication System above.
7. Under Outbound Services, enter the paths for the predefined outbound services using the following pattern: /<your_service>/<your_entity> and the corresponding Service URL for the following steps of the open channel action: Preprocessing (optional) Processing (mandatory) Postprocessing (optional) You can find the required data in the iFlow of the SAP BTP system that you want to connect.
Note
For each outbound service you must set the Service Status to Active at least for the outbound service Processing.
8. Choose Save to save the new or edited communication arrangement in an active status. 9. Now you can download the certificate to your local machine and upload it to use it in SAP BTP. 10. After you have entered the required settings and uploaded the certificate in SAP BTP, you can proof your
connection by choosing Check Connection under Outbound Services.
Related Information
Data Flow [page 233]
Integration Guide Integration Scenarios
PUBLIC
219
4.3.3.5 OData Service Settings for Outbound
Here you can find more information about the settings in the OData service CUAN_CAMPAIGN_OPEN_CHANNEL that are required for the outbound of an open channel integration.
Prerequisite
You have implemented the enhancement (5) Open Channel: Define Template for Outbound Interaction in addition to the mandatory enhancement (1) Open Channel: Define Implementations.
220
PUBLIC
Integration Guide Integration Scenarios
About the OData
Integration Guide Integration Scenarios
PUBLIC
221
From the communication point of view the system for SAP Marketing Cloud acts as a client and the server side implementation of the services is done in external systems using SAP Business Technology Platform as a middleware.
Please keep the following things in mind:
Communication format for requests and responses shall be formatted in JSON only and not in Atom. Data protocol of the communication is (almost) OData V2. Only code and message object of the OData V2 error response is saved, but not any deeper errors of the
OData error document. Each processing step requires an active outbound node in the communication arrangement, customers
could drop processing of the Pre- and Post-Processing steps by leaving the active flag empty, but data transfer for the processing step is mandatory. Cross-Site Request Forgery (CSRF) Protection (SAP BTP) HTTP sender channel supports the cross-site request forgery (CSRF) protection. When CSRF protection is activated, it is usen in the preprocessing, processing, and postprocessing
step. Though the communication with SAP BTP is CSRF protected. We recommend to activate CSRF protection for each integration flow separately. Integration flow must be capable to respond on HTTP HEAD (check communication in communication
arrangements,CSRF Protection) and POST (open channel outbound) requests. Restarting a Campaign
In case the an existing campaign has written outbound interactions and you restart your campaign only those members of the used target group are contacted again for whom no outbound interaction exist.
In case the an existing campaign has not written outbound interactions and you restart your campaign, the campaign sends out emails to all members of the target group again. Therefore we recommend to check your iFlow to prevent duplicates.
OData Entity Types Entity Type
Description
Campaign
An entity representing the campaign business object.
CampaignExecutionRun
An entity representing a campaign execution run. Each send process belongs to one execution run.
CampaignExecutionRunPackage
An entity representing a package that is processed by an ex ecution run.
CampaignTargetGroupMember
An entity representing a target group member.
TargetGroupMemberAttributeDatum
An entity representing the attributes and attributes values of a target group member.
Note that the entity set is named TargetGroupMemberAttributeData.
The names of the entity sets are the plural form of the entities.
222
PUBLIC
Integration Guide Integration Scenarios
Entity Properties
The names of the properties are almost the same names as used for OData services located in the package CUAN_COMMON.
Campaign Properties Property
Type
Description
CampaignId
Name MarketingAreaId SegmentationObject ImplementationId
String
String String String String
An identifier of a campaign key of the entity type.
A name of a campaign.
An identifier of an marketing area.
An identifier of a segmentation object.
An identifier of an customer-specific action implementation.
Campaign Execution Run Properties Property
Type
Description
ExecutionRunKey ProcessingStepCode CampaignId
String String String
An globally unique identifier of an exe cution run key of the entity type.
A coded representation of the process ing step.
An identifier of the campaign business object, used as reference to the parent entity type Campaign.
Campaign Execution Run Package Properties
Property
Type
Description
PackageId Campaign ExecutionStartDateTime
String String String
An identifier of the package key of the entity type.
A complex data type representing the entity type Campign.
A timestamp at which the execution run is started.
Integration Guide Integration Scenarios
PUBLIC
223
Property ExecutionRunKey
Type String
Description
An globally unique identifier of an exe cution run, used as reference to the pa rent entity type CampaignExecutionRun key of the entity type.
Campaign Target Group Member Properties
Property
Type
OutboundId
String
PackageId
String
ExecutionRunKey
String
Description
A globally unique identifier of the out bound interaction key of the entity type.
An identifier of the package, used as reference to the parent entity type CampaignExecutionRunPackage.
An globally unique identifier of an exe cution run, used as reference to the pa rent entity type CampaignExecutionRunPackage.
For more information about the interaction key, see Interactions [page 615].
Campaign Target Group Member Attribute Datum
Property
Type
Description
AttributeId
String
An identifier of an attribute key of the entity type.
Value
String
A value of the attribute.
EdmTypeId
String
An identifier of the OData type.
OutboundId
String
A globally unique identifier of the out bound interaction, used as reference to the parent entity type CampaignTargetGroupMember.
Note
Structure of the export definition and implementation of the enhancement (4) Open Channel: Enhance Payload for Data Transfer defines the content of the OData entity TargetGroupMemberAttributeData.
224
PUBLIC
Integration Guide Integration Scenarios
Preprocessing
One deep create message consisting of the entity sets Campaigns and CampaignExecutionRuns is send. Example Payload:
Sample Code
{ "d": { "CampaignId": "0000381379", "Name": "Open Channel Demo 1", "MarketingAreaId": "CXXGLOBAL", "SegmentationObject": "SAP_CONTACT_ENGAGEMENT_SIN", "ImplementationId": "ZOC_EXPORT", "CampaignExecutionRuns": { "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "ProcessingStepCode": "1", "CampaignId": "0000381379" } }
}
Processing
Multiple deep create messages consisting of the entity sets CampaignExecutionRunPackages, CampaignTargetGroupMembers and TargetGroupMemberAttributeData are send. Each message belongs to one execution package.
Sample Code
{ "d": { "Campaign": { "CampaignId": "0000381379", "Name": "Open Channel Demo 1", "MarketingAreaId": "CXXGLOBAL", "SegmentationObject": "SAP_CONTACT_ENGAGEMENT_SIN", "ImplementationId": "ZOC_EXPORT" }, "PackageId": 1, "ExecutionStartDateTime": "2016-07-07T07:44:40Z", "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "CampaignTargetGroupMembers": [ {"OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10", "PackageId": 1, "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "TargetGroupMemberAttributeData": [ { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-
NAME_FIRST", "Value": "Julie", "EdmTypeId": "Edm.String", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER-
NAME_LAST", "Value": "Armstrong",
Integration Guide Integration Scenarios
PUBLIC
225
CONTACT_KEY",
NAME_FIRST", NAME_LAST", CONTACT_KEY",
"EdmTypeId": "Edm.String", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER"Value": "005056AC4A181ED598D20A84AB8AC6E9", "EdmTypeId": "Edm.Binary", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "OUTBOUND_INTERACTION", "Value": "8CDCD4A847681EE69182D4A1498E1EF5", "EdmTypeId": "Edm.String", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "ZOC_EXPORT_DESCRIPTION", "Value": "Open Channel Demo 1", "EdmTypeId": "Edm.String", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "ZOC_EXPORT_DATE", "Value": "2016-07-07", "EdmTypeId": "Edm.Date", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" }, { "AttributeId": "ZOC_EXPORT_PRIORITY", "Value": "PRIORITY_1", "EdmTypeId": "Edm.String", "OutboundId": "1202654B21C72A50A0D4E5CB35E6D2FBE916EA10" } ] }, {"OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23", "PackageId": 1, "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "TargetGroupMemberAttributeData": [ { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER"Value": "John", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER"Value": "Miller", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER"Value": "005056AC4A181ED598D20A84AB8B06E9", "EdmTypeId": "Edm.Binary", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "OUTBOUND_INTERACTION", "Value": "8CDCD4A847681EE69182D4A1498EDEF5", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "ZOC_EXPORT_DESCRIPTION", "Value": "Open Channel Demo 1", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" }, { "AttributeId": "ZOC_EXPORT_DATE", "Value": "2016-07-07", "EdmTypeId": "Edm.Date", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23"
226
PUBLIC
Integration Guide Integration Scenarios
NAME_FIRST", NAME_LAST", CONTACT_KEY",
] } }
}, { "AttributeId": "ZOC_EXPORT_PRIORITY", "Value": "PRIORITY_1", "EdmTypeId": "Edm.String", "OutboundId": "EA297547B0DBBDF81C308FD14A3757C1420ABB23" } ] }, {"OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF", "PackageId": 1, "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "TargetGroupMemberAttributeData": [ { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER"Value": "Michael", "EdmTypeId": "Edm.String", "OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER"Value": "Adams", "EdmTypeId": "Edm.String", "OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "DA-SAP_CE_CONTACT_IA_ERP_CUSTOMER"Value": "40F2E93065BD1ED598D1DCFDB65F97C0", "EdmTypeId": "Edm.Binary", "OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "OUTBOUND_INTERACTION", "Value": "8CDCD4A847681EE69182D4A1498F3EF5", "EdmTypeId": "Edm.String", "OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "ZOC_EXPORT_DESCRIPTION", "Value": "Open Channel Demo 1", "EdmTypeId": "Edm.String", "OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "ZOC_EXPORT_DATE", "Value": "2016-07-07", "EdmTypeId": "Edm.Date", "OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF" }, { "AttributeId": "ZOC_EXPORT_PRIORITY", "Value": "PRIORITY_1", "EdmTypeId": "Edm.String", "OutboundId": "CA5F1FE120237480E6054B06D61371081AE095DF" } ] }
Postprocessing
One message consisting of the entity set "Campaign Execution Runs" is send. Example Payload:
Integration Guide Integration Scenarios
PUBLIC
227
Sample Code
{ "d": { "ExecutionRunKey": "8CDCD4A847681EE69182D1BBA1C39EF3", "ProcessingStepCode": "3", "CampaignId": "0000381379" }
}
Message Choreography Between the OData and SAP Cloud Platform
Notes regarding the message choreography:
The system for SAP Marketing Cloud saves all error messages in the application log, and also the information with lower severity.
The system for SAP Marketing Cloud does not require responses that are send after creation of entities (status code 201).
The calls are synchronous calls for data transfer between SAP Marketing Cloud and SAP BTP. The receiving system should process the data asynchronously to get a be better error handling and
performance.
Error Handling
In the following you will find useful remarks about the error handling of this OData service:
Errors in the Preprocessing phase stops all further processing steps. Errors during the Processing step marks the entire package as erroneous. Business errors in the SAP BTP mapping shouldn't occur. We recommend to implement all checks in the
enhancements because SAP BTP rejects the entire package. We recommend to set an appropriate HTTP status code and send an OData V2 error document formatted
as JSON in case of errors. Content of code and value are saved in the application log as error and will be visible in the campaign UI
execution log. But note that the content of the inner-error-node is not parsed. Content of all error messages not send as OData V2 error document is also saved in the application log as
it is. Content of the HTTP responses of HTTP status codes of the group Success is not saved in the application
log. All HTTP status code greater or equal than 300 mark the actual execution package as erroneous and stop
the execution of the following packages. All erroneous packages and not processed packages can be restarted again.
OData V2 Error Document Example (Inner Error Node Is Not Shown)
Sample Code
{ "error": { "code": "CUAN_MKT_ORCH_ODATA/001", "message": { "lang": "en",
228
PUBLIC
Integration Guide Integration Scenarios
"value": "Determination of the key failed for campaign ID \"0000032784\" version \"1\"."
} } }
Related Information
Open Channel Integration [page 194]
4.3.3.6 Inbound Service Settings API
Here you can find more information about the settings in the API that are required for the inbound of an open channel integration.
The inbound comprises the creation of interactions (only creation) by using the deep-inserts of the OData service API_MKT_INTERACTION.
Endpoint OData Service Deep Insert: /sap/opu/odata/sap/API_MKT_INTERACTION_SRV/ InteractionsDeepInsert
You need this path to create the service URL to your external system. In addition it tells you how the InteractionsDeepInsert data is structured.
Entity Property of OData Service
Mandatory (must be filled by the OData service)
Copy (data is taken over from the outbound)
Entity InteractionsDeepInsert (This data is part of the interaction API.)
UUID
Child Entity baseInteraction (This data is part of the import data.)
InteractionUUID
X
X
InteractionContactOrig
X
in
Remarks
There will be an error in case the inbound and outbound data of this property is not identical. There will be an error in case the inbound and outbound data of this property is not identical.
Integration Guide Integration Scenarios
PUBLIC
229
Entity Property of OData Service
Mandatory (must be filled by the OData service)
Copy (data is taken over from the outbound)
InteractionContactId
X
CommunicationMedium
X
InteractionType
X
Remarks
There will be an error in case the inbound and outbound data of this property is not identical.
There will be an error in case the inbound and outbound data of this property is not identical.
Note
Keep in mind that the Direction for the interac tion type must be In bound in the self-service configuration app Man age Interaction Content. For more information, see Managing Interac tion Content.
InteractionSourceObjec X tType
InteractionSourceObjec X t
InteractionTimeStampUT X C
SourceSystemType
X
SourceSystemId
Passes always CUAN_CAMPAIGN_OUTBOUND .
Passes property OutboundId of the entity CampaignTargetGroupMem ber.
There will be an error in case the SourceObjectId is empty.
Both properties SourceSystemType and SourceSystemId are op tional, but helpful values and therefore should be passed for describing the origin of the interaction.
230
PUBLIC
Integration Guide Integration Scenarios
Entity Property of OData Service
CampaignID
Mandatory (must be filled by the OData service)
Copy (data is taken over from the outbound)
X
CampaignContent
X
InteractionAdditionalO
X
bject
InteractionIsAnonymous
Child Entity InteractionAdditionalObject (optional, child of Interaction) Child Entity InteractionProduct (optional, child of Interaction) Child Entity InteractionInterest (optional, child of Interaction)
Remarks
There will be an error in case the inbound and outbound data of this property is not identical.
There will be an error in case the inbound and outbound data of this property is not identical.
There will be an error in case the inbound and outbound data of this property is not identical.
There will be an error in case IsAnonymous has the value X.
The inbound processing retrieves all outbound interactions of the campaign by using the SourceObjectId and takes over data (X in column Copy) from the outbound interaction. The OData entity InteractionAdditionalObject is always be copied from the outbound interaction. The following example coding shows the minimum payload required:
Sample Code
{ "UUID": "32575914-a9db-476c-a51a-2b0d4a899b95", "Interactions": [ { "InteractionUUID":
"00000000-0000-0000-0000-000000000000", "InteractionType": "ZOC_CALL_CENTER_INB", "InteractionSourceObjectType":
"CUAN_CAMPAIGN_OUTBOUND", "InteractionSourceObject":
"18D3620CC1DBAEB8E5F97AFB922E84E092F271F0", "InteractionTimeStampUTC":
"2019-06-13T08:55:00" }, { "InteractionUUID":
"00000000-0000-0000-0000-000000000000", "InteractionType": "ZOC_CALL_CENTER_INB", "InteractionSourceObjectType":
"CUAN_CAMPAIGN_OUTBOUND",
Integration Guide Integration Scenarios
PUBLIC
231
"InteractionSourceObject": "0FB6D7D9DCDB8616A4A39D0E931C01DA57B5E48F",
"InteractionTimeStampUTC": "2019-06-13T08:55:00"
} ] }
Interaction Type Configuration
After you have implemented the OData service you need to check whether the interaction types are created properly in the configuration.
1. To do so, open the Manage Your Solution app and choose Configure Your Solution. 2. Then search for the configuration user interface Manage Interaction Content 3. There you must have two entries for each of your interactions: One with the Direction Outbound and one
with the Direction Inbound and with the corresponding interaction channel and communication media assigned. 4. Then you have to implement the enhancement (5) Open Channel: Define Template for Outbound Interaction that is mandatory for inbound interactions.
Sample Code
template-id_origin
= 'SAP_HYBRIS_MKT_IC'.
template-interaction_type
= 'ZOC_CALL_CENTER_OUTB'.
template-communication_medium = 'BUSINESS_DOCUMENT'.
Communication Arrangement
Now you have to setup inbound communication arrangement for integration scenarios Business Data Integration SAP_COM_0206 The path will be filled automatically with /sap/opu/odata/sap/API_MKT_INTERACTION_SRV. You need only to enter the prefix.
232
PUBLIC
Integration Guide Integration Scenarios
4.3.3.7 Data Flow
In the overview below you can see how the different pieces of enhancements, outbound OData and communication arrangement are used during the execution of the campaign action Open Channel:
The campaign execution calls the action Open Channel in 3 steps.
1. Preprocessing In this step the enhancement (3) Open Channel: Define global Settings for Execution is called. The implementation of this enhancement is optional. The filter of the enhancement is the ID of the implementation which was defined in the enhancement (1) Open Channel: Define Implementations. In the enhancement some global settings can be made like the package size or whether marketing permissions shall be checked. Please check the example coding for this enhancement in order to get more details. If the outbound service Preprocess has been activated for the communication arrangement the campaign execution informs the SAP Business Technology Platform by using the OData CUAN_CAMPAIGN_OPEN_CHANNEL. In this call the payload consists of the following OData entities:
Campaigns
CampaignExecutionRuns Note that the outbound service Preprocess is optional.
2. Processing The campaign execution transfers the data in parallel processed packages. In every package the action Open Channel reads the values of the target group members, for example, <Name>, <City>, as defined in the assigned export definition. Now it calls the enhancement (4) Open Channel: Enhance Payload for Data Transfer. The implementation of this enhancement is optional. The filter of the enhancement is the ID of the implementation which was defined in the enhancement (1) Open Channel: Define Implementations. In the enhancement the data that shall be transferred can be checked, such as sort out an entry if <Name> and <City> is empty, and changed and enhanced, for example, calculate a value and append it.
Integration Guide Integration Scenarios
PUBLIC
233
Please check the example coding for this enhancement in order to get more details. If the outbound service Process has been activated for the communication arrangement the campaign execution informs the SAP BTP by the usage of the OData CUAN_CAMPAIGN_OPEN_CHANNEL. In this call the payload consists of the following OData entities:
Campaigns (Campaign is part of the CampaignExecutionRunPackages)
CampaignExecutionRunPackages
CampaignTargetGroupMembers
TargetGroupMemberAttributeData The OData creates one service call with the following entity sets: CampaignExecutionRunPackages, CampaignTargetGroupMembers, and TargetGroupMemberAttributeData Note that the outbound service Process is mandatory. After the OData call has been finished the action calls the enhancement (5) Open Channel: Define Template for Outbound Interaction. The implementation of this enhancement is optional. The filter of the enhancement is the ID of the implementation which was defined in the enhancement (1) Open Channel: Define Implementations. In the enhancement an interaction type can be set which is used in order to write outbound interactions for all target group members which have been transferred successfully. Please check the example coding for this enhancement in order to get more details. Finally the action Open Channel writes interactions. If in the enhancement (4) Open Channel: Enhance Payload for Data Transfer some target group members have been sorted out, corresponding interactions with a reason code will be written. For all other target group members successful outbound interactions will be written in case the enhancement (5) Open Channel: Define Template for Outbound Interaction has been implemented.
3. Postprocessing After all packages have been processed the campaign execution calls the post processing of the action Open Channel. If the outbound service Process has been activated for the communication arrangement the campaign execution informs the SAP BTP using OData CUAN_CAMPAIGN_OPEN_CHANNEL. In this call the payload contains the OData entity CampaignExecutionRuns. Note that the outbound service Post Process is optional.
Related Information
OData Service Settings for Outbound [page 220]
4.3.3.8 Retry Sending Using Idempotency
With idempotency the system repeats a failed request up to five times to an external system using the connecting iFlow.
When the system sends the request to the external system things can go wrong either on the outbound or the inbound side. The system tries to resend up to five times. Only if all tries fail, the system throws an error message on the user interface and in the application log.
After you have set Retry Send Active property to True (X) in the setup of your communication arrangement, you have the following to do: Check your iFlow and enable it to accept several requests with the same key and
234
PUBLIC
Integration Guide Integration Scenarios
take care that the repetition sends always the same answer. This means that the same answer is sent only if the request has been processed properly by SAP Business Technology Platform.
Example
First Attempt: An error happens during send and SAP BTP isn't reached. Second Attempt: An error occurs during receiving in SAP Marketing Cloud. The request has been processed properly and SAP BTP saves the response. Third Attempt: An error occurs during receiving in SAP Marketing Cloud. The request has been already processed properly in the second trial. Though SAP BTP sends again the saved response. Fourth Attempt: An error happens during send and SAP BTP isn't reached. Fifth Attempt: No error, because the request has been already processed properly in the second trial. Though SAP BTP sends again the saved response.
The keys in question are: Preprocessing: ExecutionRunKey (CampaignExecutionRuns) Processing: ExecutionRunKey and PackageID Postprocessing: ExecutionRunKey
Related Information
Create Communication Systems and Arrangements [page 218]
4.3.3.9 Questions and Answers
Q: I implemented the enhancement (5) Open Channel: Define Template for Outbound Interaction, but the interactions are not written. What could be gone wrong?
A: It might be that the ID is wrong, because the ID used for writing the interactions has to be the ID as specified by the ID_ORIGIN. For example, when your enhancement contains the following line, the framework expects ERP customer identifier:
Sample Code
template-id_origin = 'SAP_ERP_CUSTOMER'
Integration Guide Integration Scenarios
PUBLIC
235
You could try to implement the enhancement (4) Open Channel: Enhance Payload for Data Transfer to set the right identifier:
Sample Code
LOOP AT target_group_member_status ASSIGNING FIELDSYMBOL(<ls_target_group_member_stat>).
" Replace the given identifier by ID_ORIGIN specific identifiers CL_CUAN_INTERACT_CNTCT_HELPER=>GET_CONTACT_FACETS( EXPORTING IT_CONTACT_KEYS = value #( ( conv #( <ls_target_group_member_stat>TG_MEMBER_INTERACTION_CONTACT ) ) )
IMPORTING ET_CONTACT_FACET = data(lt_contact_facet) ).
READ TABLE lt_contact_facet ASSIGNING FIELD-SYMBOL(<ls_contact_facet>) WITH KEY id_origin = 'SAP_ERP_CUSTOMER'.
IF SY-SUBRC EQ 0. <ls_target_group_member_stat>-communication_id = <ls_contact_facet>-id.
ENDIF. ENDLOOP.
The code snippet demonstrates only how to replace the identifiers!
Another solution would be the following coding:
Sample Code
LOOP AT target_group_member_status ASSIGNING FIELDSYMBOL(<ls_target_group_member_stat>).
READ TABLE target_group_member_data ASSIGNING FIELDSYMBOL(<ls_target_group_member_data>)
WITH KEY tg_member_key = <ls_target_group_member_stat>tg_member_key.
IF sy-subrc eq 0. ...
ELSE. "// No dynamic content found <ls_target_group_member_stat>-interaction_type = <your interaction type>. <ls_target_group_member_stat>-failure_reason = <your reason>.
ENDIF.
Explanation: Interactions are only written when the enhancement (5) Open Channel: Define Template for Outbound
Interaction has been implemented. If you have NOT implemented the ELSE loop, keep the following in mind:
The business logic sets the interaction types and optionally also the reasons. The process message only contains the node TargetGroupMemberAttributeData It might happen
that the figures under, if dynamic content has been found based on an assigned export definition. If you have implemented the ELSE loop, keep the following in mind:
Interactions are written with the interaction type and reason defined in the coding (ELSE loop) if dynamic content was not found.
In case dynamic content has been found, the business logic sets the interaction types and optionally also the reasons.
The process message only contains the node OutboundId (and subsequent nodes) if dynamic content is found based on an assigned export definition. Only target group members with dynamic content are send.
236
PUBLIC
Integration Guide Integration Scenarios
Q: How to process interactions in the SAP system using the Open Channel integration combined with trigger-based campaigns?
A: With this code snippet you can, for example, access any interaction columns in the open channel integration and process them further by forwarding the information to SAP Business Technology Platform.
Note that you use any further descriptive information for trigger-based campaigns, such as column INTERACTIONCONTENT, in the enhancement (4) Open Channel: Enhance Payload for Data Transfer.
Sample Code
Sample Code
" Define some new fields to the message
APPEND VALUE #( attribute_id = 'TRIGGER_INTERACTION'
attribute_name = 'Trigger Interaction'
attribute_type = 'Edm.String' ) TO
target_group_member_attributes.
APPEND VALUE #( attribute_id = 'INTERACTION_CONTENT'
attribute_name = 'Interaction Content'
attribute_type = 'Edm.String' ) TO
target_group_member_attributes.
...
" Add the content for both fields
APPEND VALUE #( tg_member_key
= <ls_target_group_member_data>-
tg_member_key
tg_member_interaction_contact = <ls_target_group_member_data>-
tg_member_interaction_contact
tg_member_interaction
= <ls_target_group_member_data>-
tg_member_interaction
attribute_id
= 'TRIGGER_INTERACTION'
attribute_value
= <ls_target_group_member_stat>-
tg_member_interaction ) TO target_group_member_data.
IF <ls_target_group_member_stat>-tg_member_interaction IS NOT INITIAL.
SELECT SINGLE interactioncontent FROM i_mkt_interaction INTO
@DATA(lv_content_data) WHERE interaction = @<ls_target_group_member_stat>-
tg_member_interaction.
IF sy-subrc EQ 0.
APPEND VALUE #( tg_member_key
=
<ls_target_group_member_data>-tg_member_key
tg_member_interaction_contact =
<ls_target_group_member_data>-tg_member_interaction_contact
tg_member_interaction
=
<ls_target_group_member_data>-tg_member_interaction
attribute_id
= 'INTERACTION_CONTENT'
attribute_value
= lv_interaction_content )
TO target_group_member_data.
ENDIF.
ENDIF.
Q: What went wrong, when the figures of the campaign performance don't match?
A: Performance for your open channel campaign don't match. A reason for this mismatch could be that the interaction types aren't used in a consistent way.
Integration Guide Integration Scenarios
PUBLIC
237
The Open Channel Interactions tile represents the sum of all outbound and inbound interactions. For example, you have sent out 156 emails and 134 of them are opened. The figures shown are then as follows:
Delivered Messages
156
Opened Messages
134
Open Channel Interactions
290
To get consistent figures for your open channel campaign performance, such as the delivered messages, we recommend using also the interaction types in a consistent way. When you use, for example, the interaction types EMAIL_OUTBOUND and EMAIL_OPENED in your integration, the tiles Delivered Messages and Opened Messages show the correct numbers. This is also valid for tiles with calculated figures, such as Opened Messages in %.
For more information about the calculated figures, see Aggregated Success Data from Interactions [page 882].
Q: Which URL shall I use for SAP BTP integration flow?
A: Each SAP BTP system provides multiple nodes. It is important to select the runtime node and not the tenant management node. The URL is visible in CPI Operations View Manage Integration Content . Then select the integration flow. For more information, see also Runtime in Detail.
Q: Why do not I see any error messages for my wrongly implemented HEAD and GET requests?
A: The open channel functionality sends a http HEAD request followed by an http POST request. It depends on the implementation of the integration flow, whether the HEAD and GET requests are handled properly and doesn't lead to any error messages while running the iFlow.
Q: Can I change the Multiple Value Separator for export definitions with Open Channel usage?
A: No. You may only overwrite the Multiple Value Separator in export definitions using the Export usage type.
Open Channel execution uses the export definition to retrieve the attributes to be sent to the Open Channel interface. The attributes are retrieved from calling the segmentation API as other actions such as Email or SMS. If you use a multiple-value personalization attribute, such as an item of interest, during the execution, the attribute is replaced with its characteristics (such as golf, football, swimming), separated by commas as the Multiple Value Separator.
238
PUBLIC
Integration Guide Integration Scenarios
Related Information
FAQ SAP Marketing Cloud: Campaigns with Open Channel Integration
4.3.3.10 DEPRECATED: Inbound Service Settings Using Import Service
Here you can find more information about the settings in the OData service that are required for the inbound of an open channel integration.
Note
The inbound of the open channel integration has been deprecated as of SAP Marketing Cloud 1908. Please use as of 1908 Inbound Service Settings API [page 229].
The inbound comprises the creation of interactions (only creation) by using the deep-inserts of the OData service CUAN_IMPORT. Endpoint OData Service Deep Insert: /sap/opu/odata/sap/cuan_import_srv/ImportHeaders You need this path to create the service URL to your external system. In addition it tells you how the ImportHeader data is structured.
Entity Property of OData Service
Mandatory (must be filled by the OData service)
Copy (data is taken over from the outbound)
Entity ImportHeader (This data is part of the import data.)
Id
SourceSystemType (op tional)
SourceSystemId (optional)
Child Entity Interaction (This data is part of the import data.)
ContactIdOrigin
X
ContactId
X
Remarks
There will be an error in case the inbound and outbound data of this property is not identical. There will be an error in case the inbound and outbound data of this property is not identical.
Integration Guide Integration Scenarios
PUBLIC
239
Entity Property of OData Service
CommunicationMedium
Mandatory (must be filled by the OData service)
Copy (data is taken over from the outbound)
X
InteractionType
X
Remarks
There will be an error in case the inbound and outbound data of this property is not identical.
Note
Keep in mind that the Direction for the interac tion type must be In bound in the self-service configuration app Man age Interaction Content. For more information, see Managing Interac tion Content.
SourceObjectType
X
Passes always CUAN_CAMPAIGN_OUTBOUND .
SourceObjectId
X
Passes property OutboundId of the entity CampaignTargetGroupMem ber.
There will be an error in case the SourceObjectId is empty.
SourceSystemType SourceSystemId
Both properties SourceSystemType and SourceSystemId are op tional, but helpful values and therefore should be passed for describing the origin of the interaction.
CampaignId
X
There will be an error in case
the inbound and outbound
data of this property is not
identical.
InitiativeId
X
There will be an error in case
the inbound and outbound
data of this property is not
identical.
240
PUBLIC
Integration Guide Integration Scenarios
Entity Property of OData Service
InitiativeVersion
Mandatory (must be filled by the OData service)
Copy (data is taken over from the outbound)
X
MarketingOrchestration
X
Id
AdditionalObjectRefere
X
nces
IsAnonymous
Child Entity Product (optional, child of Interaction) Child Entity Interest (optional, child of Interaction)
Remarks
There will be an error in case the inbound and outbound data of this property is not identical.
There will be an error in case the inbound and outbound data of this property is not identical.
There will be an error in case the inbound and outbound data of this property is not identical.
There will be an error in case IsAnonymous has the value X.
The inbound processing retrieves all outbound interactions of the campaign by using the SourceObjectId and takes over data (X in column Copy) from the outbound interaction. The OData entity InteractionAdditionalObjectReference is always be copied from the outbound interaction. The following example coding shows the minimum payload required:
Sample Code
{ "Id" : "", "SourceSystemType" : "", "SourceSystemId" : "32168", "Interactions" : [ { "InteractionType" : "ZOC_CALL_CENTER_INB", "SourceObjectType" : "CUAN_CAMPAIGN_OUTBOUND", "SourceObjectId" : "CA5F1FE120237480E6054B06D61371081AE095DF", "SourceSystemType" : "", "SourceSystemId" : "32168" } ]
}
Integration Guide Integration Scenarios
PUBLIC
241
Interaction Type Configuration
After you have implemented the OData service you need to check whether the interaction types are created properly in the configuration.
1. To do so, open the Manage Your Solution app and choose Configure Your Solution. 2. Then search for the configuration user interface Manage Interaction Content 3. There you must have two entries for each of your interactions: One with the Direction Outbound and one
with the Direction Inbound and with the corresponding interaction channel and communication media assigned. 4. Then you have to implement the enhancement (5) Open Channel: Define Template for Outbound Interaction that is mandatory for inbound interactions.
Sample Code
template-id_origin
= 'SAP_HYBRIS_MKT_IC'.
template-interaction_type
= 'ZOC_CALL_CENTER_OUTB'.
template-communication_medium = 'BUSINESS_DOCUMENT'.
Communication Arrangement
Now you have to setup inbound communication arrangement for integration scenarios Business Data Integration SAP_COM_0004 The path will be filled automatically with /sap/opu/odata/sap/cuan_import_srv. You need only to enter the prefix.
4.3.4 Mobile, Social, and Digital Channel
With the integrations below you can interact with your customers and communities using social media.
Integration with Google Ads [page 243] Overview of the integration scenario.
Mobile App Integration with Google Firebase [page 244] This section describes how you can integrate SAP Marketing Cloud with Google Firebase for sending push notifications of mobile campaigns to a mobile app.
Social Campaigns Using Facebook and Instagram [page 254] With this integration, you can plan and create campaigns in Facebook, and then use Facebook Ads Manager to push ads to Facebook and Instagram via Facebook. The actual spend and campaign success data from Facebook is pulled into SAP Marketing Cloud for analysis.
Integration with LinkedIn [page 257] Send a target group to LinkedIn to create a Matched Audience for campaign targeting in LinkedIn.
WeChat Integration [page 258]
242
PUBLIC
Integration Guide Integration Scenarios
With this integration, you can synchronize the followers of your WeChat official accounts as well as the follower interactions to SAP Marketing Cloud. What's more, you can create and carry out WeChat campaigns through SAP Marketing Cloud. Analytical reports about WeChat followers and interactions are available as well. LINE Integration [page 258] With this integration, you can synchronize the followers of your LINE accounts as well as the follower interactions to SAP Marketing Cloud. What's more, you can create and carry out LINE campaigns through SAP Marketing Cloud. Analytical reports about LINE followers and interactions are available as well. Integration with Google Campaign Manager [page 259] Overview of the integration scenario. Integration with Adform [page 261] With this integration, you can send target groups that you created in SAP Marketing Cloud as custom audiences to Adform and use them in your Adform campaigns.
4.3.4.1 Integration with Google Ads
Overview of the integration scenario.
The integration with Google Ads allows you to create and assign Google Ads campaigns, then analyze the performance of these campaigns from SAP Marketing Cloud.
Note
You can assign a Google Ads campaign to an SAP Marketing Cloud campaign and generate a customer list in Google Ads. However, the ability to trigger the creation of a Google Ads campaign from SAP Marketing Cloud is deprecated and will be obsolete in an upcoming release.
For more information about the Google Ads Integration with SAP Marketing/SAP Marketing Cloud integration package, see the SAP API Business Hub .
For more information about Google Ads Campaigns, see Google Ads Campaigns.
The following diagram provides an overview of the main components involved in the integration with Google Ads. SAP Cloud Integration is used as a middleware between SAP Marketing Cloud and Google Ads. It is responsible for the account authentication with OAuth 2.0 and any other API communication routing between the two involved systems.
Integration Guide Integration Scenarios
PUBLIC
243
Configuration Settings
To run the integration scenario, make settings in the following systems: Google Ads SAP Cloud Integration SAP Marketing Cloud For a complete description of the configuration settings required for the scenario, see the Integration Guide.
4.3.4.2 Mobile App Integration with Google Firebase
This section describes how you can integrate SAP Marketing Cloud with Google Firebase for sending push notifications of mobile campaigns to a mobile app.
The following graphic illustrates the end-to-end flow for enabling the mobile channel feature. You can create a mobile campaign in the SAP Marketing Cloud system. To this campaign, you can assign an offer or a notification. The offers and notifications are sent as mobile push notifications to either Android or iOS devices. The mobile push notifications are routed via the Google Firebase.
For the mobile device to connect to a SAP Marketing Cloud system, you must use SAP Cloud Integration. SAP Cloud Integration iFlows can be leveraged to connect your mobile app to SAP Marketing Cloud via your mobile app's backend system. SAP recommends not to connect the mobile app directly to the SAP Cloud Integration for security reasons. After you've deployed the iFlows, you must set up the communication scenarios for inbound and outbound communication.
For more information, see Mobile App Integration with SAP Marketing Cloud.
244
PUBLIC
Integration Guide Integration Scenarios
Note
Transport Layer Security (TLS) version 1.2 or higher is required if you're using a servlet instead of the CPI iFlow for inbound communication from the Customer Mobile Backend.
4.3.4.2.1 Configuring Firebase
Procedure
1. Create a google account. 2. Log in to Firebase Console using the google account. 3. Create a new project in Firebase. 4. Follow steps provided in this link to add iOS and Android apps.
Note
For Android devices, SAP uses the data message format provided by Firebase instead of the standard notification message format. User applications have to handle the notifications appropriately. For more
Integration Guide Integration Scenarios
PUBLIC
245
information, see Firebase Cloud Messaging (FCM) and Sample Payload of Mobile Push Notification [page 248].
4.3.4.2.2 Configuring Inbound Communication
Create the communication user, communication system, and communication arrangement required for the inbound communication.
Prerequisites
You have configured Firebase. The following communication scenarios are available in the system:
SAP_COM_0206 (Marketing - Interaction UI Integration ) SAP_COM_0207 (Marketing - Interaction Contact UI Integration ) SAP_COM_0169 (Marketing - Mobile Push Notification Events Integration)
Context
For inbound communication, you first create a communication user, then a communication system and communication arrangement.
Creating the Communication User
To add a communication user, proceed as follows:
1. Log on to SAP Marketing Cloud with a user that has administrator authorizations.
2. From the SAP Fiori launchpad, choose Communication Management 3. Choose New. 4. Enter the user name and password for your communication user. 5. Choose Save.
Communication User .
Note
You can use the communication user information for setting up communication with communication scenarios SAP_COM_0206, SAP_COM_0207, and SAP_COM_0169.
Creating the Communication System
The purpose of this communication system is to bind the communication user that you created earlier with the communication arrangement that you will create later.
246
PUBLIC
Integration Guide Integration Scenarios
To create the communication system, proceed as follows:
1. Open the Communication Systems app. 2. Choose New.
The New Communication System dialog box appears. 3. Enter a system ID and its name. 4. Choose Create. 5. A host is irrelevant to the inbound communication. Enter dummy in the Host Name field to assign a dummy
host. 6. Assign the communication user created earlier to this communication system, as follows:
1. In the User for Inbound Communication section, choose + (Add). The New Inbound Communication User dialog box appears.
2. Select the authentication method as User Name and Password and enter the user created earlier. 7. Save and activate the communication system.
Creating the Communication Arrangement
To create a communication arrangement, proceed as follows:
1. Open the Communication Arrangements app. 2. Choose New. 3. Enter scenario SAP_COM_0206 and an arrangement name. Choose Create. 4. In the Communication System field, enter the communication system created earlier. 5. Save and activate the communication arrangement. 6. Similarly, create communication arrangement for the following scenarios:
SAP_COM_0207 SAP_COM_0169
Next Steps
Configuring Outbound Communication [page 247]
4.3.4.2.3 Configuring Outbound Communication
Create the communication system and communication arrangement required for the outbound communication.
Context
For outbound communication, you first create a communication system and then a communication arrangement. Creating the Communication System Proceed as follows:
Integration Guide Integration Scenarios
PUBLIC
247
1. Log on to SAP Marketing Cloud with a user that has administrator authorizations. 2. From the SAP Fiori launchpad, choose Communication Management Communication Systems . 3. Choose New. 4. Enter an ID and a system name for your communication system. 5. Choose Create. 6. In the Communication System Draft screen, enter the host name as fcm.googleapis.com. 7. Choose the + button in the User for Outbound Communication section. 8. In the New Outbound Communication user dialog, choose the Authentication Method as SSL Client
Certificate. 9. Set the Certificate Type to Default Client Certificate. 10. Choose Create in the popup. 11. Save and activate the communication system.
Creating the Communication Arrangement
Proceed as follows:
1. Log on to SAP Marketing Cloud with a user that has administrator authorizations. 2. From the SAP Fiori launchpad, choose the Communication Arrangements app. 3. Create a new communication arrangement. 4. Choose the scenario SAP_COM_0061 (Marketing - Campaign Mobile Channel Integration). 5. Enter the arrangement name SAP_COM_0061. 6. Choose Create. 7. In the Communication Arrangement screen for Mobile Campaign, choose the communication system that
you created previously.
Note
All the outbound service URLs are populated in the Path field automatically. For Mobile Campaign, please enter the value /fcm/send. Also, ensure the Service URL is https:// fcm.googleapis.com/fcm/send.
8. In the additional properties section, enter an appropriate value for Firebase API Key. 9. Save and activate the communication arrangement.
Note
Ensure that there is only one communication arrangement for scenario SAP_COM_0061 and it is active.
4.3.4.2.4 Sample Payload of Mobile Push Notification
After successful setup, the SAP Marketing Cloud system sends push notification to the mobile device.
248
PUBLIC
Integration Guide Integration Scenarios
The following are sample mobile push notification payloads:
Sample Code
Payload on iOS device { "notification":{ "body":"<NOTIFICATION_BODY_TEXT>", "title":"<NOTIFICATION_TEXT_TITLE>", "icon":"", "click_action":"OPEN_NOTIFICATION" }, "registration_ids":[ "<REGISTRATION_ID>" ], "data":{ "origin":"YMKT", "imageURL":"<http>", "type":"<COUPON/OFFER/TEXT>", "offer":{ "id":"<OFFER_ID>", "name":"<OFFER_NAME>", "coupon":"<COUPON_NAME / ID>", "image":"<http>", "target":"<http>", "couponCode":"SAMPLE-CODE-743", "EANCodeImageURL":"<https://yourdomain.com/url_to_eancode/743>", "QRCodeImageURL":"<https://yourdomain.com/url_to_qrcode/743>", "couponCodeSerialNumber":"<SERIAL-NUMBER-743>" }, "trackingURL":"<https>", "campaignID":"<CAMPAIGN_ID>" }, "mutable_content":"<true/false>", "priority":"<PRIORITY_#>" }
Sample Code
Payload on Android device { "registration_ids":[ "<REGISTRATION_ID>" ], "data":{ "origin":"YMKT", "deeplinkTarget":"<DEEPLINK_TARGET_URL", "imageURL":"<http>", "type":"<COUPON/OFFER/TEXT>", "offer":{ "id":"<OFFER_ID>", "name":"<OFFER_NAME>", "coupon":"<COUPON_NAME / ID>", "image":"<http>", "target":"<http>", "couponCode":"SAMPLE-CODE-743", "EANCodeImageURL":"<https://yourdomain.com/url_to_eancode/743>", "QRCodeImageURL":"<https://yourdomain.com/url_to_qrcode/743>", "couponCodeSerialNumber":"<SERIAL-NUMBER-743>" }, "trackingURL":"<TRACKING_URL>", "campaignID":"<CAMPAIGN_ID>", "body":"<NOTIFICATION_TEXT_BODY>", "title":"<NOTIFICATION_TEXT_TITLE>"
Integration Guide Integration Scenarios
PUBLIC
249
}, "mutable_content":"<true/false>", "priority":"<PRIORITY_>" }
The following table contains the list of available parameters:
Parameter notification body title icon click_action data registration_ids
Plat form iOS
iOS/ An droid iOS/ An droid iOS
iOS
iOS/ An droid iOS/ An droid
Description This parameter specifies the predefined, uservisible key-value pairs of the notification pay load. The notification's body text.
The notification's title.
The notification's icon. The action associated with a user click on the notification. Corresponds to category in the Apple Push Notification (APN) payload. This parameter specifies the custom key-value pairs of the message's payload.
This parameter specifies the client apps (regis tration tokens) receiving the message.
Note
Multicast messaging (sending to more than 1 registration token) is only allowed using HTTP JSON format.
origin deeplinkTarget
iOS/ An droid
An droid
The hardcoded YMKT value reflects the system the notification originated from.
The URL that points to the exact link that is rele vant for the mobile app user. You can direct your mobile app users to the relevant destination us ing this link.
250
PUBLIC
Integration Guide Integration Scenarios
Parameter type offer coupon
Integration Guide Integration Scenarios
Plat form
iOS/ An droid
id
iOS/
An
droid
name
iOS/ An droid
image
iOS/ An droid
target
iOS/ An droid
id
iOS/
An
droid
name
iOS/ An droid
coupon
iOS/ An droid
image
iOS/ An droid
target
iOS/ An droid
couponCode
iOS/ An droid
EANCodeImageURL
iOS/ An droid
QRCodeImageURL
iOS/ An droid
Description You can define one of the following types: offer coupon text You can find their respective associated param eters below. The ID of the offer.
The name of the offer.
The image URL for the offer.
The URL that is navigated to by clicking on the image. The ID of the offer.
The name of the offer.
The SAP Marketing Cloud coupon name and ID.
The image URL for the offer.
The URL that is navigated to by clicking on the image. The coupon code.
The image URL to European Article Numbers (EAN) code. The image URL to Quick Response (QR) code.
PUBLIC
251
Parameter text trackingURL
campaignID mutable_content
Plat form
couponCodeSerial iOS/
Number
An
droid
iOS/ An droid
iOS/ An droid
Description The serial number of the coupon code.
This type simply sends a notification that con tains the body and title on the notification.
You can use the URL to track whether the user has viewed the mobile notification. When the link is opened, the system creates an interaction in the SAP Marketing Cloud system.
Note
To enable this feature, you must configure and deploy the associated integration flow. For more information, see Configure and Deploy the `Create Interaction Using Track ing URL in SAP Marketing Cloud for Mobile Application Integration' Integration Flow.
iOS/ An droid
iOS/ An droid
The ID of an SAP Marketing Cloud campaign.
Currently for iOS 10+ devices only. On iOS, use this parameter to represent mutable-content in the APN's payload. When a notification is sent and mutable_content is set to true, the con tent of the notification can be modified before it's displayed, using a Notification Service app extension.
Note
This parameter is ignored for Android and web.
252
PUBLIC
Integration Guide Integration Scenarios
Parameter priority
Plat form
iOS/ An droid
Description
Sets the priority of the message. Valid values are "normal" and "high." On iOS, these correspond to APN's priorities 5 and 10.
By default, notification messages are sent with high priority, and data messages are sent with normal priority. Normal priority optimizes the client app's battery consumption and should be used unless immediate delivery is required. For messages with normal priority, the app may re ceive the message with unspecified delay.
When a message is sent with high priority, it's sent immediately, and the app can display a no tification.
Note
For Android devices, notifications must be explicitly handled irrespective of whether the app is in the foreground, background, or killed. The app must implement the onMessageReceived() method of the FirebaseMessagingService. For more information, see Receive Messages in an Android App .
4.3.4.2.5 Maintaining the Certificate Trust List
To add the SSL certificate of Firebase to the trust list of SAP Marketing Cloud, perform the following steps:
Procedure
1. Download all of the Google services' certificates issued by any Certificate Authority from this link .
Note
As described on the Google Trust Services FAQ , this list is updated regularly. Applications connecting to Google services should trust all of the Certificate Authorities contained in this list.
2. Open the roots.pem file you've downloaded and segment each certificate (-----BEGIN CERTIFICATE----- / -----END CERTIFICATE-----) into its own separate *.pem file.
3. In SAP Marketing Cloud, choose the Maintain Certificate Trust List app. 4. Choose +. 5. Upload each of the .pem files that you segmented from the original download.
Integration Guide Integration Scenarios
PUBLIC
253
4.3.4.3 Social Campaigns Using Facebook and Instagram
With this integration, you can plan and create campaigns in Facebook, and then use Facebook Ads Manager to push ads to Facebook and Instagram via Facebook. The actual spend and campaign success data from Facebook is pulled into SAP Marketing Cloud for analysis.
Note
Please note that SAP Marketing Cloud doesn't support direct integration with Instagram.
Prerequisites on Facebook
Before you begin, a few things need to be done:
You need your own Facebook app that must be reviewed and released for productive usage by Facebook. When starting the review process, mention that you are using SAP Marketing Cloud. You can only use one Facebook app with this integration.
Note
A prerequisite for the approval is a link to a data privacy policy that is visible to every user of the app. Ensure that your company has such a policy in place.
Look up the application ID (App ID) and client secret (App Secret) in Facebook for later use when configuring the communication arrangement.
To actually do advertising on Facebook you need a Facebook ad account and a user that has been assigned either the Ad Account Admin or Ad Account Advertiser permissions for at least one ad account in Facebook. If you work together with a marketing agency you have to clarify who owns and manages this account.. It is recommended to use Facebook Business Manager. For details refer to the Facebook documentation. In any case your users need marketer permissions on the ad account. You can also work with multiple ad accounts (such as one account per marketing area).
Note
When you create a Facebook campaign in SAP Marketing Cloud, you need to select an ad account from the Advertiser dropdown. This dropdown displays all available Facebook ad accounts, regardless of the type of permission. Only ad accounts with Admin or Advertiser permissions can be used to create campaigns.
When creating a campaign, selecting an ad account with only Analyst permissions will result in an error and you will need to choose a different ad account to continue. When transferring a custom audience, using an ad account with only Analyst permission will result in an error, and you may need to discard that campaign and start again.
Facebook also requires a check for marketing permissions when using their custom audiences, a check that is done by default in SAP Marketing Cloud. In SAP Marketing Cloud, if the user has not given their permission for their data to be used for advertising purposes it can not be used in campaigns created either for Facebook custom audiences or third-parties. However, some countries have implicit opt-in permission. This means that if the user does not specifically forbid SAP Marketing Cloud from using their user for advertising purposes, the user information can be transferred to a custom audience in Facebook.
254
PUBLIC
Integration Guide Integration Scenarios
Your marketing ad account manager and system administrators can assist you with any questions about these prerequisites.
Creating a Facebook App
You must request a Facebook app to access the Facebook APIs. This app must be reviewed by Facebook in order to get full API access. Please keep in mind that Facebook can reject your app, and the review process belongs solely to Facebook. SAP is not involved in this process.
Permissions Needed The following permissions are necessary to integrate your Facebook campaigns with SAP Marketing Cloud. Facebook Login Ads_management (Standard Access)
To gain these permissions, you will need to provide videos to Facebook as part of the app review process. These videos should show how certain features of the Facebook API are used in SAP Marketing Cloud.
You must produce these videos yourself, and they will need to show your Facebook app when demonstrating login steps.
Facebook Login Permission You need to create a video to demonstrate how the Facebook Login is used in SAP Marketing Cloud. To do this, create a Facebook campaign and choose Authenticate to trigger the user authentication flow to Facebook. It is important to show that the login uses your Facebook app.
Ad_management Permission You need to create a video to demonstrate how the Ads_management feature is used in SAP Marketing Cloud. You will need to create another video demonstrating the Facebook campaign creation and authentication process, as well as showing the Performance tab with analytics available. You can use a CSV upload to add data to this campaign if you do not have a real example of a Facebook campaign yet.
Additional Notes For the App Domains of your app, you should use your company-specific tenant which can be copied from your browser.
For the review process, and later for productice usage, you will need to turn on the Live mode of your app. When you switch to Live mode, all of the permissions allowed in Development mode are removed. Until those permissions are restored, some features, such as Facebook login in SAP Marketing Cloud, may not work. After the app is reviewed an approved, these permissions will be restored and the features will work again.
Additional Information For an example about how to create a Facebook app which can be used for SAP Marketing Cloud, see the following blog: How to Create a Facebook App for Campaign and Custom Audience Integration
Note
The SAP blog is not part of the official documentation of SAP Marketing Cloud and some of the information may be outdated.
Integration Guide Integration Scenarios
PUBLIC
255
Setting Up Communication Arrangement
For more information, see Setting Up a Communication Arrangement with Facebook [page 256].
Related Information
Transferring Target Groups to Facebook Custom Audiences Facebook Campaign Performance
4.3.4.3.1 Setting Up a Communication Arrangement with Facebook
In SAP Marketing Cloud, you can create and track the success and actual spend of your Facebook campaigns and create Facebook custom audiences for your target groups to be used in either one-time or periodic campaigns.
You set up a communication system and communication arrangement to enable the Facebook execution, and the requesting of success data from Facebook. Only one communication arrangement is needed.
The authentication with Facebook is done with OAuth authorization code grant flow and there's no setup of a technical user for communication. Instead, an SAP Marketing Cloud user grants SAP Marketing Cloud the permission to manage ads on Facebook on behalf of their personal Facebook user from the SAP Marketing Cloud Campaigns app.
Prerequisites
You need your App ID and App Secret from Facebook.
You also require the business catalog role SAP_BR_ADMINISTRATOR in SAP Marketing Cloud.
You require at least one Facebook user with "Ad Account Admin" or "Ad Account Advertiser" permissions for at least one Facebook ad account. Permissions can be granted, for example, by using the Facebook Business Manager.
Redirect URL
To make your OAuth client known to the OAuth authorization server on Facebook, you need to enter a redirect URL in your Facebook app. Your company-specific tenant can be extracted from your browser and put together as follows: https://<your domain>:443/sap/public/bc/sec/oauth2/client/redirect?sapclient=100.
Note
To enable the redirect URL for SAP Marketing Cloud, configure the following settings in the Facebook App Dashboard:
Add the redirection URL in PRODUCTS Facebook Login Settings Valid OAuth Redirect URIs . Add the company specific tenant (your domain) in Settings Advanced Domain Manager .
256
PUBLIC
Integration Guide Integration Scenarios
Communication System
Create the communication system as follows:
1. In the SAP Fiori launchpad, click Communication Systems. In Communication Systems, click New. 2. In the New Communication System dialog, define the ID for the communication system. Define a System
Name. You can freely define a name; note that the name is used when you create the communication arrangement. Click Create. 3. Under Technical Data Host Name , specify the host system for Facebook, which is facebook.com.
Note
Log System ID, Client Name, and Business System aren't relevant for Facebook campaign execution.
4. Optionally, you can provide your Contact Information for the communication system you're defining. 5. Under User for Outbound Communication, click + to add a set of access details for the Facebook server.
You use the Authentication Method OAuth 2.0 and provide the App ID and App Secret that you've obtained before. Click Create. 6. Save the communication system.
Maintain Communication Arrangement for Facebook
1. From the launchpad, choose Communication Management Communication Arrangements 2. From the Communication Arrangement screen, choose New and enter the following information in the New
Communication Arrangement dialog: Communication Scenario ID: SAP_COM_0031 (Marketing - Campaign Execution Facebook Integration) Communication Arrangement Name: Enter a name of your choice, for example "Facebook" 3. Select the communication system you created under Communication System. 4. Make sure that the OAuth 2.0 Client ID matches the ID you wish to use for your Facebook campaign. 5. Enter a / or other data of your choice in the Path field. 6. Save your communication arrangement.
Related Information
Social Campaigns Using Facebook and Instagram [page 254]
4.3.4.4 Integration with LinkedIn
Send a target group to LinkedIn to create a Matched Audience for campaign targeting in LinkedIn.
The integration with LinkedIn allows you to send a target group from SAP Marketing Cloud to LinkedIn to generate a Matched Audience. The frequency of the campaign defines how often the target group is resent to LinkedIn to refresh the Matched Audience. You send the target group to a specific ad account in LinkedIn, which the campaign user must be authorized to access. The campaign user must be authenticated by LinkedIn with a valid OAuth token before they can start the campaign and send the target group.
If the minimum size of 300 matched members is met, then a Matched Audience is created. The audience size is fetched from LinkedIn and displayed in the LinkedIn Audience Transfer action in SAP Marketing Cloud.
Integration Guide Integration Scenarios
PUBLIC
257
For more information about Matched Audiences in LinkedIn, see LinkedIn Matched Audiences - Overview . Prerequisites Complete the following configuration activities once you have determined your privacy policies and communicated them to your customers: Assign the origin of contact EMAIL to the communication medium LinkedIn (LNKD) in the configuration
activity Assign Contact ID Origin to Communication Media. For more information, see Assign Contact ID Origin to Communication Media. Set your permissing handling per country and for communication medium LNKD in the configuration activity Define Marketing Permission Check. For more information, see Define Marketing Permission Check. Permissions for Contacts
Remember
You're responsible for your privacy policies regarding the transfer of contact data to third parties.
Related Information
LinkedIn Audience Transfer
4.3.4.5 WeChat Integration
With this integration, you can synchronize the followers of your WeChat official accounts as well as the follower interactions to SAP Marketing Cloud. What's more, you can create and carry out WeChat campaigns through SAP Marketing Cloud. Analytical reports about WeChat followers and interactions are available as well. For more information, see WeChat Integration [page 65].
4.3.4.6 LINE Integration
With this integration, you can synchronize the followers of your LINE accounts as well as the follower interactions to SAP Marketing Cloud. What's more, you can create and carry out LINE campaigns through SAP Marketing Cloud. Analytical reports about LINE followers and interactions are available as well. For more information, see LINE Integration [page 77].
258
PUBLIC
Integration Guide Integration Scenarios
4.3.4.7 Integration with Google Campaign Manager
Overview of the integration scenario.
This integration allows you to transfer performance data from Google Campaign Manager to SAP Marketing Cloud.
The following diagram provides an overview of the main components involved in the system integration of SAP Marketing Cloud with Google Campaign Manager. SAP Cloud Integration is used as a middleware between SAP Marketing Cloud and Google Campaign Manager. It is responsible for the account authentication with OAuth 2.0 and any other API communication routing between the two involved systems.
Integration Guide Integration Scenarios
PUBLIC
259
Configuration
To run the integration scenario, you make settings in the following systems: Google Campaign Manager
260
PUBLIC
Integration Guide Integration Scenarios
SAP Cloud Integration SAP Marketing Cloud
Related Links
For a complete description of the configuration settings required for the scenario, see the Integration Guide. For more information about the Google Campaign Manager Integration with SAP Marketing Cloud/SAP Marketing integration package, see Google Campaign Manager Integration with SAP Marketing Cloud/SAP Marketing . For more information about Google Campaign Manager campaigns, see Google Campaign Manager Campaigns.
4.3.4.8 Integration with Adform
With this integration, you can send target groups that you created in SAP Marketing Cloud as custom audiences to Adform and use them in your Adform campaigns.
Prerequisites
Before you can use this integration, you must do the following: Set up your data provider account on the Adform platform.
Only one data provider account should be assigned to your Adform platform. You choose the data provider account in the ADFORM AUDIENCES node in the Campaigns app. Create categories in your data provider account. Download the Adform server certificate (api.adform.com).
Configuration
To use this integration you must set up the communication system and communication arrangement in your SAP Marketing Cloud system and import the Adform server certificate into SAP Marketing Cloud.
Related Information
Configuring SAP Marketing Cloud [page 262] Import the Certificate [page 264] Adform Audiences Campaign
Integration Guide Integration Scenarios
PUBLIC
261
4.3.4.8.1 Configuring SAP Marketing Cloud
To establish communication with the OData service, you perform procedures in SAP Marketing Cloud. The overall process is as follows:
1. Set Up the Communication System [page 262] Set up a communication system for the Adform integration scenario.
2. Set Up the Communication Arrangement [page 263] After setting up the communication system, set up the communication arrangement for the Adform integration scenario.
4.3.4.8.1.1 Set Up the Communication System
Set up a communication system for the Adform integration scenario.
Prerequisites
To set up a communication system and communication arrangement, you require the Communication Management (SAP_CORE_BC_COM) business catalog role.
Procedure
1. Log on to your SAP Marketing Cloud system with a user that has administrator authorizations. 2. From the SAP Fiori launchpad, choose the Communication Systems app. 3. Choose New. 4. Enter a system ID and name for your communication system. 5. Choose Create. 6. On the Communication System page, enter the following:
a. Under Technical Data, enter dummy as the Host Name to assign a dummy host. This is a dummy communication system as its only purpose is to bind the communication user that you previously created to the communication arrangement that you will create in the next step.
b. Under User for Outbound Communication, choose (+). c. For Authentication Method, select OAuth 2.0. d. Enter your client ID and client secret you received from Adform. 7. Save your changes and exit the app.
Task overview: Configuring SAP Marketing Cloud [page 262]
262
PUBLIC
Integration Guide Integration Scenarios
Next task: Set Up the Communication Arrangement [page 263]
4.3.4.8.1.2 Set Up the Communication Arrangement
After setting up the communication system, set up the communication arrangement for the Adform integration scenario.
Prerequisites
To set up a communication system and communication arrangement, you require the Communication Management (SAP_CORE_BC_COM) business catalog role.
Procedure
1. Log on to your SAP Marketing Cloud system with a user that has administrator authorizations. 2. From the SAP Fiori launchpad, choose the Communication Arrangements app. 3. Create a new communication arrangement. 4. Select scenario SAP_COM_0496. 5. Choose Create. 6. In the Communication Arrangements screen, do the following:
a. Under Common Data, choose the communication system that you created previously. b. Under User for Outbound Communication, choose the user name you assigned to the communication
system. 7. Save your changes and exit the app.
Task overview: Configuring SAP Marketing Cloud [page 262]
Previous task: Set Up the Communication System [page 262]
Integration Guide Integration Scenarios
PUBLIC
263
4.3.4.8.2 Import the Certificate
Import the server certificate for Adform into SAP Marketing Cloud.
Prerequisites
You already downloaded the certificate from Adform.
Procedure
1. Log into the SAP Fiori launchpad with a business role that contains the security (SAP_CORE_BC_SEC) business catalog.
2. Open the Maintain Certificate Trust List app. 3. Use (+) to add a certificate . 4. Upload the certificate.
4.3.5 Setting Up Captcha Configuration for Forms
Use captcha configuration to enhance the security of your forms and decrease vulnerability to malicious attacks by bots that send fraudulent contact data into your system.
SAP Marketing Cloud integrates with Google reCAPTCHA v3 and provides a Captcha element in the Form editor allowing you to set up captchas for your forms, analyze form traffic, and take action to ensure your forms are secure.
To set up the communication between your SAP Marketing Cloud system and Google reCAPTCHA v3, you do the following: Download the GlobalSign certificate from Google Admin Console. Upload the GlobalSign certificate to the Maintain Certificate Trust List app.
Note
If the GlobalSign certificate is already listed in the Maintain Certificate Trust List, you can skip the download and upload steps.
Register your domain on the Google Admin Console for Google reCAPTCHA v3. Create a communication system. Create a communication arrangement using the Marketing - Captcha Integration (SAP_COM_0584)
communication scenario. The scenario is used to store the site and secret keys that are generated when you register your domain.
264
PUBLIC
Integration Guide Integration Scenarios
Download the GlobalSign Certificate
You must download the GlobalSign Root CA-R2 certificate to ensure that the Captcha communication works as required. You perform the following steps: 1. Open the Google Admin Console in a browser window.
Note
The steps for downloading the certificate will differ depending on the device and browser you use. For example, the certificate can be copied either directly to your desktop or you may encounter a step-bystep wizard to support you with the download.
2. Click the small lock icon in the address bar. This is located either to the left or right of the URL. 3. Select the GlobalSign Root CA-R2 certificate and drag and drop it to your local computer or follow the
steps to copy the file to your local computer. Again, how you perform this step depends on the device and browser you are using.
Upload the GlobalSign Certificate
To upload the GlobalSign Root CA-R2 certificate, you perform the following steps: 1. Open the Maintain Certificate Trust List app. 2. Choose +. 3. Browse your computer for the certificate file you saved by following the steps in the previous section. 4. Select the file and choose Upload.
Register Your Domain
Prerequisites To register your domain for Google reCAPTCHA v3, you must have your own Google account. You register your domain with Google reCAPTCHA v3 as follows: 1. Log in to your Google account. 2. Open the Google Admin Console: https://www.google.com/recaptcha/admin/create 3. Enter a label for your form or landing page where the form is embedded. Use a label that's easy to
remember. 4. Select reCAPTCHA v3 for the type. 5. Add the domain of your form or landing page where the form is embedded.
Note
The domain must be that of the published form or landing page.
6. Add the domain of your SAP Marketing Cloud system, for example my1234567-api.s4hana.ondemand.com. This ensures that your form captchas will work correctly when opening your form in test mode.
Integration Guide Integration Scenarios
PUBLIC
265
7. Select the checkbox to accept the reCAPTCHA terms of service and choose Submit. A Site Key and a Secret Key are created and saved in the Admin console settings. These keys are necessary when creating the communication arrangement. The site key is used to call the reCAPTCHA service on your form. The secret key authorizes communication between your SAP Marketing Cloud system and the reCAPTCHA server to verify the user's response.
Create a Communication System
You create the communication system as follows:
1. In the SAP Fiori launchpad, open the Communication Management group. 2. Open the Communication Systems app and choose New. 3. In the New Communication System dialog, enter names for the system ID and system name. For example,
GOOGLE_CAPTCHA_v3. You can freely define a system name. It is used when you create the communication arrangement. 4. Choose Create. 5. In the Technical Data section, enter www.google.com for the host name. 6. In the Users for Outbound Communication section, choose the plus icon to define the outbound authentication method. 7. Select None for the authentication method and choose Create. 8. Choose Save.
Create a Communication Arrangement
You create the communication arrangement as follows:
1. Open the Communication Arrangements app and choose New. 2. In the New Communication Arrangement dialog, search for the Marketing - Captcha Integration
(SAP_COM_0584) communication scenario. 3. Enter a name for the communication arrangement. 4. Choose Create. 5. In the Communication System field, open the value help to search for and select the communication
system you created. 6. In the Additional Properties section, verify that the correct property value is set for the type. The default is
set at 10, which is Google reCAPTCHA v3. 7. Open the settings of the Google Admin Console and copy and paste the site and secret keys into the
communication arrangement. 8. Choose Save.
You have set up the captcha configuration for your forms. When you create a new form and add a Captcha element, you can select the configured captchas in the Captcha Configuration list. For more information, see Enhancing Form Security.
266
PUBLIC
Integration Guide Integration Scenarios
4.4 Application-Enabling Integrations
The section provides information about integration options that enable specific applications of SAP Marketing Cloud, such as geospatial segmentation, or analyzing marketing data based on the analytic capabilities of SAP BusinessObjects Cloud.
Integrating Custom Themes [page 267] Set a custom company theme in the SAP Fiori launchpad.
Integration with SAP Analytics Cloud (1SO) [page 268] Set up the Integration of SAP Analytics Cloud (1SO) with SAP Marketing Cloud
Content Studio Integrations [page 304] Lists the Content Studio integrations with SAP Marketing Cloud
Enabling Geospatial Segmentation with here.com [page 317] Use the integration option to translate addresses to geo-coordinates and reverse, and to enable geospatial analysis for segmentation based on the connected maps.
Integration with Baidu Maps for Geospatial Segmentation (Deprecated) [page 318] The integration of Baidu Maps into Segmentation enables you to segment contacts in China by geographic location in a visualized way.
SAP Jam Integration for Collaboration [page 320] The integration enables using SAP Jam in SAP Marketing Cloud to facilitate the collaboration when planning and executing marketing campaigns.
Verifying Email Addresses Using a Partner Solution [page 321] Accurate email addresses are vital for email marketing campaigns. To verify email addresses you can use partner services, such as Neverbounce or others.
Integration with an External Coupon Service System [page 321] Integrate SAP Marketing Cloud with an external coupon service system. To use this integration, you must use the communication arrangement: SAP_COM_0286.
Partner Extension: Integrate with Digital Market Intelligence [page 330] With the partner integration of SimilarWeb, you can see the web no app traffic of your competitors for each channel, such as direct, email, social. These insights help you to make better strategic decisions with regard to your own campaigns. Note that the extension is an offering from a partner of SAP.
Marketing Events [page 330]
4.4.1 Integrating Custom Themes
Set a custom company theme in the SAP Fiori launchpad. The Scope Item: UI Theme Designer (2TV) enables you to set a custom company theme for the SAP Fiori launchpad in the SAP Marketing Cloud. For example, a company color scheme and a company logo. To integrate a custom theme in SAP Marketing Cloud, do the following: 1. Create a custom theme on your SAP Business Technology Platform (Neo) account. 2. Set up a communication arrangement in SAP Marketing Cloud that uses the SAP_COM_0086
communication scenario.
Integration Guide Integration Scenarios
PUBLIC
267
3. Set as an SAP Marketing Cloud default theme. For more information, see Setting a Custom Theme for the SAP Fiori Launchpad and Scope Item: UI Theme Designer (2TV) .
Note
The Scope Item: UI Theme Designer (2TV) is excluded from default activation. To activate the scope item, submit a request to BCP Ticket Component: XX-S4C-OPR-SRV. The activation of this scope item requires an additional SAP Business Technology Platform (Neo) account.
4.4.2 Integration with SAP Analytics Cloud (1SO)
Set up the Integration of SAP Analytics Cloud (1SO) with SAP Marketing Cloud
Note
This section is not relevant for SAP Analytics Cloud, embedded edition. You check in the Set Up Your Marketing Solution application to see if you have the embedded edition. For more information, see Setup of SAP Analytics Cloud, Embedded Edition/SAP Analytics Cloud.
Use
Integrating SAP Marketing Cloud with SAP Analytics Cloud allows you to make full use of the analytic capabilities of SAP Analytics Cloud to explore marketing data. You can, for example, build analytics stories based on CDS views and use them in the Analytics and Reporting Gallery. The Live Data Connection allows users to run SAP Marketing Cloud CDS query views without data replication. The analytical query is delivered as CDS content and is exposed via the analytical engine and the InA protocol via the REST services under /sap/bw/ina/ to SAP Analytics Cloud.
268
PUBLIC
Integration Guide Integration Scenarios
Prerequisites
To integrate the SAP Marketing Cloud data into SAP Analytics Cloud, ensure the following: You have the necessary access data (URL, user, and password, authorizations) for the SAP Cloud Identity
Provider (IdP) system and the SAP Analytics Cloud system. Both applications must use the same SAP Cloud Identity Provider (IdP). The IdP user is authorized for both applications.
More Information
SAP Analytics Cloud Complete the following steps to integrate SAP Analytics Cloud with SAP Marketing Cloud.
1. Connecting SAP Analytics Cloud to SAP Marketing Cloud Identity Provider [page 270] Connect your SAP Analytics Cloud to SAP Marketing Cloud Identity Provider.
2. Create the Live Data Connection to SAP Marketing Cloud [page 272]
Integration Guide Integration Scenarios
PUBLIC
269
Creating the live data connection allows you to run SAP Marketing Cloud CDS query views without data replication. 3. Renewal of Signing Certificates [page 300] Renew signing certificates. 4. Selecting SAP Marketing Cloud Content Packages to Add to Your Tenant [page 301] Choose and then import SAP Marketing Cloud content to your SAP Analytics Cloud system to improve your analytics scenarios.
4.4.2.1 Connecting SAP Analytics Cloud to SAP Marketing Cloud Identity Provider
Connect your SAP Analytics Cloud to SAP Marketing Cloud Identity Provider.
Prerequisites
1. You need to have the role System Owner in SAP Analytics Cloud to set up the SSO integration. 2. If you have previously set up an SAML SSO live connection with the check box Identity Provider will also be
used for Live Data connections with SAML Single Sign On to S/4HANA Cloud Edition enabled, then you need do the following steps first: 1. In the SAP Analytics Cloud menu, select System Administration and switch to the Security tab.
Edit the settings. 2. In the section Authentication Method, change the setting from SAML Single Sign-On (SSO) to SAP
Cloud Identity (Default), and save the settings. Continue with the following steps.
Caution
It is important to base the SAML assertion on Login name, in order to ensure a smooth integration. Support for other configurations is not guaranteed.
Procedure
1. In your SAP Cloud Identity Services - Identity Authentication system, open the administration console. Go to Application & Resources Tenant Settings SAML 2.0 Configuration and download the identity provider's metadata file.
2. Start the SAP Analytics Cloud application in a separate window as System Owner. 3. From the menu, select System Administration and switch to the Security tab. Edit the settings. 4. In the section Authentication Method, change the setting to SAML Single Sign-On (SSO). 5. Go to the section SAML Single Sign-On (SSO) Configuration. In Step 1: Download Service Provider
metadata, download the metadata.xml file.
270
PUBLIC
Integration Guide Integration Scenarios
The downloaded file initially has the same name as the metadata file of the identity provider. Make sure that you rename the metadata file. 6. In Step 2: Upload Identity Provider metadata, upload the metadata.xml file that you've previously downloaded from SAP Marketing Cloud identity provider (not the file from SAP Analytics Cloud ). 7. In Step 3: Choose a user attribute to map to your identity provider, select Custom SAML User Mapping.
Caution
Custom SAML User Mapping with the SAML assertion based on Login name is the only out of the box supported configuration for this step. Support for other configurations is not guaranteed.
8. Return to the SAP Cloud Identity Services - Identity Authentication system and open Application & Resources Applications . Add a new application for SAP Analytics Cloud.
9. On the Trust tab, select SAML 2.0 Configuration. In the section Define from Metadata, upload the metadata.xml file that you downloaded from earlier.
10. Return to the Trust tab. Choose the entry Name ID Attribute and change the setting to Login Name. Save your settings.
11. In the SAP Cloud Identity Services - Identity Authentication system, under Users & Authorizations User Management , search for the user that you want to map to your existing account. Note the login name of the user for the SAP Marketing Cloud system.
12. In the SAP Analytics Cloud system, you can now verify that all settings are correct. In the section SAML Single Sign-On (SSO) Configuration, in Step 4: Verify your account with the identity provider, provide the login name of your SAP Marketing Cloud user in the Login Credential (Custom SAML User Mapping) and click Verify Account.
13. From the upcoming popup, copy the URL.
Note
Use a private session to open the URL, such as incognito mode in the Google Chrome browser. Doing so ensures that when you log on to SAP Analytics Cloud, you're prompted to log on and don't reuse an existing browser session. You will log in with the SAML_VERIFY user.
14. In the SAP Analytics Cloud system, return to the Security settings page, where you now should get a message that your account has been verified. Save your settings.
15. In the popup, click Convert and confirm the message.
After some minutes, your tenant is connected to the SAP Marketing Cloud identity provider. The SAML user mapping for your user that carried out the conversion was already changed. 16. Ensure that you adjust the SAML user mappings of all existing users manually to the new identity provider. First, ensure that you created all users in the identity provider.
17. Navigate to Security Users . In the column SAML User Mapping, enter the corresponding login name of the SAP Marketing Cloud system for all other users. Save the changes.
Task overview: Integration with SAP Analytics Cloud (1SO) [page 268]
Next: Create the Live Data Connection to SAP Marketing Cloud [page 272]
Integration Guide Integration Scenarios
PUBLIC
271
4.4.2.2 Create the Live Data Connection to SAP Marketing Cloud
Creating the live data connection allows you to run SAP Marketing Cloud CDS query views without data replication. Before you create the live data connection to SAP Marketing Cloud, you must identify the environment where SAP Analytics Cloud is hosted. The following environments are available: SAC Neo Tenant [page 272] SAP Cloud Foundry Tenant [page 285] If the tenant id is visible as a part of the SAP Analytics Cloud URL, then SAP Analytics Cloud is hosted on the SAC Neo environment. For example, https://xxx.sapanalytics.cloud/sap/fpa/ui/tenants/<tenant ID>/ app.html If the tenant id is not visible as a part of the SAP Analytics Cloud URL, then SAP Analytics Cloud is hosted on the SAP Cloud Foundry environment. For example, https://xxx.sapanalytics.cloud/sap/fpa/ui/tenants/ app.html Once you identify the environment, ensure that you complete the tasks in the sequence they're listed to create the live data connection to SAP Marketing Cloud.
Parent topic: Integration with SAP Analytics Cloud (1SO) [page 268]
Previous task: Connecting SAP Analytics Cloud to SAP Marketing Cloud Identity Provider [page 270]
Next: Renewal of Signing Certificates [page 300]
4.4.2.2.1 SAC Neo Tenant
Identify if the SAC Neo tenant is the environment where SAP Analytics Cloud is hosted.
If the tenant id is visible as a part of the SAP Analytics Cloud URL, then SAP Analytics Cloud is hosted on the SAC Neo environment. For example, https://xxx.sapanalytics.cloud/sap/fpa/ui/tenants/<tenant ID>/ app.html
Now that you've identified the environment where SAP Analytics Cloud is hosted, to create the live data connection with the SAC Neo tenant, complete the tasks in the following sequence:
1. Adding a New OAuth Client [page 273] 2. Adding a New Live Data Connection [page 274] 3. Setting Up a Communication System [page 275] 4. Setting Up a Communication Arrangement [page 277] 5. Completing the Setup of the Live Data Connection [page 280] 6. Setting Up the Outbound Connections from SAP Marketing Cloud to SAP Analytics Cloud [page 282] 7. Adding SAP Marketing Cloud as a Trusted Origin with SAP Analytics Cloud [page 283]
Allow the use of and then access the analytics stories in SAP Marketing Cloud.
272
PUBLIC
Integration Guide Integration Scenarios
4.4.2.2.1.1 Adding a New OAuth Client
Prerequisites
For the steps in the SAP Analytics Cloud system, the Admin or System Owner role is required.
Procedure
1. In the SAP Analytics Cloud system, navigate to System Administration App Integration OAuth Clients and note down the authorization URL and the token URL.
2. Under Configured Clients, add a new OAuth Client with the following properties: 1. Name, for example "SAP HMC System" 2. OAuth Client ID, for example "my300xxx". 3. Purpose: "Interactive Usage". 4. Security Authorization Grant Client Credentials 5. Security Secret chosen by you (like a password). Don't specify a lifetime for the secret. 6. Token Details Token Lifetime 60 minutes (suggested value).
3. Press Add.
Integration Guide Integration Scenarios
PUBLIC
273
Task overview: SAC Neo Tenant [page 272] Next task: Adding a New Live Data Connection [page 274]
4.4.2.2.1.2 Adding a New Live Data Connection
Procedure
1. In the SAP Analytics Cloud system, navigate to Connection and press the Plus (+) icon to add a new connection.
2. Select Live Data Connection SAP S/4HANA . 3. In the dialog New S/4HANA Live Connection, enter a Name and Description.
In order to use SAP Marketing Cloud sample content, the name has to be SAPMKTNW. 4. Select Connection Type SAP S/4HANA Cloud. 5. Under Host, enter the host name of the SAP Marketing Cloud tenant. For example, my300xxx-
api.s4hana.ondemand.com. 6. Note down the provider name that is displayed under Authentication Method OAuth 2 SAML. Bearer
Assertion and download the signing certificate.
274
PUBLIC
Integration Guide Integration Scenarios
Note
No need to save at this point. We make the required configurations in SAP Marketing Cloud and return to this setup for saving. Task overview: SAC Neo Tenant [page 272] Previous task: Adding a New OAuth Client [page 273] Next task: Setting Up a Communication System [page 275]
4.4.2.2.1.3 Setting Up a Communication System
Prerequisites
For the steps in the SAP Marketing Cloud system, the Administrator role is required.
Procedure
1. Open SAP Marketing Cloud in a new browser window. In the app Communication Systems, click New to create a new communication system.
2. Under Technical Data General Host Name , enter the host name of the SAP Analytics Cloud tenant.
3. Under Technical Data OAuth 2.0 Settings , enter the authorization endpoint oauthasservices<SAP CP account ID>.int.sap.hana.ondemand.com/oauth2/api/v1/authorize and token
Integration Guide Integration Scenarios
PUBLIC
275
endpoint oauthasservices-<SAP CP account ID>.int.sap.hana.ondemand.com/ oauth2/api/vi/token when you added the new OAuth client. For more information, see Adding a New OAuth Client [page 273].
Note
Enter these endpoints without the https:// prefix.
4. Under OAuth 2.0 Identity Provider, select Enabled. Enter the provider name and upload the signing certificate that you obtained in Adding a New Live Data Connection [page 274].
5. Create a user for Inbound Communication with the Authentication Method User Name and Password and note down the user name and password.
6. To create a user for Outbound Communication, enter the following details: 1. In Authentication Method, choose OAuth 2.0.
276
PUBLIC
Integration Guide Integration Scenarios
2. Add the OAuth 2.0 client ID and the client secret that you defined in Adding a New OAuth Client [page 273].
7. Save the communication system. Task overview: SAC Neo Tenant [page 272] Previous task: Adding a New Live Data Connection [page 274] Next task: Setting Up a Communication Arrangement [page 277]
4.4.2.2.1.4 Setting Up a Communication Arrangement
Procedure
1. In the SAP Marketing Cloud system, choose Communication Arrangements app, click New to create a new arrangement.
2. In the New Communication Arrangement pop-up screen, enter the scenario SAP_COM_0065 and click Create.
3. Enter the Communication System that you defined in Setting Up a Communication System [page 275].
Integration Guide Integration Scenarios
PUBLIC
277
4. Under Additional Properties Tenant ID (SAP Analytics Cloud tenant) , maintain the tenant ID that is visible in the URL of SAP Analytics Cloud. When calling up https://xxx.sapanalytics.cloud, you'll be redirected to the full URL where you can find the tenant ID as shown in this example: https:// xxx.sapanalytics.cloud/sap/fpa/ui/tenants/«tenant ID»/app.html.
5. Under Inbound Communication User Name Authentication Method , select Authentication with OAuth 2.0 using the input help of the User Name field.
278
PUBLIC
Integration Guide Integration Scenarios
6. Under Outbound Communication, set SAML2 Identifier to User Name. Note down the SAML2 Issuer. For example, https://my300xxx-api.s4hana.ondemand.com/oa2cs. Download the signing certificate (the text file signing_pse.crt).
7. Ensure that under Outbound Services, both UI Link Navigation and Retrieve Stories have Service Status checked (= Active).
Integration Guide Integration Scenarios
PUBLIC
279
8. Save the communication arrangement. Task overview: SAC Neo Tenant [page 272] Previous task: Setting Up a Communication System [page 275] Next task: Completing the Setup of the Live Data Connection [page 280]
4.4.2.2.1.5 Completing the Setup of the Live Data Connection
Procedure
1. Switch back to the browser window with the SAP Analytics Cloud Live Data connection definition. 1. Enter the token service user and token service password that you defined in Setting Up a Communication System [page 275]. 2. Enter the following space-separated list as OAuth scope: SAP_BW_INA_BATCHPROCESSING_HTTP SAP_BW_INA_GETCATALOG_HTTP SAP_BW_INA_GETRESPONSE_HTTP SAP_BW_INA_GETSERVERINFO_HTTP SAP_BW_INA_LOGOFF_HTTP SAP_BW_INA_VALUEHELP_HTTP
2. Click OK.
280
PUBLIC
Integration Guide Integration Scenarios
Task overview: SAC Neo Tenant [page 272]
Previous task: Setting Up a Communication Arrangement [page 277]
Next task: Setting Up the Outbound Connections from SAP Marketing Cloud to SAP Analytics Cloud [page 282]
Integration Guide Integration Scenarios
PUBLIC
281
4.4.2.2.1.6 Setting Up the Outbound Connections from SAP Marketing Cloud to SAP Analytics Cloud
Procedure
1. In the SAP Analytics Cloud system, select System Administration App Integration Configured Clients .
2. To add a trusted identity provider, enter the following details: 1. A name chosen by you. 2. A provider name that is equal to the SAML 2 Issuer and to the signing certificate obtained in Setting Up a Communication Arrangement [page 277]. 3. The contents of the text filesigning_pse.crt into Signing Certificate.
Task overview: SAC Neo Tenant [page 272] Previous task: Completing the Setup of the Live Data Connection [page 280] Next task: Adding SAP Marketing Cloud as a Trusted Origin with SAP Analytics Cloud [page 283]
282
PUBLIC
Integration Guide Integration Scenarios
4.4.2.2.1.7 Adding SAP Marketing Cloud as a Trusted Origin with SAP Analytics Cloud
Allow the use of and then access the analytics stories in SAP Marketing Cloud.
Context
Analytics stories use charts, visualizations, texts, and pictograms to describe data. Before you can view your SAP Analytics Cloud stories, you must first add your SAP Marketing Cloud system as a trusted origin by adding the host name of the connected SAP Marketing Cloud system to SAP Analytics Cloud.
Procedure
1. Log on to SAP Analytics Cloud and select System Administration .
Integration Guide Integration Scenarios
PUBLIC
283
2. Navigate to the tab App Integration.
3. In the Trusted Origins section, click Add a Trusted Origin. 4. Enter the host name of the connected SAP Marketing Cloud system. For example, https://myXXXX-
api.s4hana.ondemand.com. 5. Click Save.
Note
If the third-party cookie isn't enabled in your browser, you could get the following logon error after clicking Analyze to display the analytics stories in SAP Marketing Cloud.
To resolve this error, go to your Chrome browser, open Advanced Settings Privacy and Security
Content settings Cookies . Add sapbusinessobjects.cloud and sapanalytics.cloud to the allowed list of third-party cookies.
284
PUBLIC
Integration Guide Integration Scenarios
Clear your browser cache and log in again. You can now see the analytics stories when you click Analyze.
You can click Analyze, for example in Campaigns and Spotlighting Accounts, to find the analytics stories.
Task overview: SAC Neo Tenant [page 272]
Previous task: Setting Up the Outbound Connections from SAP Marketing Cloud to SAP Analytics Cloud [page 282]
Related Information
Analytics Stories
4.4.2.2.2 SAP Cloud Foundry Tenant
Identify if the SAP Cloud Foundry tenant is the environment where SAP Analytics Cloud is hosted. If the tenant id is not visible as a part of the SAP Analytics Cloud URL, then SAP Analytics Cloud is hosted on the SAP Cloud Foundry environment. For example, https://xxx.sapanalytics.cloud/sap/fpa/ui/tenants/ app.html Now that you've identified the environment where SAP Analytics Cloud is hosted, create the live data connection with SAP Cloud Foundry. Complete the tasks in the following sequence:
1. Adding a New OAuth Client [page 286] 2. Adding a New Live Data Connection [page 288] 3. Setting Up a Communication System [page 289] 4. Setting Up a Communication Arrangement [page 292] 5. Completing the Setup of the Live Data Connection [page 295] 6. Setting Up the Outbound Connections from SAP Marketing Cloud to SAP Analytics Cloud [page 297] 7. Adding SAP Marketing Cloud as a Trusted Origin with SAP Analytics Cloud [page 298]
Allow the use of and then access the analytics stories in SAP Marketing Cloud.
Integration Guide Integration Scenarios
PUBLIC
285
4.4.2.2.2.1 Adding a New OAuth Client
Prerequisites
For the steps in the SAP Analytics Cloud system, the Admin or System Owner role is required.
Procedure
1. In the SAP Analytics Cloud system, navigate to System Administration App Integration OAuth Clients and note down the authorization URL, oAuth2SAML Token URL, and oAuth2SAML Audience.
2. Under Configured Clients, add a new OAuth Client with the following properties: 1. Name, for example "SAP SMC System" 2. The OAuth Client ID will generate upon saving. 3. Purpose: "Interactive Usage". 4. The Security Secret will auto-generate.
3. Press Add.
286
PUBLIC
Integration Guide Integration Scenarios
4. Once the oAuth Client is created, note down the OAuth Client ID and Secret (click on the Show Secret button to note down the generated secret).
Integration Guide Integration Scenarios
PUBLIC
287
Task overview: SAP Cloud Foundry Tenant [page 285] Next task: Adding a New Live Data Connection [page 288]
4.4.2.2.2.2 Adding a New Live Data Connection
Procedure
1. In the SAP Analytics Cloud system, navigate to Connection and press the Plus (+) icon to add a new connection.
288
PUBLIC
Integration Guide Integration Scenarios
2. Select Live Data Connection SAP S/4HANA . 3. In the dialog New S/4HANA Live Connection, enter a Name and Description.
In order to use SAP Marketing Cloud sample content, the name has to be SAPMKTNW. 4. Select Connection Type SAP S/4HANA Cloud. 5. Under Host, enter the host name of the SAP Marketing Cloud tenant. For example, my300xxx-
api.s4hana.ondemand.com. 6. Note down the provider name that is displayed under Authentication Method OAuth 2 SAML. Bearer
Assertion and download the signing certificate.
Note
No need to save at this point. We make the required configurations in SAP Marketing Cloud and return to this setup for saving.
Task overview: SAP Cloud Foundry Tenant [page 285] Previous task: Adding a New OAuth Client [page 286] Next task: Setting Up a Communication System [page 289]
4.4.2.2.2.3 Setting Up a Communication System
Prerequisites
For the steps in the SAP Marketing Cloud system, the Administrator role is required.
Procedure
1. Open SAP Marketing Cloud in a new browser window. In the app Communication Systems, click New to create a new communication system.
Integration Guide Integration Scenarios
PUBLIC
289
2. Under Technical Data General Host Name , enter the host name of the SAP Analytics Cloud tenant.
3. Under Technical Data OAuth 2.0 Settings , enter the authorization endpoint, oAuth2SAML Token endpoint, and oAuth2SAML Audience from when you added the new OAuth client. For more information, see Adding a New OAuth Client [page 286].
Note
Enter the authorization endpoint and the oAuth2SAML Token endpoint without the https:// prefix. The oAuth2SAML Audience must be entered exactly as it appears in the SAP Analytics Cloud systems.
4. Under OAuth 2.0 Identity Provider select Enabled. Enter the provider name and upload the signing certificate that you obtained in Adding a New Live Data Connection [page 288].
5. Create a Token Service User for Inbound Communication with the Authentication Method User Name and Password and note down the user name and password.
290
PUBLIC
Integration Guide Integration Scenarios
6. To create a user for Outbound Communication, enter the following details: 1. In Authentication Method, add OAuth 2.0. 2. Add the OAuth 2.0 client ID and the client secret that you defined in Adding a New OAuth Client [page 286].
7. Save the communication system. Task overview: SAP Cloud Foundry Tenant [page 285] Previous task: Adding a New Live Data Connection [page 288] Next task: Setting Up a Communication Arrangement [page 292]
Integration Guide Integration Scenarios
PUBLIC
291
4.4.2.2.2.4 Setting Up a Communication Arrangement
Procedure
1. In the SAP Marketing Cloud system app Communication Arrangements, click New to create a new arrangement.
2. Enter the Scenario SAP_COM_0065 and click Create.
3. Enter the Communication System that you defined in Setting Up a Communication System [page 289].
4. Under Additional Properties Tenant ID (SAP Analytics Cloud tenant) , maintain the SAP Analytics Cloud tenant ID. In the SAP Analytics Cloud system, you can find the tenant ID under Menu System About . The value displayed under System Name is the tenant ID.
Note
Please maintain the alpha part of the value in lower case. Even if you see the system name as "91B6F", the right value to enter is "91b6f".
292
PUBLIC
Integration Guide Integration Scenarios
5. Under Inbound Communication User Name Authentication Method , select Authentication with OAuth 2.0 using the input help of the User Name field.
Integration Guide Integration Scenarios
PUBLIC
293
6. Under Outbound Communication, set SAML2 Identifier to User Name. Note down the SAML2 Issuer. For example, https://my300xxx-api.s4hana.ondemand.com/oa2cs. Download the signing certificate (the text file signing_pse.crt).
7. Ensure that under Outbound Services, both UI Link Navigation and Retrieve Stories have Service Status checked (= Active).
294
PUBLIC
Integration Guide Integration Scenarios
8. Save the communication arrangement. Task overview: SAP Cloud Foundry Tenant [page 285] Previous task: Setting Up a Communication System [page 289] Next task: Completing the Setup of the Live Data Connection [page 295]
4.4.2.2.2.5 Completing the Setup of the Live Data Connection
Procedure
1. Switch back to the browser window with the SAP Analytics Cloud Live Data connection definition. 1. Enter the token service user and token service password that you defined in Setting Up a Communication System [page 275]. 2. Enter the following space-separated list as OAuth scope: SAP_BW_INA_BATCHPROCESSING_HTTP SAP_BW_INA_GETCATALOG_HTTP SAP_BW_INA_GETRESPONSE_HTTP SAP_BW_INA_GETSERVERINFO_HTTP SAP_BW_INA_LOGOFF_HTTP SAP_BW_INA_VALUEHELP_HTTP
2. Click OK.
Integration Guide Integration Scenarios
PUBLIC
295
Task overview: SAP Cloud Foundry Tenant [page 285]
Previous task: Setting Up a Communication Arrangement [page 292]
Next task: Setting Up the Outbound Connections from SAP Marketing Cloud to SAP Analytics Cloud [page 297]
296
PUBLIC
Integration Guide Integration Scenarios
4.4.2.2.2.6 Setting Up the Outbound Connections from SAP Marketing Cloud to SAP Analytics Cloud
Procedure
1. In the SAP Analytics Cloud system, select System Administration App Integration Configured Clients .
2. To add a trusted identity provider, enter the following details: 1. A name chosen by you. 2. A provider name that is equal to the SAML 2 Issuer and to the signing certificate obtained in Setting Up a Communication Arrangement [page 277]. 3. The contents of the text filesigning_pse.crt into Signing Certificate.
Task overview: SAP Cloud Foundry Tenant [page 285] Previous task: Completing the Setup of the Live Data Connection [page 295] Next task: Adding SAP Marketing Cloud as a Trusted Origin with SAP Analytics Cloud [page 298]
Integration Guide Integration Scenarios
PUBLIC
297
4.4.2.2.2.7 Adding SAP Marketing Cloud as a Trusted Origin with SAP Analytics Cloud
Allow the use of and then access the analytics stories in SAP Marketing Cloud.
Context
Analytics stories use charts, visualizations, texts, and pictograms to describe data. Before you can view your SAP Analytics Cloud stories, you must first add your SAP Marketing Cloud system as a trusted origin by adding the host name of the connected SAP Marketing Cloud system to SAP Analytics Cloud.
Procedure
1. Log on to SAP Analytics Cloud and select System Administration .
298
PUBLIC
Integration Guide Integration Scenarios
2. Navigate to the tab App Integration.
3. In the Trusted Origins section, click Add a Trusted Origin. 4. Enter the host name of the connected SAP Marketing Cloud system. For example, https://myXXXX-
api.s4hana.ondemand.com. 5. Click Save.
Note
If the third-party cookie isn't enabled in your browser, you could get the following logon error after clicking Analyze to display the analytics stories in SAP Marketing Cloud.
To resolve this error, go to your Chrome browser, open Advanced Settings Privacy and Security
Content settings Cookies . Add sapbusinessobjects.cloud and sapanalytics.cloud to the allowed list of third-party cookies.
Integration Guide Integration Scenarios
PUBLIC
299
Clear your browser cache and log in again. You can now see the analytics stories when you click Analyze.
You can click Analyze, for example in Campaigns and Spotlighting Accounts, to find the analytics stories.
Task overview: SAP Cloud Foundry Tenant [page 285]
Previous task: Setting Up the Outbound Connections from SAP Marketing Cloud to SAP Analytics Cloud [page 297]
Related Information
Analytics Stories
4.4.2.3 Renewal of Signing Certificates
Renew signing certificates. When you log on to SAP Analytics Cloud, you are notified if the service provider certificate is about to expire. If you then decide to renew the signing certificate, you must download the signing certificate again. For more information about how to download the signing certificate, see: Adding a New Live Data Connection [page 274] if SAP Analytics Cloud is hosted on the SAC Neo tenant. Adding a New Live Data Connection [page 274]if SAP Analytics Cloud is hosted on the SAP Cloud Foundry
tenant. Afterwards, upload the signing certificate to your communication system. For more information about how to upload the signing certificate, see: Setting Up a Communication System [page 275] if SAP Analytics Cloud is hosted on the SAC Neo tenant. Setting Up a Communication System [page 289] if SAP Analytics Cloud is hosted on the SAP Cloud
Foundry tenant.
Parent topic: Integration with SAP Analytics Cloud (1SO) [page 268]
Previous: Create the Live Data Connection to SAP Marketing Cloud [page 272]
Next task: Selecting SAP Marketing Cloud Content Packages to Add to Your Tenant [page 301]
300
PUBLIC
Integration Guide Integration Scenarios
4.4.2.4 Selecting SAP Marketing Cloud Content Packages to Add to Your Tenant
Choose and then import SAP Marketing Cloud content to your SAP Analytics Cloud system to improve your analytics scenarios.
Procedure
1. As an administrator, log on to your SAP Analytics Cloud system. 2. From the top-left menu, select Browse Files .
3. On the left pane, choose Content Library.
4. Choose the type of content that you want to add. You can choose either Samples or Business Content. Select Business Content.
Integration Guide Integration Scenarios
PUBLIC
301
5. Select the SAP Marketing Cloud package.
Note
If you're an upgrade customer, please note that in your system has the old package SAP Hybris Marketing Cloud. When you do the import, the new package SAP Marketing Cloud is added to your system. Check the What's New document for a description of the updates. Now, you have to move all the existing stories (SAP-delivered plus any stories you created yourself) from the old package into the new package. To select the target folder when moving the existing stories, choose the path Public SAP_Content SAP_Marketing and then the appropriate folder. Please follow the existing folder structure. For every folder, you have to do this step separately. After you've moved all the stories, please delete the old package.
6. A popup comes up with the details of the content in the package. Choose Import to get the content.
302
PUBLIC
Integration Guide Integration Scenarios
The import process can take a while. The system notifies you when it's done, or if an error occurs.
Integration Guide Integration Scenarios
PUBLIC
303
Task overview: Integration with SAP Analytics Cloud (1SO) [page 268] Previous: Renewal of Signing Certificates [page 300]
4.4.3 Content Studio Integrations
Lists the Content Studio integrations with SAP Marketing Cloud
Simple Content Repository [page 305] Simple Content Repository, based on SAP Document Center, is available as an out-of-box feature for all users.
Landing Page Publication [page 305] Landing Page Publication allows you to use your own company or brand domain name for landing pages published in SAP Marketing Cloud.
Integrate with Content Management Systems or Digital Asset Management Systems [page 306]
304
PUBLIC
Integration Guide Integration Scenarios
Integrate a Content Management System (CMS) or Digital Asset Management (DAM) system with the Content Studio app. Integrate with SAP Document Center [page 312] Integrate an SAP Document Center system with the Content Studio app. Integration with SAP Product Content Management [page 314] Use the integration with SAP Product Content Management to easily incorporate product pictures from SAP Product Content Management in your marketing messages. To use this integration, you must also use the communication arrangement: SAP_COM_0051. Integration with Return Path for Marketing Emails [page 316] You can use this integration to find out whether email providers would categorize emails that you want to send with a campaign as spam. You can also see if your email is displayed correctly on various devices, email programs and browsers. Integration with Litmus for Marketing Emails [page 317] You can use this integration to see if your email is displayed correctly on various devices, email clients and browsers.
4.4.3.1 Simple Content Repository
Simple Content Repository, based on SAP Document Center, is available as an out-of-box feature for all users. It allows you to select images from and upload images to the Content Studio. You can activate this feature in your tenant using the Content Repository Configuration app. For more information, see Configure Content Repositories.
4.4.3.2 Landing Page Publication
Landing Page Publication allows you to use your own company or brand domain name for landing pages published in SAP Marketing Cloud. You can activate this feature and configure the required CDN domain name using the Content Repository Configuration app. For more information, see Configure Content Repositories.
Integration Guide Integration Scenarios
PUBLIC
305
4.4.3.3 Integrate with Content Management Systems or Digital Asset Management Systems
Integrate a Content Management System (CMS) or Digital Asset Management (DAM) system with the Content Studio app.
Use
CMS or DAM systems provide catalogs of digital images, videos, documents, music, and so on. You can search for digital assets by keywords. You can integrate CMS or DAM systems with SAP Marketing Cloud to access images for use in the Content Studio app. The SAP Marketing Cloud Integration with Content Management System integration package is available on the SAP API Business Hub. For more information, see: https://api.sap.com
Prerequisites
To set up a communication system and communication arrangement, ensure that the business catalog role Communication Management (SAP_CORE_BC_COM) is assigned to your SAP Marketing Cloud user.
To configure and deploy the integration package in SAP Marketing Cloud, assign the roles mentioned in the following guide: Persona
Configure and Deploy the Integration Flows
The following artifacts are available in the SAP Marketing Cloud Integration with Content Management System package:
Template for CMS or DAM Integration Use this integration flow template to develop an integration flow. You can use the developed integration flow to integrate digital assets of any CMS or DAM system with SAP Marketing Cloud.
OpenText DAM System Integration Use this integration flow to integrate digital assets of the OpenText DAM system with SAP Marketing Cloud.
To configure and deploy the integration flows:
1. From your development tenant of your SAP Cloud Integration account, choose Discover, and then select and copy the SAP Marketing Cloud Integration with Content Management System package. The copied package appears in the Design view in your tenant.
Note
You can use SAP Marketing Cloud to configure and deploy the integration package. For more information, see SAP Cloud Integration.
306
PUBLIC
Integration Guide Integration Scenarios
2. Select the required artifact.
3. Modify the integration flow of the selected artifact.
4. Configure the following blocks in the Upload integration flow: For more information on modifying externalized parameters in integration flows, see Externalize Parameters of an Integration Flow.
Externalized parameters for integration flows
Field Name
Entry Value
DAM_CREDENTIAL
Enter the name of the deployed credential artifact.
Note
This credential is required to connect to the CMS or DAM system.
IFLOW_ENDPOINT
For information on deploying the User Credential Artifact, see Deploying or Editing a User Credentials Artifact.
Enter the relative path of the integration flow endpoint. The SAP Marketing Cloud system invokes the IFLOW_ENDPOINT endpoint by using the keyword_QUERY parameter along with toGET access the search endpoint.
Note
If keyword_QUERY parameter is not passed, connect is executed.
Note
Use this path in the Communication Arrangements app with the prefix /http as follows:
/http<relative_path>
For example, if you specify the value in this field as /OpenText, then use the following path in the Communication Arrangements app:
/http/OpenText
DAM_ACCESS_URL DAM_SEARCH_URL
Enter the address of the CMS or DAM endpoint to check or establish the connectiv ity with the CMS or DAM system.
For example, use the following URL in the OpenText DAM System Integration inte gration flow: https://<OpenText Host>/otmmapi/v3/sessions
Enter the address of the CMS or DAM endpoint to search the images in the CMS or DAM system. For example, use the following URL in the OpenText DAM System Integration inte gration flow: https://<OpenText Host>/otmmapi/v3/search/text
Integration Guide Integration Scenarios
PUBLIC
307
Field Name DAM_ACCESS_QUERY DAM_SEARCH_QUERY
DAM_RESULTLIST_XPATH DAM_SUGGESTION_URL DAM_SUGGESTION_QUERY
Entry Value
Enter the value of the query parameter in DAM_ACCESS_QUERY of the URL to check or establish the connectivity with CMS or DAM system.
<DAM_ACCESS_URL>?<DAM_ACCESS_QUERY>
For example, there is no value for the query parameter and URL in the OpenText DAM System Integration integration flow.
Enter the value of the query parameter in DAM_SEARCH_QUERY of the URL to search images in the CMS or DAM system.
<DAM_SEARCH_URL>?<DAM_SEARCH_QUERY>
For example, use the following URL in the OpenText DAM System Integration inte gration flow:
https://<OpenText Host>/otmmapi/v3/search/text? keyword_query\='(*${header.keyword_query}*)'&load_type \=metadata&metadata_to_return\=ARTESIA.FIELD.ASSET DESCRIPTION
XPath to split the response structure and get a series of digital assets.
For example, use the following XPath in the OpenText DAM System Integration inte gration flow:
/search_result_resource/asset_list
Enter the address of the CMS or DAM endpoint to read the suggested keywords in the CMS or DAM system.
For example, use the following URL in the OpenText DAM System Integration inte gration flow:
https://<OpenText Host>/otmmapi/v4/search/text/ suggestions
Enter the value of the query parameter in DAM_SUGGESTION_QUERY of the URL to read the suggested keywords in the CMS or DAM system.
<DAM_SUGGESTION_URL>?<DAM_SUGGESTION_QUERY>
For example, use the following URL in the OpenText DAM System Integration inte gration flow:
https://<OpenText Host>/otmmapi/v4/search/text/ suggestions? input=$ {header.keyword_suggestions}&search_plugin_id=ARTESIA.PL UGIN.SEARCH.SOLR.V1&max_suggestions=${header.top}
308
PUBLIC
Integration Guide Integration Scenarios
Field Name
Entry Value
DAM_SUGGESTIONRESULT_XPAT XPath to split the response structure and get a series of suggested keyword. H
For example, use the following XPath in the OpenText DAM System Integration inte gration flow:
/search_suggestion_result_resource/ search_suggestion_result/suggestion_list
5. Configure the following blocks in Integration Process:
Note
For more information on configuring integration flow blocks, see Configure Integration Flow Components.
1. (Optional) In the Content Modifier block, enter the header parameters, which are required to call the CMS or DAM system. The Content Modifier block is placed after the Router search route and the Start Event block.
2. Add the ${header.keyword_query} != null and ${header.CamelHttpMethod} = 'GET' condition to switch between connect and search logic. Ensure that connect logic is the default logic. The search logic is executed only when both the conditions are true.
3. You can define the required parameters to modify the request, which connects and searches the CMS or DAM system.
6. Configure the following information in Local Integration (Handle Search Response from DAM): In the Content Modifier block, enter the following Properties to map the image metadata between SAP Marketing Cloud and the required CMS or DAM system. The Content Modifier block is placed after the Generic Splitter block.
Note
By default, the Content Modifier supports the following rendition types: Preview Thumbnail
You can add or remove the required rendition types as follows:
Add or remove the DIGITALASSETFILE node inside the node ASSET in Content Modifier body. The structure of DIGITALASSETFILE node is as follows:
Sample Code
<DIGITALASSETFILE> <ASSET_ID></ASSET_ID> <FILE_ID></FILE_ID> <MIME_TYPE></MIME_TYPE> <RENDITION></RENDITION> <URL></URL> <WIDTH></WIDTH> <HEIGHT></HEIGHT>
Integration Guide Integration Scenarios
PUBLIC
309
</DIGITALASSETFILE>
<FILE_ID> accepts only numeric value. This value which must be unique for both Preview and Thumbnail renditions.
Field Name ASSET_ID CONTENT_TYPE PREVIEW_FILE_ID THUMBNAIL_FILE_ID PREVIEW_MIME_TYPE THUMBNAIL_MIME_TYPE THUMBNAIL_RENDITION
PREVIEW_RENDITION
PREVIEW_URL THUMBNAIL_URL TITLE DESCRIPTION ACCESS_DATA PREVIEW_WIDTH PREVIEW_HEIGHT THUMBNAIL_WIDTH THUMBNAIL_HEIGHT
Entry Value ID of image Type of content ID of image preview ID of image thumbnail MIME type of preview MIME type of thumbnail Name of the rendition. For example, Preview, Thumbnail, Original, and so on. Name of the rendition. For example, Preview, Thumbnail, Original, and so on. URL of image preview URL of image thumbnail Title of image Description of image This field does not require an entry value The width of the preview rendition image The height of the preview rendition image The width of the thumbnail rendition image The height of the thumbnail rendition image
Note
The following properties are sent by SAP Marketing Cloud to the integration flow as headers. These parameters are used while searching the CMS or DAM system. keyword_query: returns the search keywords entered in Content Studio. top: number of search results to be fetched as a part of the request.
310
PUBLIC
Integration Guide Integration Scenarios
skip: number of records to be skipped to display the records in the current page. keyword_suggestions: takes the characters entered in Content Studio to fetch the
suggested keywords.
7. Deploy the integration package. 8. Set up the communication system.
Create a communication system, which you can later use to establish communication arrangements. 1. Log on to your SAP Marketing Cloud system with a user that has administrator authorizations. 2. Launch the Communication Systems app, and choose New. 3. Enter a System ID and the System Name in the New Communication System window, and choose
Create. 4. In the Communication System page, enter the following:
1. Under Technical Data, enter the details of either SCI or middleware that you want to connect to. 2. Under User for Outbound Communication section, choose + to create a New Outbound User, which
can connect to the configured SCI or middleware: If you choose Authentication Method: User Name and Password from the dropdown, enter the following: User Name: <your communication user name> Password: <your communication user password> If you choose Authentication Method: SSL Client Certificate from the dropdown, choose either Default Client Certificate or Trusted Third-Party Key Pair. If you choose Trusted Third-Party Key Pair as authentication method, you have to browse to the Third-Party Key Pair and provide a password. For more information, see: Enabling Client Certificate Authentication 5. Choose OK.
Note
You can now establish a communication arrangement with the created system. Use the Maintain Communication Arrangements app for this purpose.
9. Set up the communication arrangement. 1. Log on to your SAP Marketing Cloud system with a user that has administrator authorizations. 2. In the SAP Fiori launchpad, choose the Communication Arrangements app. 3. Create a communication arrangement. 4. Choose the scenario SAP_COM_0050 (Marketing - Generic DAM Integration). 5. Enter the required arrangement name. 6. Choose Create. 7. In the Communication Arrangements screen, do the following: 1. Under Common Data, choose the communication system that you defined in Communication Systems app. 2. Under Additional Properties, choose the following: 1. CMS/DAM Name: Enter the name of the CMS or DAM system. For example, OpenText. 2. Implementation Mode: Choose 01 for SCI/Any Middleware. 3. Allow content upload: Choose Empty. If you select SCI/Any Middleware implementation mode, you cannot upload images. You can use SAP Document Center to upload images.
Integration Guide Integration Scenarios
PUBLIC
311
4. Folder for Upload: If you select SCI/Any Middleware implementation mode, you cannot upload images. You can use SAP Document Center to upload images.
5. Origin Domain Name and Path for CDN: Enter the domain name and the path of the Origin system that you have configured in the Content Delivery Network (CDN). For example, <Origin Domain Name>/<Path>.
6. CDN Domain Name: Enter the domain name generated during CDN configuration. 8. Under Outbound Communication, select the communication user name, which you previously defined. 9. Under Outbound Services:
Enter the path to access the deployed integration flow. The path contains the value of the externalized parameter IFLOW_ENDPOINT with the /http prefix. For example, if you specify the value of the externalized parameter asIFLOW__ENDPOINT / OpenText, then use the following path in the Communication Arrangements app: /http/OpenText
10. Choose Save.
4.4.3.4 Integrate with SAP Document Center
Integrate an SAP Document Center system with the Content Studio app.
Use
SAP Document Center provides anytime, anywhere access to view, edit, and collaborate on personal and corporate content in an easy-to-use mobile app. You can integrate SAP Document Center with SAP Marketing Cloud to access images for use in Content Studio app. This integration enables a user to search for content using keywords and also to upload content.
Prerequisites
To set up a communication system and the communication arrangement, ensure that the business catalog role Communication Management (SAP_CORE_BC_COM) is assigned to your SAP Marketing Cloud user.
To configure SAP Document Center in SAP BTP cockpit, you must have an SAP BTP account, enabled with SAP Document Center.
Configure SAP Document Center in SAP BTP cockpit
1. Launch SAP BTP. 2. Choose account subaccount . 3. Choose Services.
312
PUBLIC
Integration Guide Integration Scenarios
4. Enable the administrator role for your user in SAP Document Center. For more information, see https:// help.sap.com/viewer/p/SAP_Document_Center.
5. Choose Service Configuration Configure SAP Document Center .
Note
Note down the domain name from the SAP Document Center popup. This is the host name of the system. You need this information to update the Technical Data section of the Communication System page in the Communication Systems app.
6. Choose Settings Shared documents . 1. Select the Allow Sharing checkbox. The minimum password length should be 0, which is required for anonymous access. 2. Select the Allow Upload checkbox.
Configuration in the SAP Marketing Cloud
1. Define the communication user for Outbound Integration. Create a new communication system, which you can later use to establish communication arrangements. 1. Log on to your SAP Marketing Cloud system with a user that has administrator authorizations. 2. Launch the Communication Systems app, and choose New. 3. Enter a System ID and the System Name in the New Communication System window, and choose Create. 4. In the Communication System page, enter the following: 1. Under Technical Data section, enter the details of the system that you want to connect to.
Note
Enter the domain name from the SAP Document Center popup here.
2. Under User for Outbound Communication section, choose + to create a New Outbound User, which can connect to the SAP Document Center: Authentication Method: Choose User Name and Password from the dropdown. User Name: <your communication user name> Password: <your communication user password>
Note
The digital assets uploaded from the Content Studio app is available in the shared repository of the user.
3. Choose Create. 5. Choose Save.
Note
You can now establish a communication arrangement with the created system.
2. Set up the communication arrangement for SAP_COM_0050 scenario. Use the Communication Arrangements app for this purpose.
Integration Guide Integration Scenarios
PUBLIC
313
1. In the SAP Fiori launchpad, choose the Communication Arrangements app. 2. Choose New to create a new communication arrangement. 3. Choose the scenario SAP_COM_0050 (Marketing - Generic DAM Integration), enter an appropriate
arrangement name, and choose Create. 4. In the Communication Arrangements page, do the following:
1. Under the Common Data section, choose the Communication System that you defined in the Communication Systems app.
2. Under Additional Properties section, choose the following: CMS/DAM Name: Enter the name of the CMS/DAM system. This name is displayed in the Image Storage dropdown under the Upload New Image tab in the Content Studio app. Implementation Type: Choose 02 for SAP Document Center. Allow content upload: Choose X to allow content upload. Folder for Upload: Enter the folder name where you want to save the uploaded digital assets in the SAP Document Center.
Note
If the folder name entered by the user is unavailable, a new folder with the entered name is created.
Origin Domain Name and Path for CDN: Enter the domain name and the path of the Origin system that you have configured in the Content Delivery Network (CDN). For example, <Origin Domain Name>/<Path>
CDN Domain Name: Enter the domain name generated during CDN configuration. 3. Under Outbound Communication section, select the communication User Name, which you have
previously defined. 4. Under Outbound Services section, enter the following path: /mcm/b/json 5. Choose Save.
4.4.3.5 Integration with SAP Product Content Management
Use the integration with SAP Product Content Management to easily incorporate product pictures from SAP Product Content Management in your marketing messages. To use this integration, you must also use the communication arrangement: SAP_COM_0051.
Use
In SAP Marketing Cloud, you can create marketing emails using the Content Studio. A marketing email can contain digital assets, such as images. Digital assets are usually stored in an external Digital Asset Management (DAM) system. The DAM system also provides search capabilities for the media files. You can integrate SAP Product Content Management with the Communication Systems app as a DAM system.
314
PUBLIC
Integration Guide Integration Scenarios
New Communication System
To add a new communication system, proceed as follows: 1. Open the Communication Systems app and choose New to create a new communication system. Make the
following entries on the dialog box: System ID: HYBRIS_COMMERCE_PCM System Name: HYBRIS_COMMERCE_PCM 2. Choose Create. 3. On the following window, enter the host name of your SAP Product Content Management server in the Host Name field. 4. Add a User for Outbound Communication and choose None as Authentication Method in the New Outbound User dialog box. 5. Choose Create.
Communication Arrangement
To add a new communication arrangement, proceed as follows: 1. Open the Communication Arrangements app and choose New to create a new communication
arrangement. 2. On the dialog box, choose the scenario SAP_COM_0051 and then choose Create. 3. On the following window, choose the communication system created above and None as the User Name in
the area Outbound Communication. Make the following entries for Retrieve product images from SAP Commerce PCM: Port: Enter the port number that is setup on the server for HTTPS (SSL) Path: Enter the path to the V1 REST API of the Omni Commerce Channel (OCC) Service URL: Enter the service URL 4. Choose Save.
More Information
Using Image Links in Emails and Email Templates Creating a Personalized Email or Email Template
Integration Guide Integration Scenarios
PUBLIC
315
4.4.3.6 Integration with Return Path for Marketing Emails
You can use this integration to find out whether email providers would categorize emails that you want to send with a campaign as spam. You can also see if your email is displayed correctly on various devices, email programs and browsers.
Use
To check an email, its content is sent to the email address of an external service provider. For more information about the function, see Using the Spam Filter and Email Previews. This function is available if you have signed a separate contract with the external service provider Return Path. To do so, contact Return Path at https://returnpath.com/request-a-demo/ or email sap@returnpath.com.
Procedure
1. Request API credentials from Return Path. To do so, contact your Return Path account team or submit a support ticket. Make sure you specify that you are using SAP Marketing Cloud as your provider in the ticket. SAP currently supports the following Return Path features with SAP Marketing Cloud: Inbox Preview Spam Filter Check Once Return Path has created the account, you receive the following information: API Key API Secret
2. Create an incident for the system in which you want to activate the email content check and enter the SAP component CEC-MKT-MEM. Enter the following information: Description: Request for individual activation of SAP_COM_1035 Your credential data, which you received from Return Path (API Key and API Secret, ideally via Secure Store) For information about securely transferring your Return Path credentials, see SAP Note 1773689 .
316
PUBLIC
Integration Guide Integration Scenarios
4.4.3.7 Integration with Litmus for Marketing Emails
You can use this integration to see if your email is displayed correctly on various devices, email clients and browsers.
Use
To check an email, its content is sent to the external service provider Litmus. If you want to use the feature, you need a separate contract with Litmus, which you can apply directly from inside the Content Studio app or from the SAP App Center. For more information about the function, see Using the Preview with Litmus for an Email Lite. For new customers from release 2005, the selection Litmus Preview is automatically displayed in the Content Studio app.
Procedure
Proceed as follows to make the selection visible to your users: 1. Log on as administrator. 2. Choose the Maintain Business Role tile. 3. Search for the role for which you want to enable access to the Litmus Preview function. 4. Choose the Assigned Business Calalogs tab and ensure the business catalog Marketing - Content (ID:
SAP_CEC_BC_MKT_LIB1_PC) is assigned. 5. Only if that business catalog is assigned, you can now add the new business catalog Marketing - Content
with Litmus (ID: SAP_CEC_BC_MKT_CNT_LTM_PC).
Note
If this business catalog Marketing - Content with Litmus is already assigned, delete it to remove the selection in the Content Studio app.
4.4.4 Enabling Geospatial Segmentation with here.com
Use the integration option to translate addresses to geo-coordinates and reverse, and to enable geospatial analysis for segmentation based on the connected maps. For more information, see Setting up the Geospatial Segmentation and Map Preview.
Note
SAP only provides the interfaces and configuration options that allow you to connect the map visualization and geocoding services. The usage of here.com is not part of your end-user license agreement with SAP. It is your responsibility to check and/or adapt the default configuration.
Integration Guide Integration Scenarios
PUBLIC
317
4.4.5 Integration with Baidu Maps for Geospatial Segmentation (Deprecated)
The integration of Baidu Maps into Segmentation enables you to segment contacts in China by geographic location in a visualized way.
Note
To use this function, you must have contact location data in the form of geographic coordinates in SAP Marketing Cloud.
For a description of the function, see Using Geospatial Segmentation with Baidu Maps (Deprecated). For setup instructions, see Setting Up the Integration with Baidu Maps for Geospatial Segmentation (Deprecated) [page 318].
4.4.5.1 Setting Up the Integration with Baidu Maps for Geospatial Segmentation (Deprecated)
Set up the integration of Baidu Maps into Segmentation.
Prerequisites
You have applied for a Baidu account key to use Baidu Maps APIs through Baidu Maps Platform at http:// lbsyun.baidu.com .
You have a business role that contains the Communication Management (SAP_CORE_ BC_COM) business catalog. This business catalog is required for creating the communication system and communication arrangement. You can use the standard business role Administrator (SAP_BR_ADMINISTRATOR), which contains the Communication Management business catalog and other administration-related catalogs. Alternatively, you can create custom business roles using the Maintain Business Roles app.
You have a business role that contains the Marketing - Segmentation and Campaign Configuration (SAP_CEC_BC_MKT_CPC_PC) business catalog. This business catalog is required for activating the relevant segmentation profile in the Segmentation Configuration app. You can use the standard business role Administrator - Marketing (SAP_BR_ADMINISTRATOR_MKT), which contains the Marketing - Segmentation and Campaign Configuration business catalog and other configuration-related catalogs. Alternatively, you can create custom business roles using the Maintain Business Roles app.
You have a business role that contains the Security (SAP_CORE_BC_SEC) business catalog. This business catalog is required for managing trusted sites. You can use the standard business role Administrator (SAP_BR_ADMINISTRATOR), which contains the Security business catalog and other administration-related catalogs. Alternatively, you can create custom business roles using the Maintain Business Roles app.
318
PUBLIC
Integration Guide Integration Scenarios
Procedure
1. Create a communication system that represents the Baidu Maps system, as follows: a. Log into SAP Fiori launchpad with a business role that contains the Communication Management (SAP_CORE_ BC_COM) business catalog. b. Open the Communication Systems app. c. Choose New.
The New Communication System dialog box appears. d. Enter a system ID and a system name. Choose Create.
Examples: System ID: BAIDU_MAP System name: Baidu Map
The editing screen for the communication system appears. e. In the Host Name field, enter www.baidu.com, which is the host name of the Baidu Maps server.
Choose Save. f. Create a user for the outbound communication, as follows:
1. In the User for Outbound Communication section, choose + (Add). 2. Set the authentication method to None. Choose Create. g. Save and activate the communication system.
Do not exit SAP Fiori launchpad. 2. Create a communication arrangement for communicating with Baidu Maps, as follows:
a. Open the Communication Arrangements app. b. Choose New.
The New Communication Arrangement dialog box appears. c. Enter scenario SAP_COM_0075 and an arrangement name. Choose Create.
The editing screen for the communication arrangement appears. d. In the Communication System field, enter the communication system that you have created. e. In the Baidu Account Key field, enter your Baidu account key. f. In the Baidu Map API section, enter the required information, such as the path. g. Save and activate the communication arrangement. h. Exit SAP Fiori launchpad. 3. Activate the All China Consumers (B2C) segmentation profile, as follows: a. Log into SAP Fiori launchpad with a business role that contains the Marketing - Segmentation and
Campaign Configuration (SAP_CEC_BC_MKT_CPC_PC) business catalog. b. Open the Segmentation Configuration app. c. Choose Segmentation Profiles. d. Select All China Consumers (B2C) from the left pane. e. Choose Edit in the Use in Applications section in the right pane. f. Select the Use checkbox for the Segmentation Model application. g. Choose Save. h. Go back to the initial screen of the Segmentation Configuration app. Choose Segmentation Objects and
Attributes.
Integration Guide Integration Scenarios
PUBLIC
319
i. Search for the China Consumer (deprecated; SAP_CE_LOC_CN; use the segmentation object Contacts instead) segmentation object. Select it after you find it.
j. From the details screen of the segmentation object on the right, select the SAP_CONTACT_INTERACTIONS_CN data source. A details screen of the data source opens.
k. Switch to the edit mode by choosing Edit. Do the following on both the IA_LATITUDE_BD09 and IA_LONGITUDE_BD09 properties: Select the Visible as Attribute checkbox. From the Attribute Group dropdown list, select Interactions.
l. Choose Save. m. Exit SAP Fiori launchpad. 4. Log into SAP Fiori launchpad with a business role that contains the Security (SAP_CORE_BC_SEC) business catalog. 5. Open the Manage Content Security Policy app. 6. On the Trusted Sites tab, select UI_RESOURCES_SCRIPTS. A details pane opens on the right. 7. On the Managed by Customer tab, add https://api.map.baidu.com as a trusted site. Save your changes.
4.4.6 SAP Jam Integration for Collaboration
The integration enables using SAP Jam in SAP Marketing Cloud to facilitate the collaboration when planning and executing marketing campaigns.
Note
Keep in mind that you need the Social Collaboration Integration (SAP_COM_0026) for this integration. For more information, see SAP Jam Collaboration under Administration.
For information about how to set up the integration, see SAP Help Portal at https://help.sap.com/viewer/p/ SAP_JAM_COLLABORATION, Administration Administrator Guide (HTML) Integrations .
Prerequisites
SAP Jam is installed. SAP Jam server is defined in the configuration of the system. System user is also a SAP Jam user. For the SAP Jam widget to appear in the Campaigns app, ensure you maintain the source URL, for
example, https://*.sapjam.com/, in the whitelist of the Content Security Policy. For more information, see Manage Content Security Policy.
320
PUBLIC
Integration Guide Integration Scenarios
Features
Create and link SAP Jam group or assign existing group. Post status changes to SAP Jam group. Automatic upload of export files to SAP Jam group. Display SAP Jam feed in a campaign.
4.4.7 Verifying Email Addresses Using a Partner Solution
Accurate email addresses are vital for email marketing campaigns. To verify email addresses you can use partner services, such as Neverbounce or others. For more information, see the blog SAP Marketing Cloud Verifying E-Mail addresses with Neverbounce .
4.4.8 Integration with an External Coupon Service System
Integrate SAP Marketing Cloud with an external coupon service system. To use this integration, you must use the communication arrangement: SAP_COM_0286.
Use
SAP Marketing Cloud allows you to integrate with an external coupon management service. Such a service is responsible for coupon code creation, validation and redemption. The offer and coupon functionality in SAP Marketing Cloud is also responsible for consistently publishing offers with and without assigned coupons using the different digital marketing channels. Perform the following tasks to set up an external coupon service.
Implement Outbound Interface
Implement the external coupon outbound interface, either directly in the external system, or by using a suitable integration middleware, such as SAP Cloud Integration (https://cloudplatform.sap.com/capabilities/productinfo.SAP-Cloud-Platform-Integration.cceaaf2b-8ceb-4773-9044-6d8dad7a12eb.html ), to map the SAP Marketing Cloud interface to the external system interface. The external coupon service must follow the REST application protocol via HTTPS and must accept JSON.
Integration Guide Integration Scenarios
PUBLIC
321
Set Up a Communication Arrangement
1. Set up the communication system to define the endpoint of the external coupon service. Create a new communication system, which you can later use to establish communication arrangements. 1. In the SAP Fiori launchpad, log on with a user that has administrator authorizations. 2. Launch the Communication Systems app, and choose New. 3. In the New Communication System window, define the System ID for the communication system, for example, Z_EXTERNAL_COUPON_SRV. Define a System Name. You can freely define a name; note that the name is used when you create the communication arrangement. Choose Create. 4. In the Communication System page, enter the following: 1. Under Technical Data, specify the external system you want to use for the external coupon service. Indicate the pure host name, no path, no port. Define the HTTPS Port, default is 443. Note that the other properties under Technical Data are not relevant. 2. Optionally, you can provide your contact information for the communication system you are defining. 3. Define the users to be used for the communication: Under User for Inbound Communication, create a new technical user. This user will be able to access the corresponding inbound APIs to write Coupon Codes and Redemption Interactions. Under User for Outbound Communication, define the user to be used to access your external coupon service. 5. Choose Save to save the new or edited communication system in an active status..
Note
You can now establish a communication arrangement with the created system. Use the Maintain Communication Arrangements app for this purpose.
2. Set up the communication arrangement. Create a communication arrangement and reference the communication system created in the first step. 1. In the SAP Fiori launchpad, choose the Communication Arrangements app. 2. Create a new communication arrangement. 3. 2. In the New Communication Arrangement dialog, under Scenario, use the value help to select the predefined scenario Marketing - External Coupon Management Service Integration (SAP_COM_0286). 4. Enter the required arrangement name. 5. Choose Create. 6. In the Communication Arrangements screen, do the following: 1. Under Common Data, use the value help to select the communication system you have created in the Communication Systems app. 7. Under Outbound Services specify the relative path for the outbound service. The host name is already defined in the communication system. The resulting URL to connect to the external service via HTTPS will be https://<service_url>/<path>:<port>: 8. Choose Save to save the new or edited communication arrangement in an active status.
Note
You should only maintain one communication arrangement for the scenario SAP_COM_0286. Although you can create multiple communication arrangements, only the most recently activated communication arrangement is used when replicating coupons.
322
PUBLIC
Integration Guide Integration Scenarios
Process Overview
Once you have setup your external coupon service and the connection to it, the external coupon management process is performed as follows. You require the business catalog role Marketing Recommendation (SAP_CEC_BC_MKT_REC_PC) to work with offers and coupons.
1. Plan your offer with coupon In the Manage Offers app, create an offer with a coupon feature. Maintain your offer details.
2. Create and assign a coupon for your offer In the coupon tab for an offer, assign an existing coupon by searching the coupon value help or create a new coupon directly by choosing Create. This creates a default coupon, navigates you to the coupon details and assigns the coupon to the offer in a single step.
3. Release the coupon and replicate it to the external system In the Manage Coupons app, in the section General Information, maintain the integration property. Set the value for Replicate to External Coupon Service to Yes. Choose Release and then Replicate to transfer the coupon and assigned offer information to the external system. In the dialog, define the initial number of coupon codes to be created by the external system.
4. Release the offer and use it in your execution process (such as in an email campaign) Navigate back to the offer and choose Release. You can now use the offer in execution processes. For example, you can run an email campaign with an email message that contains the offer. Note that the offer needs to have coupon codes and needs to also be visible during campaign execution.
5. Changes made to your offer are communicated to the external system If you change the offer (either in the preparation phase of the offer or after setting the status to Paused), these changes are also communicated to the external coupon service.
6. If needed, request more coupon codes during the lifetime of your offer During the lifetime of the offer with coupon, you can request additional coupon codes from the external coupon system. Open the app Manage Coupons and navigate to the details for the coupon object. In the section Coupon Codes, you can choose Request Additional Codes. On the dialog box, define the number of additional codes to be added to the existing number of codes. The properties Total Number of Requested Codes and Number of Pending Codes in the Integration section of the coupon header give an overview about replication progress.
For information about the overall process of offers with coupon and external coupon service, see Offers with External Coupon Service.
Integration Guide Integration Scenarios
PUBLIC
323
Implementing the External Coupon Service
To replicate coupon and offer information to an external coupon service, SAP Marketing Cloud calls a defined REST endpoint with a JSON payload via HTTPS. The payload is structured into four different objects, as you see in the following figure:
As long as the offer can be changed, SAP Marketing Cloud calls the REST endpoint. A detailed overview about the properties, their data types and semantics can be found in the following table:
Object Coupon
Property CouponUUID
Data Type UUID
Size 36
Coupon
String
32
CouponOrigin
String
30
CouponType
String
10
CouponContact String
2
RelationshipType
CouponStatus
String
2
Semantic
Example Value
Internal identifier of the coupon header
6c0b84b7-5523-1e e8-9689-445f06b 876e8
User-defined iden CPN_201835_000 tifier of the coupon 1
User-defined ori gin of the coupon identifier
DEMO
Indicates the type SINGLE Single
of the coupon
Coupon Code
MULTI Multiple Coupon Codes
Indicates the rela 01 No Contact
tionship between a Assigned
coupon code and the contact
03 Contact As signed Dynami
cally
Status of the cou pon code
01 In Preparation 02 Released
324
PUBLIC
Integration Guide Integration Scenarios
Object
Property
Data Type
CouponCode Val Decimal idityDuration
CouponCode Val String idityDurationUnit
CpnCodeValidity StartDelay
Decimal
CpnCodeValidity StartDelayUnit
String
TotalNumberOf Redemption
Integer
TotalNumberOf RdmptnPerCon tact
Integer
NumberOfRe
Integer
quested CouponC
odes
Coupon Texts
SingleCoupon Code
Language
String String
Size 15/0 3 15/0 3 ---
--
128 2
CouponName
String
120
CouponDescrip String
512
tion
Assigned Offer
MarketingOffer
String
10
Semantic
Example Value
Duration of the val 14 idity of an individ ual code.
Unit of the dura DAY tion, defaulted to days
Validity start delay 1 of an individual code
Unit of the validity DAY start delay, de faulted to days
Total number of re 1.000 demptions possi ble for this coupon
Number of re
1
demptions possi
ble for each con
tact or code.
Number of codes to be generated by the external cou pon system.
50.000
SUMMER-SALE
ISO code of the
EN
language-depend
ent name and de
scription
Name of the cou pon
Description of the coupon
Internal identifier 0000000815 of the offer
Integration Guide Integration Scenarios
PUBLIC
325
Object
Property
Data Type
Size
Semantic
Example Value
ExternalOffer
String
60
ExternalOfferOri- String
30
gin
OfferStatus
String
2
OfferValidity Start Date Time
--
DateTime
OfferValidity End Date Time
--
DateTime
OfferVisibility
Date Time
--
StartDateTime
OfferVisibility End Date Time
--
DateTime
Assigned Loca
MarketingLocation String
50
tions
MarketingLocation String
30
Origin
External identifier of the offer if it was created externally and not within SAP Marketing Cloud
Origin of the exter nal offer identifier
Status of the offer 00 In Prepara tion
01 Released
02 Paused
ISO 8601-compli ant timestamp in UTC
2018-06-13T22:00 :00.000+0000
ISO 8601-compli ant timestamp in UTC
2018-06-13T22:00 :00.000+0000
ISO 8601-compli ant timestamp in UTC
2018-06-13T22:00 :00.000+0000
ISO 8601-compli ant timestamp in UTC
2018-06-13T22:00 :00.000+0000
Identifier of the marketing location
Origin of the loca SAP_RE
tion identifier
TAIL_STORE
In the lifecycle of the offer with coupon, the following requests will be sent to the external coupon service. All requests always contain the complete set of properties with their current values.
1. A HTTP POST request for the initial replication of the coupon with the assigned offer data. 2. A HTTP PUT request for any changes to the assigned offer (such as adding assigned marketing locations,
extending the validity period of the offer). The property NumberOfRequestedCouponCodes is 0 in this case. 3. A HTTP PUT request to request additional codes. The property NumberOfRequestedCouponCodes contains the actual number of requested codes and not the overall number of codes to be generated. If for example the initial replication requests 50.000 codes and an additional request for 10.000 codes is issued, the NumberOfRequestedCouponCodes is 10.000 for the second request for additional codes.
326
PUBLIC
Integration Guide Integration Scenarios
Example payload for the initial replication request for a coupon with 50.000 codes. The URL of the endpoint is defined in the communication arrangement / RFC destination.
Sample Code
POST /coupons {
CouponUUID: "6c0b84b7-5523-1ee8-9add-d272824ef884", Coupon: "CPN ID 4711", NumberOfRequestedCouponCodes: 50000, ... CouponTexts: [{
Language: "EN", CouponName: "Coupon Name", CouponDescription: "Coupon Description" }] AssignedOffer: { MarketingOffer: "OFFER ID 4711", ExternalOffer: "PMR ID 4711", ExternalOfferOrigin: "SAP_PMR", ... AssignedLocations: [{
MarketingLocation: "LOC ID 4711", MarketingLocationOrigin: "SAP_RETAIL_STORE" }] } }
Example payload for a subsequent request of 10.000 additional codes. The complete payload is sent again. The only difference here is the value of the NumberOfRequestedCouponCodes property.
Sample Code
PUT /coupons {
CouponUUID: "6c0b84b7-5523-1ee8-9add-d272824ef884", Coupon: "CPN ID 4711", NumberOfRequestedCouponCodes: 10000, ... CouponTexts: [{
Language: "EN", CouponName: "Coupon Name", CouponDescription: "Coupon Description" }] AssignedOffer: { MarketingOffer: "OFFER ID 4711", ExternalOffer: "PMR ID 4711", ExternalOfferOrigin: "SAP_PMR", ... AssignedLocations: [{
MarketingLocation: "LOC ID 4711", MarketingLocationOrigin: "SAP_RETAIL_STORE" }] } }
Integration Guide Integration Scenarios
PUBLIC
327
CSRF protection
We provide CSRF protection according to the standard implemented at SAP: Any modifying request is rejected unless the header attribute x-xsrf-token is added with a valid token value. The client must be able to obtain a valid token using the following procedure: The token will be requested by a HTTP HEAD request to the default endpoint URL. This call will include the name/value pair "x-csrf-token/fetch" in the request header. The response includes the name/value pair "x-xsrf-token/<validToken>". The valid token will be used for
subsequent requests. It is not mandatory for an external coupon service to implement CSRF protection as long as the HTTP HEAD request to fetch the CSRF token will not fail.
Handling Errors
If an error occurs when communicating with the external coupon service, SAP Marketing Cloud expects a corresponding HTTP status code. Furthermore, details about the source of the error can be included as JSON in the body of the HTTP response. The JSON is parsed and processed further, for example the error message is shown in the Manage Coupon user interface when the replication of the coupon fails. Example of an error response:
Sample Code
{ "error": { "status": 404, "message": "Coupon not found", "target": "/path_to_api_endpoint/object_id", "details": [{ "message": "Detailed error message goes here" }] }
}
Implementing Inbound Interfaces
In addition to the outbound interface used to create a coupon with offer information in an external coupon management system, the following SAP Marketing Cloud inbound APIs are also relevant to the overall process: Importing coupon codes into SAP Marketing Cloud Importing redemption interactions into SAP Marketing Cloud
Importing Coupon Codes The external coupon management service is responsible for generating coupon codes and transferring them back to SAP Marketing Cloud for distribution in the digital channels. This can be done using the Coupon OData API. For more information, see Coupons [page 1026].
328
PUBLIC
Integration Guide Integration Scenarios
Sample Code
Example payload to create a single coupon code for a given coupon UUID
POST /sap/opu/odata/sap/API_MKT_COUPN_SRV/Coupons(guid'<coupon_uuid>')/ to_CouponCode {
"CouponCode": "Coupon Code, e.g. Web-Code", "CouponCodeSerialNumber": "Coupon Code Serial Number", "EANCodeImageURL": "Image URL to EAN code", "QRCodeImageURL": "Image URL to QR code" }
Importing Redemption Interactions One integral part of an external coupon management service is the redemption of coupon codes. SAP Marketing Cloud can also use this information to optimize the distribution and communication of offers with coupons. For example, the offer recommendation will only recommend offers with assigned coupons when the redemption limit has not yet been reached. The interaction API can be used to inform SAP Marketing Cloud about offer redemption events. For more information, see Interactions [page 615]. The following pre-defined interaction type is delivered with SAP Marketing Cloud: OFFER_REDEMPTION: Inform about a redemption of an offer with assigned coupon. The redemption counter in SAP Marketing Cloud will be increased in this use case.
Sample Code
Example payload for an anonymous offer redemption interaction from an online shop
POST /API_MKT_INTERACTION_SRV/Interactions {
"InteractionTimeStampUTC": "/Date(1530626397595)/", "CommunicationMedium": "ONLINE_SHOP", "InteractionType": "OFFER_REDEMPTION", "InteractionIsAnonymous": true, "InteractionOffers": [{
"MarketingOffer": "0000000815", "CouponCode": "CODE-0815-ABC" }] }
For more information about set up of interaction channels, see Managing Interaction Content.
Integration Guide Integration Scenarios
PUBLIC
329
4.4.9 Partner Extension: Integrate with Digital Market Intelligence
With the partner integration of SimilarWeb, you can see the web no app traffic of your competitors for each channel, such as direct, email, social. These insights help you to make better strategic decisions with regard to your own campaigns. Note that the extension is an offering from a partner of SAP.
To add the partner extension in SAP Marketing Cloud, do the following steps: 1. Open your system of SAP Marketing Cloud and go to the Extensions under your user details. 2. Add an extension with
a section a title, for example, SimilarWeb and a URL. For an overview of all available URLs, see Widgets Demo of SimilarWeb
Now, you should see an additional tab in the Marketing Plans app, when you open a single plan.
For more information, see SimilarWeb .
Related Information
UI Extensions
4.4.10 Marketing Events
This section for marketing events explains the following: How to integrate events, registrants, and participants data from third-party event provider platforms, such
as ON24 platform with SAP Marketing Cloud using integration flows. For more information, see Integration with Marketing Events [page 330]. How to integrate events, registrants, and participants data from GoToWebinar platform with SAP Marketing Cloud using integration flows. For more information, see Integration with GoToWebinar using SAP Cloud Integration Open Connectors [page 332].
4.4.10.1 Integration with Marketing Events
The integration of events data from event provider platform, such as ON24 platform with SAP Marketing Cloud enables promotion of these events via campaigns and analysis of their success rate after event completion. This integration fetches and stores event data easily from the event provider platforms into SAP Marketing Cloud system.
To achieve this integration the following iFlows are provided:
330
PUBLIC
Integration Guide Integration Scenarios
Fetch Marketing Events Data from Event Provider Platforms This integration flow calls the API endpoints from the event provider platform (ON24) to fetch the events data and map it to the SAP Marketing Cloud format. This fetched data is used by the application job to create the marketing event object in SAP Marketing Cloud system. If the iFlow is run in full mode header value delta = false, then all the events from the specified start date plus 180 days are fetched and updated in SAP Marketing Cloud system. If the iFlow is run in delta mode header value delta = true, then all the events updated from the lastrundatetime, that is, header value plus 180 days will be fetched and updated in SAP Marketing Cloud system.
Fetch Registrant Data from Event Provider Platforms This integration flow calls the API endpoints from the event provider platform (ON24) to get the registrants' data for an event and map it to the SAP Marketing Cloud format. This fetched data is used by the application job to update or created the following objects in SAP Marketing Cloud system:
Registrants are updated or created as interaction contacts
Activities like registration, permission opt-in are created as interactions of respective contacts
Fetch Participant Data from Event Provider Platforms This integration flow calls the API endpoints from the event provider platform (ON24) to get the participants (attendee) data for an event and map it to the SAP Marketing Cloud format. This fetched data is used by the application job to update or created the following objects in SAP Marketing Cloud system:
Participants are updated or created as interaction contacts
Engagement data of participants like polls and surveys are created as survey responses of respective contacts
Fetch Participant Engagement Data from Event Provider Platforms This integration flow calls the API endpoints from the event provider platform (ON24) to import engagement data of participants such as polls and surveys metadata to SAP Marketing Cloud system. This metadata is used to create the poll or survey business object in SAP Marketing Cloud system. Survey responses to these polls and survey are captured using the 'Fetch Participant Data from Event Provider Platforms' iflow .
The integration package runs on the SAP Cloud Integration tenant and fetches events data from event provider platforms and transform it into SAP Marketing Cloud format. The Network Security team takes responsibility for preparing the network environment across different systems and related security aspects.
Integration Guide Integration Scenarios
PUBLIC
331
For more information, see Integrating Marketing Events Data with SAP Marketing Cloud.
4.4.10.2 Integration with GoToWebinar using SAP Cloud Integration Open Connectors
The integration of events data from GoToWebinar platform with SAP Marketing Cloud enables promotion of these events via campaigns and analysis of their success rate after event completion. This integration fetches and stores event data easily from the event provider platforms into SAP Marketing Cloud system.
To achieve this integration the following iFlows are provided: Fetch Marketing Events Data from GoToWebinar Platform - Events data is fetched from the GoToWebinar
platform. Fetch Registration Data from GoToWebinar Platform - Registrants' information is fetched from the
GoToWebinar platform, and registrants are created as interaction contacts on SAP Marketing Cloud system. Fetch Participation Data from GoToWebinar Platform - Participant data is fetched from the GoToWebinar platform. The participants are created as new interaction contacts. The participant details will also contain engagement data like polls and surveys. The engagement data of participants is created as interaction activities in SAP Marketing Cloud system.
The integration package runs on the SAP Cloud Integration tenant and fetches events data from event provider platforms and transform it into SAP Marketing Cloud format. The Network Security team takes responsibility for preparing the network environment across different systems and related security aspects.
SAP Cloud Integration Open Connectors are used to simplify the connectivity and provide seamless integration with GOToWebinar platform. If there are any updates from the event provider platform, they will be handled by SAP Cloud Integration Open Connectors.
332
PUBLIC
Integration Guide Integration Scenarios
Limitations on GotoWebinar Integration
Functional Limitations
The following data is not supported by GotoWebinar platform as their APIs do not fetch these details for a specific event or a participant:
On-demand Duration: The time during which a participant viewed the recording of the event. Content Downloads: The number of different types of content downloaded by a participant. Participation Score: A measure for a participant's engagement in an event. This score is determined by
comparing and rating concrete KPI values of a participant in an event. On-demand Recording Available From: The date from which the recording of the event is available for
viewing. On-demand Recording Available Until: The date until which the recording of the event will be available for
viewing.
Note
GoToWebinar allows recurring events with multiple sessions, but multiple sessions are not supported with this integration. You should set up a single session between each SAP Marketing Cloud event and GoToWebinar webinar.
Technical Limitations
The following technical limitations are found with integrating GoToWebinar platform data using SAP Cloud Integration Open Connector:
The data being fetched from GoToWebinar platform and integrated in SAP Marketing Cloud by marketing application job cannot effectively run in incremental mode. Event data that is within the application job date range will be fetched irrespective of whether data has been changed since the last run or not. Due to this, the number of data fetch calls made using SAP Cloud Integration Open Connectors increases and the performance for application job execution is suboptimal.
The registrant or participant details are fetched and integrated by calling the participant API individually for each registrant or participant. Due to this, the number of data fetch calls made using Open Connectors increases depending on the number of registrants or participants.
For more information, see Integrating GoToWebinar Data with SAP Marketing Cloud using SAP Open Connectors.
4.5 Suite-Enabling Integrations
This section contains details of integration with applications in the SAP Suite, such as SAP Customer Experience, S/4HANA, CRM, ERP, and includes inbound, outbound, and bidirectional integration.
Sales and Service (Inbound) [page 334] Sales Automation (Outbound) [page 352]
Set up the integration of a sales system with SAP Marketing Cloud Financial Data [page 379]
Integration Guide Integration Scenarios
PUBLIC
333
Survey Data [page 383] Personalized Commerce [page 385]
4.5.1 Sales and Service (Inbound)
The integrations below enable you to integrate sales and service data with your system:
SAP ERP For more information, see Integration with SAP ERP [page 349].
SAP Customer Relationship Management (CRM) and SAP Cloud for Customer Enables you, for example, to replicate SAP CRM and SAP Cloud for Customer business partners and business documents. For information about how to set up the integration, see Integration with SAP CRM - Inbound Channel [page 342] and Integration with SAP Cloud for Customer - Inbound Channel [page 338].
External Sales Systems Depending on the data model of the external sales system, business partners and business documents can be replicated. For more information, see Integration with External Sales Systems - Inbound Channel [page 346].
SAP Customer Activity Repository retail applications bundle For more information, see SAP Customer Activity Repository retail applications bundle [page 352].
Available Integration Scenarios and their Business Partner Replication
Scenario
Business Partner Transfer Set-Up Guide
Integration Technology
Marketing Collaboration with
SAP Cloud for Customer
Sales Cloud
SAP Marketing Cloud
Setting Up SAP Marketing Cloud Integration with SAP Cloud for Customer (1J9)
SOAP
Lead2Cash
SAP Master Data Service
for Business Partners SAP S/4HANA, SAP Cloud for Customer, SAP Marketing
Cloud etc.
Integration of SAP Marketing SOAP Cloud with SAP Master Data Service for Business Partners
Marketing Collaboration with
SAP CRM SAP
SAP CRM
Marketing Cloud
Setting Up SAP CRM Integra OData tion with SAP Marketing Cloud (1NP)
Order Management
SAP ERP Cloud
SAP Marketing Setting Up SAP ERP Integra tion with SAP Marketing Cloud (1KW)
OData
SAP S/4HANA SAP Marketing Cloud
Setting Up SAP S/4HANA Cloud Integration with SAP Marketing Cloud (1UG)
334
PUBLIC
Integration Guide Integration Scenarios
4.5.1.1 SAP Master Data Service for Business Partners
Integration of SAP Marketing Cloud with SAP Master Data service for business partners You can use SAP Master Data service for business partners for storing all your business partners and their master data. With the integration of SAP Master Data service for business partners, you can not only replicate business partners and their relationship to SAP Marketing Cloud, but also to other systems like SAP Cloud for Customer. With SAP Master Data service for business partners, you can also leverage the multiple relationships a contact can have within or across different companies.
For the integration setup with SAP Master Data service for business partners, you have the following two options:
1. You are guided by the Cloud Integration Automation Service (see the SAP Help Portal at Introduction to Cloud Integration Automation Service) by making use of the Maintenance Planner.
2. You use the integration setup of SAP Master Data service for business partners with SAP Marketing Cloud (see SAP Master Data for business partners Integration with SAP Marketing Cloud , or Integration of SAP Marketing Cloud with SAP Master Data service for business partners).
This integration supports advanced B2B Marketing using business partner and business partner relationships between corporate contacts and accounts. It loads the business partner data from an SAP S/4HANA system or
Integration Guide Integration Scenarios
PUBLIC
335
an SAP Cloud for Customer system into SAP Marketing Cloud, extracting the local business partners and business partner relationships into interaction contacts. In addition, the following features are offered:
Postal address of a contact within a company that is updated on a daily basis. If a contact has more than one relationship defined, for example marketing lead and president of DSAG, the relationship with the highest ID is selected.
Extraction of future time slices of time-dependent business partner data. This allows you to target marketing activities like campaigns only at contacts that are relevant at that specific point in time.
Several Extensibility Options (see Extensibility for SAP Business Partner Integration)
The following graphic shows an overview of the integration:
For a full description of how to set up an integration with SAP S/4HANA Cloud, see Setting Up SAP S/4HANA Cloud Integration with SAP Marketing Cloud (1UG) or the corresponding section of the Cloud Integration Automation Service in Maintenance Planner.
For a full description of how to set up an integration with SAP Cloud for Customer, see Setting Up SAP Marketing Cloud Integration with SAP Cloud for Customer (1J9) or the corresponding section of the Cloud Integration Automation Service in Maintenance Planner.
4.5.1.2 Presales / Sales
Set up the integration of a sales system with SAP Marketing Cloud
SAP Marketing Cloud can be integrated with SAP CRM, SAP Cloud for Customer, or an external sales system via SAP Cloud Integration.
Parallel Integration of Presales/Sales Systems
Note
You can set up the integration with SAP CRM, SAP Cloud for Customer, and an external sales system simultaneously, but only with one system of a target system type at a time. That is, you can integrate one system for SAP CRM, one for SAP Cloud for Customer, and one external sales system.
In case you have activated more than one communication arrangement, that is, you have configured more than one target system, the Business Add-In (BAdI) Lead Management: Determine Target System Type is performed. With the Custom Logic app, you can implement the BAdI. You define the target system type (either SAP_C4C or SAP_CRM or SALES_EXT) depending on different attributes of the contact that is
336
PUBLIC
Integration Guide Integration Scenarios
currently in process. The BAdI is performed once for each member of the target group. That is, you define in which target system the correspondings leads or activities are created. For more information,see Custom Logic.
The following graphic provides you with an overview of the parallel integration options:
Target Group members can be of different origin, that is,. some from SAP Cloud for Customer, others from SAP Customer Relationship Management or External Sales Systems.
BAdI: During campaign execution, the BAdI determines the target system in which a lead and/or activity shall be created according to the implemented default or custom logic.
The BAdI default implementation has to be replaced by custom logic.
Integration takes place in two directions:
Inbound, from presales / sales to marketing Outbound, from marketing to presales / sales
For more information, see:
Integration with SAP CRM - Inbound Channel [page 342] Integration with SAP Cloud for Customer - Inbound Channel [page 338] Integration with External Sales Systems - Inbound Channel [page 346] Integration with SAP CRM - Outbound Channel [page 354] Integration with SAP Cloud for Customer - Outbound Channel [page 361]. Integration with External Sales Systems - Outbound Channel [page 374]
For more information about the integration setup of SAP Cloud for Customer with SAP Marketing Cloud, see the Integration Guide on SAP API Hub at SAP Cloud for Customer Integration with SAP Marketing , or Purpose.
For more information about the integration setup of SAP Marketing Cloud and SAP CRM, see the Set-Up Instructions on SAP API Hub at SAP CRM Integration or Overview.
Integration Guide Integration Scenarios
PUBLIC
337
4.5.1.2.1 SAP Customer Data Cloud and SAP Marketing Cloud
SAP Customer Data Cloud is a provider of customer identity management. With its solutions SAP Customer Identity, SAP Customer Consent, and SAP Customer Profile you can collect and replicate contact profiles to SAP Marketing Cloud. The integration enables you to add SAP Customer Data Cloud first-party, permission-based user information into the SAP Marketing Cloud platform, and turn it into actionable data for audience segmentation, targeted marketing, and more. The integration is based on exporting data from SAP Customer Data Cloud, using the corresponding integration package on SAP Cloud Integration (see the SAP API Hub at SAP Customer Data Cloud Integration with SAP Marketing Cloud ). SAP Customer Identity manages the customers, SAP Customer Consent manages the consent, SAP Customer Profile connects this data into various channels, including SAP Marketing Cloud. For more information, see the SAP Customer Data Cloud documentation on the SAP Help Portal at SAP Marketing Cloud Integration with SAP Customer Data Cloud.
4.5.1.2.2 Integration with SAP Cloud for Customer Inbound Channel
Data transfer from sales to marketing. By integrating SAP Marketing Cloud, and SAP Cloud for Customer, the bridge between marketing and sales is built so that processes can be harmonized across marketing and sales channels. With sharing the same business partner, and business document data, Marketing is able to deeper support sales in the process of converting potential buyers and interested persons to real buyers. The integration between SAP Marketing Cloud, and SAP Cloud for Customer supports the following business scenarios: Lead Transfer Call Qualification Marketing-Driven Sales Enablement In addition, the transfer of campaign data is possible for started campaigns.
338
PUBLIC
Integration Guide Integration Scenarios
Data Replication from Sales to Marketing (Inbound)
From SAP Cloud for Customer, the system replicates the following data to SAP Marketing Cloud via initial and delta load:
Business Partners Contacts Accounts Individual Customers Business Partner Relationships
Business Documents Leads including product items Opportunities including product items, and product categories Activities of type Phone Call, Appointment, Task, and Visit
Note
In SAP Marketing Cloud, interactions are stored for tasks. So, from SAP Cloud for Customer, the replication of marketing-driven tasks is enabled. Tasks created in the sales system, cannot be replicated.
Marketing Attribute Categories Master data (marketing attribute sets and marketing attributes) Assignments of marketing attribute sets including attribute values and attribute value descriptions to business partners For more information about the transfer of marketing attributes from SAP Cloud for Customer to marketing, see Transferring Marketing Attributes [page 341].
Marketing Permissions In marketing, the permissions are stored on contact and account level. The replication takes place once via initial load. For more information about the processing of marketing permissions, see Permission Marketing.
Custom Fields for Interactions Custom fields for interactions that are created in SAP Cloud for Customer can also be transferred to marketing. To learn more about how to create custom fields in SAP Cloud for Customer, see How to Extend SAP Cloud Integration. For more information on how to extend SAP Marketing Cloud, see the extensibility guide, Custom Fields for the Integration with SAP Cloud for Customer.
Custom Fields for Business Partners and Interaction Contacts
In marketing, you can analyze data imports via the Import Monitor [page 404].
Integration
You can set up the integration between SAP Marketing Cloud with SAP Cloud for Customer via SAP Cloud Integration. For the setup you have the following two options: 1. You are guided by the Cloud Integration Automation Service (see the SAP Help Portal at Introduction to
Cloud Integration Automation Service) by making use of the Maintenance Planner.
Integration Guide Integration Scenarios
PUBLIC
339
2. You use the integration setup of SAP Cloud for Customer with SAP Marketing Cloud (see SAP Cloud for Customer Integration with SAP Marketing , or Setting Up SAP Marketing Cloud Integration with SAP Cloud for Customer (1J9).
The following figure shows an overall integration overview:
Integration of SAP Marketing Cloud with Presales or Sales for Marketing-Driven Leads, Call Center Campaigns, and Activities
For more information about the campaign-based lead creation process, see Handling Leads. For more information about the process of lead creation via a call center campaign, see Telephone Campaigns in SAP Cloud for Customer. For more information about the process of campaign-based activity creation, see Handling Activities.
Navigation, and Display Options
In SAP Marketing Cloud Information about leads, activities, and phone calls created in SAP Cloud for Customer via marketing campaigns, and replicated data from SAP Cloud for Customer is displayed in marketing on the corresponding contact, or account in Interactions. Leads and opportunities, both marketing-driven and sales-created, are additionally visible on contact, and account level under Leads Sales Pipeline . The system provides you with navigation links to SAP Cloud for Customer for the corresponding objects. On the related campaign, the system displays the marketing-driven objects created in SAP Cloud for Customer under Performance. In the Lead Dashboard, KPIs for marketing-driven, and sales-created objects are displayed.
In SAP Cloud for Customer In SAP Cloud for Customer, you can display campaign data. For more information, see Sales Insights on Marketing Campaigns [page 363]
340
PUBLIC
Integration Guide Integration Scenarios
Related Information
Lead Campaigns Marketing-Driven Sales Enablement Call Qualification Displaying Lead Information for Contacts Displaying Lead Information for Accounts Lead Dashboard Marketing Attribute Categories Transferring Marketing Attributes [page 341] Business Documents [page 661]
4.5.1.2.2.1 Business Partner Replication
Note
You can replicate the business partners in two different ways: 1. The replication can be done based on SOA.
For more information about SOA-based replication of Business Partners and Business Partner Relationships, see Replicating Business Partner with SOAP. 2. You can use the integration with SAP Master Data service for business partners. For more information, see SAP Master Data Service for Business Partners [page 335]. You can also extend the SAP business partner integration. For more information, see Extensibility for SAP Business Partner Integration.
4.5.1.2.2.2 Transferring Marketing Attributes
Transfer of marketing attributes and business partner assignments from SAP Cloud for Customer to SAP Marketing Cloud.
Marketing attributes and their assignments to business partners are transferred from SAP Cloud for Customer to SAP Marketing Cloud in two steps, as described in the following table:
Transfer of Marketing Attributes Transfer of
From SAP Cloud for Customer
To SAP Marketing Cloud
Master Data
Marketing Attribute Sets Marketing Attributes
Marketing Attribute Categories
Integration Guide Integration Scenarios
PUBLIC
341
Transfer of Business Partner Assignments
From SAP Cloud for Customer
To SAP Marketing Cloud
Marketing Attributes Sets, including: Marketing Attribute Values
Marketing Attribute Values Marketing Attribute Value Descrip
tions
Integration
In Marketing, marketing attributes categories and marketing attribute values are visible in Personal Data of contacts, accounts, or individual customers. Marketing attribute categories, and marketing attribute values can be used in segmentation.
Note
Marketing attribute categories always have a text in the system language. If no text is transferred from SAP Cloud for Customer the system automatically creates a text in the system language from the ID.
Ensure that all attributes in SAP Cloud for Customer are named differently. Attributes with the same name cause an error that can be monitored in the Import Monitor [page 404].
To prevent from overwriting attribute values, do not use the same attribute in different attribute sets in SAP Cloud for Customer.
Changes of master data and business partner assignments in Sales are automatically transferred to Marketing.
Related Information
Segmentation Contacts
4.5.1.2.3 Integration with SAP CRM - Inbound Channel
Data transfer from sales to marketing. By integrating SAP Marketing Cloud with SAP CRM, you can trigger the creation of leads and activities in SAP CRM via a marketing campaign. Furthermore this integration enables the replication of business partner, and business document data from SAP CRM to SAP Marketing Cloud. You can set up the integration of SAP CRM with SAP Marketing Cloud via SAP Cloud Integration. The integration between SAP Marketing Cloud, and SAP CRM supports the following business scenarios: Lead Transfer Marketing-Driven Sales Enablement
342
PUBLIC
Integration Guide Integration Scenarios
Data Replication from Sales to Marketing (Inbound)
From SAP CRM, the system replicates the following data to SAP Marketing Cloud via initial and delta load:
Business Partners Contacts Accounts Individual Accounts
Business Documents Leads Opportunities Activities of type Planned Call, Appointment, and Task (marketing-driven tasks only) Leads, and activities created in SAP CRM via marketing campaign are created as business documents in SAP CRM.
Note
In SAP Marketing Cloud, interactions are stored for tasks. So, from SAP CRM, the replication of marketing tasks is enabled. Tasks created in the sales system, are not replicated.
Marketing Attributes For more information about the configuration, see Configuration of CRM Marketing Attribute Replication Integration Flow.
Custom fields Custom fields created in SAP CRM can also be transferred to marketing. To learn more about how to create custom fields in SAP CRM, see How to Extend SAP CRM: Purpose of this Document. For more information on how to extend SAP Marketing Cloud, see the extensibility guide, Custom Fields for the Integration with SAP CRM.
Marketing Permissions In marketing, the permissions are stored on contact and account level. The replication takes place once via initial load. For more information about the processing of marketing permissions, see Permission Marketing. For information on how to set up the transfer of marketing permissions from SAP CRM, see Initial Load of Marketing Permissions from SAP Customer Relationship Management to SAP Marketing Cloud , in the SAP Community.
In marketing, you can analyze data imports by the Import Monitor [page 404].
Integration Guide Integration Scenarios
PUBLIC
343
Integration
The following figure shows an overall integration overview:
Integration of SAP CRM with SAP Marketing Cloud
For a full description of the integration setup of SAP Marketing Cloud and SAP CRM, see the Set-Up Instruction on SAP API Hub at SAP CRM Integration or Overview.
Navigation, and Display Options
In SAP Marketing Cloud, information about leads, and activities created in SAP CRM via marketing campaigns, and replicated data from SAP CRM is displayed in Marketing on the corresponding contact, or account in Interactions. Leads and opportunities, both marketing-driven and sales-created, are additionally visible on contact, and account level under Leads Sales Pipeline . The system provides you with navigation links to SAP CRM for the corresponding objects. On the related campaign, the system displays the marketing-driven objects created in SAP CRM under Performance. In the Lead Dashboard, KPIs for marketing-driven, and sales-created objects are displayed.
Related Information
Lead Campaigns Marketing-Driven Sales Enablement Displaying Lead Information for Contacts Displaying Lead Information for Accounts Lead Dashboard Handling Leads Handling Activities Business Documents [page 661]
344
PUBLIC
Integration Guide Integration Scenarios
4.5.1.2.3.1 Business Partner Replication
The replication of business partners and relations from SAP CRM to SAP Marketing Cloud is processed by the following principle: Initial load of all SAP CRM accounts, contacts, individual accounts person to SAP Marketing Cloud
according to your selection with the initial setup of the integration. Delta load of new SAP CRM accounts, contacts, individual accounts to SAP Marketing Cloud as soon as
those objects are created. Delta load of changed SAP CRM accounts, contacts, individual accounts to SAP Marketing Cloud as soon
as those objects are changed.
4.5.1.2.3.2 Transferring Marketing Attributes
Transfer of marketing attributes and business partner assignments from SAP CRM to marketing.
Marketing attributes and their assignments to business partners are transferred from SAP CRM to SAP Marketing Cloud in two steps, as described in the following table:
Transfer of Marketing Attributes Transfer of
From SAP CRM
To SAP Marketing Cloud
Master Data
Marketing Attributes
Marketing Attribute Categories
Business Partner Assignments
Marketing Attributes, including:
Marketing Attribute Values
Marketing Attribute Values Marketing Attribute Value Descrip
tions
Integration
In Marketing, marketing attributes categories and marketing attribute values are visible in Personal Data of contacts, accounts, or individual customers. Marketing attribute categories, and marketing attribute values can be used in segmentation. Changes of master data and business partner assignments in Sales are automatically transferred to Marketing.
Integration Guide Integration Scenarios
PUBLIC
345
4.5.1.2.4 Integration with External Sales Systems - Inbound Channel
Data transfer from external sales systems to marketing. By integrating SAP Marketing Cloud with external sales systems, the bridge between marketing and sales is built so that processes can be harmonized across marketing and sales channels.
Caution
For the integration of SAP Marketing Cloud with external sales systems, we do not deliver standard content.
Note
You can also use the integration with Salesforce offered by Advantco International LLC. For more information, see SAP Marketing Cloud Integration with Salesforce .
Inbound Processes from an External Sales System to Marketing
Depending on the data model of an external sales system, the following data can be replicated to SAP Marketing Cloud. Business Partners Business Documents, such as leads, opportunities, or activities Business documents can be imported from external sales systems to SAP Marketing Cloud via the standard OData service Import of Business Documents (Interactions) (CUAN_BUSINESS_DOCUMENT_IMP_SRV). Business partners can be imported from external sales systems to SAP Marketing Cloud via the standard OData services Marketing - Interaction Contacts (API_MKT_INTERACTION_CONTACT_SRV), Marketing Contacts ( API_MKT_CONTACT_SRV), and Marketing - Corporate Accounts (API_MKT_CORPORATE_ACCOUNT_SRV). For more information on OData services, see SAP API Business Hub under Artifacts . In marketing, you can analyze data imports via the Import Monitor [page 404].
Integration
You can set up the integration between SAP Marketing Cloud with an external sales system via SAP Cloud Integration.
346
PUBLIC
Integration Guide Integration Scenarios
The following figure shows a possible overall integration overview based on a customer-owned integration setup:
Integration of SAP Marketing Cloud with External Sales Systems
4.5.1.2.4.1 Setting Up the Connection Between Marketing and an External Sales System
Connect SAP Marketing Cloud with an external sales system.
Before doing the configuration in SAP Marketing Cloud, you need the administrator business user, which contains the business catalog SAP_CORE_BC_COM (Communication Management), for example the business role SAP_BR_ADMINISTRATOR (Administrator).
As an administrator, you maintain the setup via the following apps under Communication Management:
Maintain Communication User For more information, see Creating a Communication User for Inbound Communication [page 376].
Communication Systems For more information, see Setting Up a Communication System for the Integration of an External Sales System [page 377].
Communication Arrangements For more information, see Setting Up a Communication Arrangement for the Integration of an External Sales System [page 378].
4.5.1.3 Order Management
Order Management Data Replication to SAP Marketing Cloud [page 348] Integration with SAP S/4HANA Cloud and SAP S/4HANA
Integration with SAP ERP [page 349] Integration of SAP ERP with SAP Marketing Cloud using SAP Cloud Integration
Integration Guide Integration Scenarios
PUBLIC
347
4.5.1.3.1 Order Management Data Replication to SAP Marketing Cloud
Integration with SAP S/4HANA Cloud and SAP S/4HANA
By integrating SAP Marketing Cloud and SAP S/4HANA Cloud or SAP S/4HANA, customers can use customer and contact data, as well as their relations and address data for Marketing campaigns.
Using the SAP Cloud Integration as standard middleware content, customers benefit from SAP cloud integration standards for security, performance, data integrity, and robustness.
On SAP S/4HANA-side the exchange is done via Business Partner SOA services MDGK_BP_RPLCTRQ and MDG_BP_RELATIONSHIP_OUT.
On Marketing-side the interface CUAN_BUSINESS_PARTNER_IMPORT is used, see Import Business Partners [page 574].
Note
If you have an integration of SAP S/4HANA Enterprise with SAP Marketing Cloud in place, deletion or the end of purpose of a customer or corporate contact on the SAP S/4HANA Enterprise side is not automatically replicated to SAP Marketing Cloud. To ensure deletion in SAP Marketing Cloud, you have to do the following:
1. Run the application job Flag Contact IDs for Deletion with the following parameters: specify the Origin of Contact and the ID of Contact, and select the parameter Origin IDs with Dep. IDs Too.
2. Finally, you also have to run the application job Delete Flagged Contact IDs.
348
PUBLIC
Integration Guide Integration Scenarios
For the integration setup with SAP S/4HANA Cloud, you have the following two options: 1. You are guided by the Cloud Integration Automation Service (see the SAP Help Portal at Introduction to
Cloud Integration Automation Service) by making use of the Maintenance Planner. 2. You use the integration setup of SAP S/4HANA Cloud with SAP Marketing Cloud (see SAP S/4HANA Cloud
Integration with SAP Marketing Cloud , or Setting Up SAP S/4HANA Cloud Integration with SAP Marketing Cloud (1UG)). For the integration setup with SAP S/4HANA, you can find a full description: Setting Up SAP S/4HANA Integration with SAP Marketing Cloud (23L).
4.5.1.3.2 Integration with SAP ERP
Integration of SAP ERP with SAP Marketing Cloud using SAP Cloud Integration By integrating SAP Marketing Cloud and SAP ERP, customers can use valuable data from the on premise SAP ERP system in Business-To-Business (B2B) and Business-To-Customer (B2C) business scenarios. This includes customer, contact and product data, as well as sales volume data like quotes, orders, and returns. Customers can, for example, launch campaigns for the customers and contacts, or use information on sales volume to determine the best customers for campaigns. If specific contacts, customers, and consumers are set to blocked in the source system, the respective customers, contacts, and consumers are flagged with end of purpose in the marketing system. They are then no longer visible and cannot be used in business processes in marketing.
Integration is done using SAP Cloud Integration middleware and the OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV, seeImport Business Partners [page 574].
Extensibility enables customers to transfer additional data of customers, contacts, and sales orders from SAP ERP to SAP Marketing Cloud. Additional fields for this purpose must be enabled in the Custom Fields app for the service CUAN_BUSINESS_PARTNER_IMPORT_SRV.
You can find a full description of how to set up this integration in: Setting Up SAP ERP Integration with SAP Marketing Cloud (1KW).
Integration Guide Integration Scenarios
PUBLIC
349
4.5.1.4 Integrating Service Tickets
Replicate Service Tickets from SAP Service Cloud to SAP Marketing Cloud. By replicating service tickets from SAP Service Cloud to interactions in SAP Marketing Cloud, marketers can use them as signals in marketing. Via the replicated interactions, actions can be triggered in marketing, such as inviting people to surveys, safeguarding the overall customer satisfaction by awards or compensations. Furthermore, they can be used as interruption pointer for campaigns. Service tickets in marketing are important to understand your customer's business needs, for example to trigger campaigns for a new product launch or product replacements.
Prerequisites
The integration of service tickets requires the following preliminary steps: Perform the integration scenario SAP Cloud for Customer Integration with SAP Marketing Cloud.
For more information about the integration setup of SAP Cloud for Customer with SAP Marketing Cloud, see SAP Cloud for Customer Integration with SAP Marketing Cloud . For setup instructions, see Service Ticket Integration. In the Manage Interaction Content configuration app, define a new Interaction Channel for service tickets, named Service. Assign the Communication Medium BUSINESS_DOCUMENT and the Interaction Type SERVICE_TICKET to the interaction channel Service. For more information, see Managing Interaction Content.
Process
Customers can submit requests for service, for example to address a problem in SAP Service Cloud. These service tickets can be replicated to SAP Marketing Cloud and saved in interactions for further marketing actions. The following graphic provides you with an overview about the necessary steps.
350
PUBLIC
Integration Guide Integration Scenarios
To integrate service tickets in SAP Marketing Cloud, perform the following steps:
Download the service category catalog in SAP Service Cloud via Microsoft Excel® file download and upload it in SAP Marketing Cloud as product hierarchy using the Data File Load app. For more information about the import, see Data File Load.
Deploy the standard iFlow on SAP Cloud Integration that service tickets are mapped and loaded as interactions into SAP Marketing Cloud. The following attributes of service tickets are replicated to marketing:
Mapping of Service Ticket Attributes from SAP Service Cloud to Properties of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV of SAP Marketing Cloud
Service Ticket Attribute in SAP Service Cloud
CUAN_BUSINESS_DOCUMENT_IMP_SRV Property in SAP Marketing Cloud
Ticket Buyer Party
Contact ID
Ticket Creation Date Time
Time Stamp
Ticket ID
External ID
Ticket Priority Code
Interaction Priority
The Internal Object Type is not mapped to an attribute in SAP Service Cloud. It has the hard-coded value SERVICE_TICKET. In the integration scenario SAP Cloud for Customer Integration with SAP Marketing Cloud, this value can be adapted in the corresponding iFlow Replicate Service Ticket to SAP Marketing.
Internal Object Type
The External Object Type is not mapped to an attribute in SAP Service Cloud. It has the hard-coded value C4S_SERVICE_TICKET.
External Object Type
Confirmation Issuing Status Code
Status Code
Information Life Cycle Status Code
External Status Code
Service Category
Product Category of type Process Category
Incident Category
Product Category of type Incident Category
Object Category
Product Category of type Object Category
Cause Category
Product Category of type Cause Category
Resolution Category
Ticket Completion Time Point Ticket Creation Date Time
Product Category of type Solution Category
Interaction Processing Duration Is calculated from TicketCompletionTimePoint minus Cre ationDateTime and converted into seconds.
Integration Guide Integration Scenarios
PUBLIC
351
For more information about the structure of this service, see Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV [page 664]. Product hierarchies can be classified in terms of their usage in marketing, that is, whether they are defined for product categories or service categories. The service categories of the service tickets are included as product categories in SAP Marketing Cloud. They can be classified with category types, that is, to distinguish service processes, root causes, or service solutions. For more information about the attributes on product hierarchies and product categories, see Product Hierarchies and Categories [page 604].
4.5.1.5 SAP Customer Activity Repository retail applications bundle
The integration of SAP Customer Activity Repository enables you to import of POS transactions, such as sales order and sales returns as interactions.
You can use then this data in various process steps like segmentation, customer fact sheet, product recommendation, and trigger based campaigns.
As a prerequisite you have uploaded the relevant master data to SAP Marketing Cloud, such as contacts, products, and marketing locations.
Note
Keep in mind that this integration works only with SAP Customer Activity Repository retail applications bundle (CARAB) 2.0 FP1.
For more information, see: SAP Customer Activity Repository applications bundle Integration with SAP ERP [page 349] OData services
Products [page 582] Product Hierarchies and Categories [page 604] Contacts [page 412] Import Business Partners [page 574]
4.5.2 Sales Automation (Outbound)
Set up the integration of a sales system with SAP Marketing Cloud SAP Marketing Cloud can be integrated with SAP CRM, SAP Cloud for Customer, or an external sales system via SAP Cloud Integration. Parallel Integration of Presales/Sales Systems
352
PUBLIC
Integration Guide Integration Scenarios
Note
You can set up the integration with SAP CRM, SAP Cloud for Customer, and an external sales system simultaneously, but only with one system of a target system type at a time. That is, you can integrate one system for SAP CRM, one for SAP Cloud for Customer, and one external sales system.
In case you have activated more than one communication arrangement, that is, you have configured more than one target system, the Business Add-In (BAdI) Lead Management: Determine Target System Type is performed. With the Custom Logic app, you can implement the BAdI. You define the target system type (either SAP_C4C or SAP_CRM or SALES_EXT) depending on different attributes of the contact that is currently in process. The BAdI is performed once for each member of the target group. That is, you define in which target system the correspondings leads or activities are created. For more information,see Custom Logic.
The following graphic provides you with an overview of the parallel integration options:
Target Group members can be of different origin, that is,. some from SAP Cloud for Customer, others from SAP Customer Relationship Management or External Sales Systems.
BAdI: During campaign execution, the BAdI determines the target system in which a lead and/or activity shall be created according to the implemented default or custom logic.
The BAdI default implementation has to be replaced by custom logic.
Integration takes place in two directions:
Inbound, from presales / sales to marketing Outbound, from marketing to presales / sales
For more information, see:
Integration with SAP CRM - Inbound Channel [page 342] Integration with SAP Cloud for Customer - Inbound Channel [page 338] Integration with External Sales Systems - Inbound Channel [page 346] Integration with SAP CRM - Outbound Channel [page 354] Integration with SAP Cloud for Customer - Outbound Channel [page 361]. Integration with External Sales Systems - Outbound Channel [page 374]
For more information about the integration setup of SAP Cloud for Customer with SAP Marketing Cloud, see the Integration Guide on SAP API Hub at SAP Cloud for Customer Integration with SAP Marketing , or Purpose.
Integration Guide Integration Scenarios
PUBLIC
353
For more information about the integration setup of SAP Marketing Cloud and SAP CRM, see the Set-Up Instructions on SAP API Hub at SAP CRM Integration or Overview.
4.5.2.1 Integration with SAP CRM - Outbound Channel
Data transfer ftom marketing to sales.
Data Replication from Marketing to Sales (Outbound)
From SAP Marketing Cloud, the system triggers the creation of the following data in SAP CRM:
Business Partners If the business partner is not known in SAP CRM, the system creates a business partner, account, contact, individual customer, in SAP CRM.
Note
Only during the process of lead creation via marketing campaign, business partners are created in sales. Ensure that business partners in Marketing that are part of the lead creation process, the Country is filled. Otherwise, no business partner, and no lead is created in SAP CRM.
The address of a contact is not replicated into SAP CRM. The system uses the standard address of the related account.
Before creating business documents, the system creates accounts, and contacts in SAP CRM with the origin ID from Marketing.
Business Documents Leads The system enriches the transferred marketing data during each lead transfer. For more information see Augmented Lead Context [page 355]. Activities of type Planned Call, Appointment, and Task The system enriches the transferred marketing data during each activity transfer. For more information see Augmented Activity Context [page 359].
Note
For leads and activities transferred to SAP CRM, the system also sends out the assigned marketing area. As no mapping is performed in SAP Cloud Integration, the marketing area gets lost during the confirmation process from SAP CRM to SAP Marketing Cloud.
Custom Fields Created in Marketing. Custom fields created in marketing can also be transferred to SAP CRM. For more information on how to extend SAP Marketing Cloud, see the extensibility guide, Custom Fields for the Integration with SAP CRM. To make marketing-created custom fields available in SAP CRM, you have to ensure that the standard mapping is extended in SAP Cloud Integration.
354
PUBLIC
Integration Guide Integration Scenarios
Integration
The following figure shows an overall integration overview:
Integration of SAP CRM with SAP Marketing Cloud
For a full description of the integration setup of SAP Marketing Cloud and SAP CRM, see the Set-Up Instruction on SAP API Hub at SAP CRM Integration or Overview.
Related Information
Lead Campaigns Marketing-Driven Sales Enablement Displaying Lead Information for Contacts Displaying Lead Information for Accounts Lead Dashboard Handling Leads Handling Activities Business Documents [page 661]
4.5.2.1.1 Augmented Lead Context
Enhancement of lead information to be transferred to sales. Via augmented lead context, sales representatives are provided with context-related lead information that helps to prioritize the sequence of lead processing, and that allows more specified follow-up activities. Augmented lead context is relevant for the integration with SAP CRM and SAP Cloud for Customer. For a lead triggered by marketing, the sales representative wants to know the context of this creation, that can be a product: Requested as a sample by an interested party Clicked on by an interested party in a marketing email
Integration Guide Integration Scenarios
PUBLIC
355
The following use case illustrates the dependencies:
A customer requests a sample, or adds a product to a wishlist. In marketing, you can trigger lead creation in sales, including the product information (product item). The transfer of product information is based on the product of the trigger event of the marketing campaign for lead creation in sales.
Note
During an integration with SAP Cloud for Customer, the system only transfers product items for product origin SAP_C4C_PRODUCT.
To drive lead acceptance and conversion probability in sales, during lead transfers, additional and custom attributes from the following objects are transferred together with the lead:
Predecessor interaction Business partner Campaign Lead score
The system transfers Score Builder scores that you can create by yourself, and the delivered Account Engagement Score based on a predictive model.
Predecessor Interaction Information
During each transfer of leads to sales via marketing campaign, the system enriches the transferred content by predecessor interaction information.
This interaction contains a range of attributes listed below. Additionally, it contains the subnodes Products and Item Of Interest with a table of attributes each.
Attributes Origin of Interaction Contact Data External ID of Interaction Contact Data Can contain the email address of a contact Interaction Reason Description of Interaction Reason Marketing Area ID Communication Medium Interaction Type Description of Interaction Type Interaction Content Campaign ID Interaction Content Subject Object Type Generic Object ID Interaction Source System Type Interaction Source System ID Generic Object ID
356
PUBLIC
Integration Guide Integration Scenarios
Business Document Status Code Uniform Resource Identifier UTC Time Stamp in Long Form (YYYYMMDDhhmmssmmmuuun) Subnodes Products
Contains the attributes ProductId and ProductOrigin; it can contain 0 to N values of this attribute combination. Item of interest Contains the attributes ItemOfInterest and ItemOfInterestName; it can contain 0 to N values of this attribute combination.
Note
Predecessor interaction information of products is transferred with the lead depending on the assigned sales system type:
Products of SAP CRM are replicated to SAP CRM. Products of SAP Cloud for Customer are replicated to SAP Cloud for Customer. For external systems, products to be transferred are not filtered. That is, all products, such as ERP
products, are replicated to an external system.
As a prerequisite, there is a predecessor action, or trigger defined to the action Create Lead. The following options are possible: The predecessor interaction contains additional existing fields, such as Product.
The system replicates additional fields during lead transfer, together with the lead. To add those fields to applicable fields in sales, mapping to sales fields must be defined. The predecessor interaction contains custom fields. The system replicates the custom fields during lead transfer. To add those fields to applicable fields in sales, mapping to sales fields must be defined.
Note
Only the attributes and not the subnodes can be extended by custom fields in SAP Marketing Cloud.
Business Partner Information
For lead transfers where no corresponding business partner exists in sales, the system transfers additional existing, and custom fields of the account, contact, or consumer.
During an integration with SAP Cloud for Customer, also for the creation of call qualification leads in sales, the system transfers additional existing, and custom fields of the account, contact, or consumer.
To add those fields to applicable fields in sales, mapping to sales fields must be defined.
Integration Guide Integration Scenarios
PUBLIC
357
Campaign Information
The system replicates custom fields on campaigns to the outbound message of the lead, so that this information can be mapped to the business document in sales. To add those fields to applicable fields in sales, mapping to sales fields must be defined.
Lead Scores
During each transfer of leads to sales via marketing campaign, or via lead transfer, the system enriches the transferred content for leads by lead score information (ID, name, value) for each contact of the assigned target group. That is, scores are added to the lead outbound message. During an integration with SAP Cloud for Customer, the system also enriches the transferred content for call qualification leads by lead score information (ID, name, value) for each contact of the assigned target group. To add those fields to applicable fields in sales, mapping to sales fields must be defined. Lead scores can be calculated regularly. As an administrative user or analyst, you can determine in the Rule Model how often a score is persisted, how many versions exist, when to delete older versions. The system replicates the most recent persisted version.
Note
As a prerequisite for transfer of scores, in the Score Builder, ensure the following: Set Client Application to Augmented Lead Context In the rule set of the score, leave Applicable For empty. The score must be persisted. This means the score must be saved either daily, weekly, or monthly. In case there is more than one rule model for a score, the system considers the last changed rule
model.
Related Information
Score Builder Custom Fields in Campaign Custom Fields Integration with SAP CRM - Outbound Channel [page 354] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
358
PUBLIC
Integration Guide Integration Scenarios
4.5.2.1.2 Augmented Activity Context
Enhancement of activity information to be transferred to sales.
Via augmented activity context, sales representatives are provided with context-related activity information that helps to prioritize the sequence of activity processing, and that allows more specified follow-up actions.
For an activity triggered by marketing, the sales representative wants to know the context of this creation that can be a product: Requested as a sample by an interested party Clicked on by an interested party in a marketing email
To drive activity acceptance in sales, during activity transfers, additional, and custom attributes from the following objects are transferred together with the activity: Predecessor interaction Campaign
Predecessor Interaction Information
During each transfer of leads to sales via marketing campaign, the system enriches the transferred content by predecessor interaction information.
This interaction contains a range of attributes listed below. Additionally, it contains the subnodes Products and Item Of Interest with a table of attributes each.
Attributes Interaction Contact Origin Interaction Contact ID Can contain the email address of a contact Interaction Reason Interaction Reason Name Interaction Contact Marketing Area Communication Medium Interaction Type Interaction Type Name Content Data Campaign ID Interaction Content Subject Interaction Content Object Source Interaction Content Object ID Source System Type Source System Interaction Source Object Additional ID Interaction Source Object Status Interaction Source Data URL Interaction Source Time Stamp UTC
Integration Guide Integration Scenarios
PUBLIC
359
Subnodes Products Contains the attributes ProductId and ProductOrigin; it can contain 0 to N values of this attribute combination. Item of interest Contains the attributes ItemOfInterest and ItemOfInterestName; it can contain 0 to N values of this attribute combination.
Note
Predecessor interaction information of products is transferred with the activity depending on the assigned sales system type:
Products of SAP CRM are replicated to SAP CRM. Products of SAP Cloud for Customer are replicated to SAP Cloud for Customer. For external systems, products to be transferred are not filtered. That is, all products, such as ERP
products, are replicated to an external system.
As a prerequisite, there is a predecessor action, or trigger defined to the action for activity creation, such as Create Task. The following options are possible:
The predecessor interaction contains additional existing fields. The system replicates additional fields during activity transfer, together with the activity. So, the sales representative is provided with additional information and is enabled to take further actions on customers. For more information, see also the use case description Creating Tasks in Sales for Missing Marketing Permissions. To add those fields to applicable fields in sales, mapping to sales fields must be defined in SAP Cloud Integration.
The predecessor interaction contains custom fields. The system replicates the custom fields during activity transfer. To add those fields to applicable fields in sales, mapping to sales fields must be defined in SAP Cloud Integration.
Note
Only the attributes and not the subnodes can be extended by custom fields in SAP Marketing Cloud.
Campaign Information
The system replicates custom fields on campaigns to the activity outbound message, so that this information can be mapped to the business document in sales. To add those fields to applicable fields in sales, mapping to sales fields must be defined in SAP Cloud Integration.
Related Information
Custom Fields in Campaign Custom Fields
360
PUBLIC
Integration Guide Integration Scenarios
Integration with SAP CRM - Outbound Channel [page 354] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
4.5.2.2 Integration with SAP Cloud for Customer Outbound Channel
Data transfer from marketing to sales.
Data Replication from Marketing to Sales (Outbound)
From SAP Marketing Cloud the creation of the following data in SAP Cloud for Customer can be triggered:
Business Partners If the business partner is not known in SAP Cloud for Customer business partner in status In Preparation (account, contact, individual customer) is created.
Note
Business partners in status In Preparation are only created in sales during the process of lead creation via marketing campaign.
Before creating business documents, the system creates accounts and contacts in SAP Cloud for Customer with the origin ID from marketing.
Business Documents Leads The system enriches the transferred marketing data during each lead transfer. For more information see Augmented Lead Context [page 355].
Note
For leads and activities transferred to SAP Cloud for Customer, the system also sends out the assigned marketing area. As no mapping is performed in SAP Cloud Integration, the marketing area gets lost when a change in sales is replicated back to marketing.
Campaigns The system transfers basic campaign data to SAP Cloud for Customer for started campaigns. With the Custom Logic app, you can implement the Business Add-In (BAdI) BAdI: Filter for Campaigns to Be Replicated to SAP Cloud for Customer (BAdI CUAN_LM_CAMPAIGN_REPLICATION) to adapt the delivered filters of campaign selection for the transfer to SAP Cloud for Customer. For the initial load of campaigns to SAP Cloud for Customer, you define an application job in the Marketing Application Jobs app. With the application job template Campaigns: Transfer Campaigns to Sales, you specify filters to select campaigns for the transfer to SAP Cloud for Customer. After a downtime in the running system, you can also perform this job. For more information, see Campaigns: Transfer Campaigns to Sales. Filtering of campaigns is done automatically by the system configuration in the Business Add-In (BAdI) BAdI: Filter for Campaigns to Be Replicated toSAP Cloud for Customer ( BAdI
Integration Guide Integration Scenarios
PUBLIC
361
CUAN_LM_CAMPAIGN_REPLICATION). The standard implementation in the BAdI permits the transfer of Blank Campaigns, Email Campaigns, and Mobile Campaigns. The implementation rejects, for example, Transfer Leads Campaigns, Facebook Campaigns and Trigger-Based Campaigns. Custom Fields Created in Marketing Custom fields created in marketing can also be transferred to SAP Cloud for Customer. For more information on how to extend SAP Marketing Cloud, see the extensibility guide, Custom Fields for the Integration with SAP Cloud for Customer. To make marketing-created custom fields available in SAP Cloud for Customer, you have to ensure that the standard mapping is extended in SAP Cloud Integration .
Integration
You can set up the integration between SAP Marketing Cloud with SAP Cloud for Customer via SAP Cloud Integration. For the setup you have the following two options: 1. You are guided by the Cloud Integration Automation Service (see the SAP Help Portal at Introduction to
Cloud Integration Automation Service) by making use of the Maintenance Planner. 2. You use the integration setup of SAP Cloud for Customer with SAP Marketing Cloud (see SAP Cloud for
Customer Integration with SAP Marketing , or Setting Up SAP Marketing Cloud Integration with SAP Cloud for Customer (1J9). The following figure shows an overall integration overview:
Integration of SAP Marketing Cloud with Presales or Sales for Marketing-Driven Leads, Call Center Campaigns, and Activities
For more information about the campaign-based lead creation process, see Handling Leads. For more information about the process of lead creation via a call center campaign, see Telephone Campaigns in SAP Cloud for Customer. For more information about the process of campaign-based activity creation, see Handling Activities.
362
PUBLIC
Integration Guide Integration Scenarios
Business Partner Replication
SAP Marketing Cloud is able to trigger the creation of business partners of type Account, Contact and Individual Customer in SAP Cloud for Customer via lead creation. In case no corresponding business partner exists in SAP Cloud for Customer, a new business partner with the status In Preparation is created.
Related Information
Lead Campaigns Handling Leads Marketing-Driven Sales Enablement Call Qualification Displaying Lead Information for Contacts Displaying Lead Information for Accounts Lead Dashboard Business Documents [page 661]
4.5.2.2.1 Sales Insights on Marketing Campaigns
Provide campaign data to sales representatives in SAP Cloud for Customer.
Use Case
As a sales representative, you want to prepare for a dedicated customer visit, and get an overview about those campaigns that affect your area of responsibility. Therefore, you want to see all campaigns that include at least one of the accounts, or contacts you are responsible for to be able to reinforce the message of the campaigns. Furthermore, you are interested in collaboration with marketing to share campaign-related information.
The following pieces of information coming from a campaign may be valuable for you:
Which campaigns are stopped, or ongoing? You can display details of marketing campaigns, such as name, description, type, and status.
Which accounts, and contacts of my area of responsibility are targeted by those campaigns? You can display those contacts, and accounts that are affected by a dedicated marketing campaign.
Which information is sent by email to a contact? You can open emails a contact has received.
Which campaign-related information is provided by marketing experts? SAP Jam allows you to support online communication, such as discussions with marketing, or other sales people, or sharing collaterals for example. During campaign replication, the system also transfers the ID of the attached SAP Jam group to SAP Cloud for Customer. As a sales representative, you can access the group in the sales system.
Integration Guide Integration Scenarios
PUBLIC
363
Prerequisites
To provide sales representatives with marketing information on campaigns ensure the following: Integration with SAP Cloud for Customer, that is the transfer of contacts and accounts, is set up. Campaign data is transferred to SAP Cloud for Customer. You have configured SAP Jam. For more information see https://help.sap.com/viewer/user_help. You have integrated the relevant campaign with SAP Jam. In SAP Jam, you have invited additional users to
your group to share information with them.
Navigation to Marketing
In SAP Cloud for Customer, the replicated campaign with the addressed contacts or account is displayed. As a sales representative, you can navigate to: Contacts in marketing Campaign in marketing
Collaboration via SAP Jam
Sales representatives and marketing experts collaborate via the same SAP Jam group, that is, they can share campaign collaterals on the SAP Jam group.
In the relevant marketing campaign, under Collaboration SAP Jam , the marketing expert creates or assigns an SAP Jam group. Per campaign, only one group can be assigned, but a group can be reused in multiple campaigns. The feed of the SAP Jam group is displayed on the marketing campaign in SAP Cloud for Customer. Sales representatives and marketing experts can create posts from within the feed. New SAP Jam groups, posts, and feeds created in marketing, sales, or directly in SAP Jam, are always synchronous in those systems.
Display of Emails in Browser
In SAP Cloud for Customer, the sales representative can display individual emails including personalization attributes that are sent to a contact via a marketing email campaign. That is, as a sales representative you have the same view on the emails as the addressee. So, you are enabled to trigger suitable further sales actions. For more information about how to insert the View in Browser link in email templates, see Using Links in Emails and Email Templates.
364
PUBLIC
Integration Guide Integration Scenarios
Related Information
Integration with SAP Cloud for Customer - Inbound Channel [page 338] Campaigns: Transfer Campaigns to Sales Augmented Lead Context [page 355] Campaign Details
4.5.2.2.2 Augmented Lead Context
Enhancement of lead information to be transferred to sales. Via augmented lead context, sales representatives are provided with context-related lead information that helps to prioritize the sequence of lead processing, and that allows more specified follow-up activities. Augmented lead context is relevant for the integration with SAP CRM and SAP Cloud for Customer. For a lead triggered by marketing, the sales representative wants to know the context of this creation, that can be a product: Requested as a sample by an interested party Clicked on by an interested party in a marketing email The following use case illustrates the dependencies: A customer requests a sample, or adds a product to a wishlist. In marketing, you can trigger lead creation in sales, including the product information (product item). The transfer of product information is based on the product of the trigger event of the marketing campaign for lead creation in sales.
Note
During an integration with SAP Cloud for Customer, the system only transfers product items for product origin SAP_C4C_PRODUCT.
To drive lead acceptance and conversion probability in sales, during lead transfers, additional and custom attributes from the following objects are transferred together with the lead: Predecessor interaction Business partner Campaign Lead score
The system transfers Score Builder scores that you can create by yourself, and the delivered Account Engagement Score based on a predictive model.
Predecessor Interaction Information
During each transfer of leads to sales via marketing campaign, the system enriches the transferred content by predecessor interaction information.
Integration Guide Integration Scenarios
PUBLIC
365
This interaction contains a range of attributes listed below. Additionally, it contains the subnodes Products and Item Of Interest with a table of attributes each.
Attributes Origin of Interaction Contact Data External ID of Interaction Contact Data Can contain the email address of a contact Interaction Reason Description of Interaction Reason Marketing Area ID Communication Medium Interaction Type Description of Interaction Type Interaction Content Campaign ID Interaction Content Subject Object Type Generic Object ID Interaction Source System Type Interaction Source System ID Generic Object ID Business Document Status Code Uniform Resource Identifier UTC Time Stamp in Long Form (YYYYMMDDhhmmssmmmuuun)
Subnodes Products Contains the attributes ProductId and ProductOrigin; it can contain 0 to N values of this attribute combination. Item of interest Contains the attributes ItemOfInterest and ItemOfInterestName; it can contain 0 to N values of this attribute combination.
Note
Predecessor interaction information of products is transferred with the lead depending on the assigned sales system type:
Products of SAP CRM are replicated to SAP CRM. Products of SAP Cloud for Customer are replicated to SAP Cloud for Customer. For external systems, products to be transferred are not filtered. That is, all products, such as ERP
products, are replicated to an external system.
As a prerequisite, there is a predecessor action, or trigger defined to the action Create Lead. The following options are possible:
The predecessor interaction contains additional existing fields, such as Product. The system replicates additional fields during lead transfer, together with the lead. To add those fields to applicable fields in sales, mapping to sales fields must be defined.
The predecessor interaction contains custom fields.
366
PUBLIC
Integration Guide Integration Scenarios
The system replicates the custom fields during lead transfer. To add those fields to applicable fields in sales, mapping to sales fields must be defined.
Note
Only the attributes and not the subnodes can be extended by custom fields in SAP Marketing Cloud.
Business Partner Information
For lead transfers where no corresponding business partner exists in sales, the system transfers additional existing, and custom fields of the account, contact, or consumer. During an integration with SAP Cloud for Customer, also for the creation of call qualification leads in sales, the system transfers additional existing, and custom fields of the account, contact, or consumer. To add those fields to applicable fields in sales, mapping to sales fields must be defined.
Campaign Information
The system replicates custom fields on campaigns to the outbound message of the lead, so that this information can be mapped to the business document in sales. To add those fields to applicable fields in sales, mapping to sales fields must be defined.
Lead Scores
During each transfer of leads to sales via marketing campaign, or via lead transfer, the system enriches the transferred content for leads by lead score information (ID, name, value) for each contact of the assigned target group. That is, scores are added to the lead outbound message.
During an integration with SAP Cloud for Customer, the system also enriches the transferred content for call qualification leads by lead score information (ID, name, value) for each contact of the assigned target group.
To add those fields to applicable fields in sales, mapping to sales fields must be defined.
Lead scores can be calculated regularly. As an administrative user or analyst, you can determine in the Rule Model how often a score is persisted, how many versions exist, when to delete older versions. The system replicates the most recent persisted version.
Note
As a prerequisite for transfer of scores, in the Score Builder, ensure the following: Set Client Application to Augmented Lead Context In the rule set of the score, leave Applicable For empty. The score must be persisted. This means the score must be saved either daily, weekly, or monthly.
Integration Guide Integration Scenarios
PUBLIC
367
In case there is more than one rule model for a score, the system considers the last changed rule model.
Related Information
Score Builder Custom Fields in Campaign Custom Fields Integration with SAP CRM - Outbound Channel [page 354] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
4.5.2.2.3 Augmented Activity Context
Enhancement of activity information to be transferred to sales.
Via augmented activity context, sales representatives are provided with context-related activity information that helps to prioritize the sequence of activity processing, and that allows more specified follow-up actions.
For an activity triggered by marketing, the sales representative wants to know the context of this creation that can be a product: Requested as a sample by an interested party Clicked on by an interested party in a marketing email
To drive activity acceptance in sales, during activity transfers, additional, and custom attributes from the following objects are transferred together with the activity: Predecessor interaction Campaign
Predecessor Interaction Information
During each transfer of leads to sales via marketing campaign, the system enriches the transferred content by predecessor interaction information.
This interaction contains a range of attributes listed below. Additionally, it contains the subnodes Products and Item Of Interest with a table of attributes each.
Attributes Interaction Contact Origin Interaction Contact ID Can contain the email address of a contact Interaction Reason Interaction Reason Name
368
PUBLIC
Integration Guide Integration Scenarios
Interaction Contact Marketing Area Communication Medium Interaction Type Interaction Type Name Content Data Campaign ID Interaction Content Subject Interaction Content Object Source Interaction Content Object ID Source System Type Source System Interaction Source Object Additional ID Interaction Source Object Status Interaction Source Data URL Interaction Source Time Stamp UTC Subnodes Products
Contains the attributes ProductId and ProductOrigin; it can contain 0 to N values of this attribute combination. Item of interest Contains the attributes ItemOfInterest and ItemOfInterestName; it can contain 0 to N values of this attribute combination.
Note
Predecessor interaction information of products is transferred with the activity depending on the assigned sales system type:
Products of SAP CRM are replicated to SAP CRM. Products of SAP Cloud for Customer are replicated to SAP Cloud for Customer. For external systems, products to be transferred are not filtered. That is, all products, such as ERP
products, are replicated to an external system.
As a prerequisite, there is a predecessor action, or trigger defined to the action for activity creation, such as Create Task. The following options are possible:
The predecessor interaction contains additional existing fields. The system replicates additional fields during activity transfer, together with the activity. So, the sales representative is provided with additional information and is enabled to take further actions on customers. For more information, see also the use case description Creating Tasks in Sales for Missing Marketing Permissions. To add those fields to applicable fields in sales, mapping to sales fields must be defined in SAP Cloud Integration.
The predecessor interaction contains custom fields. The system replicates the custom fields during activity transfer. To add those fields to applicable fields in sales, mapping to sales fields must be defined in SAP Cloud Integration.
Integration Guide Integration Scenarios
PUBLIC
369
Note
Only the attributes and not the subnodes can be extended by custom fields in SAP Marketing Cloud.
Campaign Information
The system replicates custom fields on campaigns to the activity outbound message, so that this information can be mapped to the business document in sales. To add those fields to applicable fields in sales, mapping to sales fields must be defined in SAP Cloud Integration.
Related Information
Custom Fields in Campaign Custom Fields Integration with SAP CRM - Outbound Channel [page 354] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
4.5.2.2.4 Sales Insights on Marketing Permissions and Subscriptions
Provide marketing permissions and subscriptions and enable editing in SAP Cloud for Customer.
Use Case
As a sales representative, you want to access and change marketing permissions and subscriptions that are created in marketing. For presales and sales employees, when contacting potential and existing customers via phone or email, it is important to know for which address it is allowed to reach the customers. Especially for call center activities, the knowledge about the permissions is essential.
Note
This scenario is only supported for desktops computers and notebooks. Smartphones are not supported and there can be restrictions on tablets.
370
PUBLIC
Integration Guide Integration Scenarios
Permission Marketing in SAP Marketing Cloud
As a marketing expert, you can maintain permissions and subscriptions on contacts or accounts on the respective user interface, on the Permission Marketing tab. In an integrated system landscape, a sales person can edit marketing permissions, in SAP Cloud for Customer. For this use case, SAP Cloud for Customer requests the marketing permissions from SAP Marketing Cloud and provides the corporate account or contact user interface from marketing for editing marketing permissions by a sales person.
Marketing Permission in SAP Cloud for Customer
In SAP Cloud for Customer, marketing permissions are displayed on SAP Cloud for Customer contacts or accounts under MARKETING PERMISSIONS. By Edit Permissions and Subscriptions, on a sales contact or account, you can navigate to the corresponding marketing contact or account user interface, to the Permission Marketing tab. You can edit the marketing permission in the marketing system. The system updates the permission in sales, accordingly.
Note
By default, in SAP Cloud for Customer the MARKETING PERMISSIONS facet does not show the General section and the URL for editing the permissions. To make it visible, proceed as follows: 1. Choose Adapt Edit Master Layout . 2. Go to MARKETING PERMISSIONS. 3. Add section General. 4. In section General, choose mashup Edit Permissions and Subscriptions. 5. Choose Adapt End Layout Changes .
So, permissions in SAP Cloud for Customer and in SAP Marketing Cloud are synchronous. Sales employees in SAP Cloud for Customer are provided with the same view at the permissions as their marketing counterparts.
Tip
It might be required to replicate existing permissions via initial load from SAP Cloud for Customer to SAP Marketing Cloud, and after that, editing permissions shall only be done in marketing.
Related Information
Permission Marketing in the Contact Profile Integration with SAP Cloud for Customer - Inbound Channel [page 338] Integration with SAP Cloud for Customer - Outbound Channel [page 361]
Integration Guide Integration Scenarios
PUBLIC
371
4.5.2.2.5 Sales Insights on Marketing Account and Contact Factsheet
Define a HTML or URL mashup to embed the apps Contact Profile and Spotlighting Accounts in an iFrame in SAP Cloud for Customer.
Use Case
As a sales representative, you want to get insights about the engament and activities of your accounts and contacts across multiple communication channels.
Prerequisites
To provide sales representatives with marketing information on accounts and contacts, ensure the following: Integration with SAP Cloud for Customer, that is the transfer of contacts and accounts, is set up. Sales representativess must have a user in SAP Marketing Cloud and the authorizations to display the
factsheets.
Navigation to SAP Marketing Cloud information in SAP Cloud for Customer
1. In SAP Cloud for Customer navigate to an account or contact. 2. Navigate to your custom tab, for example the Marketing Factsheet. 3. Log on to the SAP Marketing Cloud to display the account or contact factsheet.
Set-up Procedure for Mashup
The following steps have to be performed in the SAP Marketing Cloud and the SAP Cloud for Customer in order to enable Sales Insights on Marketing Account and Contact Factsheet.
Settings in SAP Cloud for Customer
Settings in SAP Cloud for Customer for HTML or URL Mashup 1. Navigate to Administrator Mashup Authoring . 2. Choose New HTML Mashup .
If you want to create a URL mashup, choose New URL Mashup .
372
PUBLIC
Integration Guide Integration Scenarios
3. In the General Information section, verify that With Port Binding is preselected.
4. Choose Port Binding Type Additional Account Information . 5. Enter a name and a description for the mashup, for example Marketing Factsheet. 6. Under Configuration Information, select Type URL. 7. Enter the URL https://<host>/ui?sap-ushell-config=headerless#MarketingContact-
displayFactSheet?OriginID=SAP_C4C_BUPA. Host here refers to the SAP Marketing Cloud host.
Note
Do not select Extract Parameter.
8. Under Request Parameters, choose Add Row. 9. As Parameter, enter InteractionContactID. 10. Open the value help and select Parameter Binding AccountInternalID and set the request parameter to
Mandatory. 11. Click Preview to display the end result of the mashup.
To test the mashup, you can enter sample values for the parameters, and click Update Parameter Values to the right of the HTML Code Editor.
Note
If you change the code, you need to click Preview again to display the updated result of the mashup.
12. Specify the Height with the recommended value 600 px accordingly. 13. Save and Activate the mashup.
For more information about creating HTML mashups, see Create HTML Mashups.
Adding the Mashup to the Account and Contact UI
1. Go to your user profile, and from the dropdown list select Start Adaptation. The system opens in the Adaptation Mode.
2. Open an account. In the side pane, select Add Tab . 3. Go to the tab bar of the main screen and select the tab you just created. 4. Select the blue icon on the new tab. The system highlights the area with a red border to indicate that you
can make changes. 5. In the side pane, click the reverse arrow icon twice to navigate from the Form Pane to the UI Component
view. 6. Select Add Mashup to open a new window. 7. Depending on your selection in step 2, set the filter to HTML Mashups or URL Mashup.
For the HTML Mashups, carry out the following additional steps: 1. Select the row that contains the required mashup to display the Properties header. 2. Tick the checkbox for the same mashup to make the Properties editable. 3. Tick the checkbox Full Width in Properties and set the Height(%) to 100.
The newly added mashup will occupy the full height of the screen. 8. Choose Apply. 9. To save your settings, go to your profile and select End Adaptation.
Add mashup to contact UI: If you want to add the marketing factsheet to the contact UI, start the Adaptation Mode, open a Contact and add a new tab. Then repeat the steps 3 to 12.
Integration Guide Integration Scenarios
PUBLIC
373
For more information about adding mashups on screen, see Add Mashups on Screens
Settings in SAP Marketing Cloud
1. Assign the business catalog SAP_CEC_BC_MKT_CFS2_PC to your user. With this catalog, you can access to the apps Contact Profile and Spotlighting Accounts. As a reference, have a look at the user SALES_REP_MKT_INFO, that has the Business Role SAP_BR_SALES_REP_MKT_INFO and the Business Catalog SAP_CEC_BC_MKT_CFS2_PC assigned.
2. As an administrator, check if the SAP Cloud for Customer UI host is added in the app Maintain Clickjacking Protection Whitelist in SAP Marketing Cloud. The host is required to be able to click inside the Marketing UI in the iFrame in SAP Cloud for Customer.
3. If the host is not listed, add it.
Technical Background
Using this URL will automatically navigate to/embed either the contact or account UIs in their legacy or Fiori incarnation depending on the business role catalog that is assigned to the user .
4.5.2.3 Integration with External Sales Systems - Outbound Channel
Data transfer from marketing to external sales systems.
By integrating SAP Marketing Cloud with external sales systems, the bridge between marketing and sales is built so that processes can be harmonized across marketing and sales channels.
Caution
For the integration of SAP Marketing Cloud with external sales systems, we do not deliver standard content.
Note
You can set up the integration with internal and an external sales system simultaneously, but only with one system of a target system type at a time. That is, you can integrate one system for SAP CRM, one for SAP Cloud for Customer, and one external sales system.
In case you have activated more than one communication arrangement, that is, you have configured more than one target system, the Business Add-In (BAdI) Lead Management: Determine Target System Type is performed. With the Custom Logic app, you can implement the BAdI. You define in which target system the corresponding leads are created.
You can also use the integration with Salesforce offered by Advantco International LLC. For more information, see SAP Marketing Cloud Integration with Salesforce .
374
PUBLIC
Integration Guide Integration Scenarios
Outbound Processes from Marketing to an External Sales System
Depending on the data model of an external sales system, the following data can be replicated to an external sales system Business Documents
Leads are transferred to the external sales system. The system enriches the transferred marketing data during each lead transfer. For more information see Augmented Lead Context [page 355].
Note
For leads transferred to an external sales system, the system also sends out the assigned marketing area. As no mapping is performed in SAP Cloud Integration, the marketing area gets lost when a change in sales is replicated back to marketing.
Custom fields created in marketing Custom fields created in marketing can be transferred to the external sales system within the lead creation process.
Integration
You can set up the integration between SAP Marketing Cloud with an external sales system via SAP Cloud Integration. The following figure shows a possible overall integration overview based on a customer-owned integration setup:
Integration of SAP Marketing Cloud with External Sales Systems
Integration Guide Integration Scenarios
PUBLIC
375
4.5.2.3.1 Setting Up the Connection Between Marketing and an External Sales System
Connect SAP Marketing Cloud with an external sales system.
Before doing the configuration in SAP Marketing Cloud, you need the administrator business user, which contains the business catalog SAP_CORE_BC_COM (Communication Management), for example the business role SAP_BR_ADMINISTRATOR (Administrator).
As an administrator, you maintain the setup via the following apps under Communication Management:
Maintain Communication User For more information, see Creating a Communication User for Inbound Communication [page 376].
Communication Systems For more information, see Setting Up a Communication System for the Integration of an External Sales System [page 377].
Communication Arrangements For more information, see Setting Up a Communication Arrangement for the Integration of an External Sales System [page 378].
4.5.2.3.1.1 Creating a Communication User for Inbound Communication
Define a user for inbound communication.
The communication user defined in the SAP Marketing Cloud system is used for inbound communication and for the processing of messages in the system. Technically the user is needed to call OData services in SAP Marketing Cloud fromSAP Cloud Integration.
1. Log on to your SAP Marketing Cloud system. 2. On the launchpad, select the Maintain Communication Users tile 3. Choose New to create a new user (for example, MKT_COM_USR) or select an existing user. 4. Assign a password for the user if you would like to use the basic authentication, or assign SAP Cloud
Integration, integration service public client certificate to the user for certificate-based authentication: 1. Basic authentication: Enter password in the Password field
Note
Basic authentication with a user and password is possible, but not recommended in a productive environment for security reasons.
2. Certificate based authentication: Choose Upload Certificate (exported from SAP Cloud Integration, integration service keystore. The link to download certificate is provided by SAP Operations in the initial tenant provisioning mail).
5. Choose Save. 6. Note down the user data for further steps.
Note
In the SAP Cloud Integration system, you need this technical user to call the OData services.
376
PUBLIC
Integration Guide Integration Scenarios
4.5.2.3.1.2 Setting Up a Communication System for the Integration of an External Sales System
Connect the communication user with the communication arrangement.
The Communication System is used to define the host name of the SAP Cloud Integration tenant and to assign users for the inbound (fromSAP Cloud Integration to SAP Marketing Cloud) and outbound (from SAP Marketing Cloud to SAP Cloud Integration) communication.
To create the communication system for SAP Cloud Integration, proceed as follows:
1. Log on to your SAP Marketing Cloud system. 2. On the launchpad, open the Communication Systems app. 3. To create a new system, choose New. 4. In New Communication System, enter a system ID and its name, and choose Create. 5. In the Technical Data section, enter the details of your SAP Cloud Integration tenant in the Host Name field
(see SAP Cloud Integration tenant provisioning email). As a host is irrelevant to the inbound communication, enter dummy to assign a dummy host. 6. Assign the communication user created earlier to this communication system, as follows: In the User for Inbound Communication section, choose + (Add). In New Inbound Communication User, select the authentication method as User Name and Password
and enter the user created earlier. 7. To create a new outbound user, in the User for Outbound Communication section, choose + (Add).
In New Outbound User, select the authentication method: Basic Authentication
Authentication Method User Name
Password Certificate-Based Authentication
Username and Password
P-user that has access to the SAP Cloud Integration service tenant.
Password for the user
Authentication Method Certificate Type
SSL Client Certificate
Exported from SAP Cloud Integration, integration serv ice keystore. The link to download certificate would be provided by SAP Operations in initial tenant provision ing mail.
8. Choose Create. 9. Save and activate the communication system.
Integration Guide Integration Scenarios
PUBLIC
377
4.5.2.3.1.3 Setting Up a Communication Arrangement for the Integration of an External Sales System
Set up the communication with SAP Cloud Integration.
Communication Arrangements need to be activated inSAP Marketing Cloud for communication with OData APIs. The communication arrangement in the SAP SAP Marketing Cloud defines all relevant information for the communication with SAP Cloud Integration. It contains the communication system, and inbound and outbound authentication.
The communication arrangement SAP_COM_0017: Marketing - Presales/Sales Integration needs to be activated.
To set up the communication arrangement, proceed as follows:
1. Log on to SAP Marketing Cloud with a user that has administrator authorizations. 2. From the SAP Fiori launchpad, choose the Communication Arrangements app. 3. To create a new communication arrangement for the communication scenario SAP_COM_0017 (Marketing
- Presales/Sales Integration ), choose New. Select the scenario and enter an arrangement name. Choose Create. 4. In the Common Data, choose the communication system that you created previously. 5. In Additional Properties, select the Target System Type. Choose SALES_EXT.
Note
In case a communication arrangement with Target System Type SALES_EXT already exists, you cannot activate another one.
6. Select values for First Origin of Contact ID, Second Origin of Contact ID, Third Origin of Contact ID. New additional properties are defined to be able to configure Origins of Contact IDs for target system type SAP_EXTERNAL. The combination of ID_ORIGIN and ID must uniquely identify a contact in SAP Marketing Cloud. Depending on the usage of number ranges assigned to business partners in the external sales system, more than one ID_ORIGIN can be necessary. Valid values can be defined in the Origin of Contact app under Implementation Cockpit Manage Your Solution Configure Your Solution Marketing/Contacts and Profiles OriginContactID Configure . The rules above are effective independent of the existence of communication arrangements with different target system types.
Note
It is only possible to activate a communication arrangement with Target System Type = SALES_EXT, if the following Additional Properties or Outbound Services are maintained as follows: The additional property Campaign Transfer to Sales is inactive. The additional property First Origin of Contact ID is vailable. The outbound service Export of Activities is inactive. The outbound service Export of Campaigns is inactive.
7. In Inbound Communication, enter the previously created user. The authentication method is filled automatically.
8. In Outbound Communication, the SAP Cloud Integration service user that was assigned to Communication System is automatically added or the default client certificate with certificate download link is displayed.
378
PUBLIC
Integration Guide Integration Scenarios
in Outbound Services, ensure that only Export of Leads is activated.
Field Name Service Status Application Protocol Port Path Service URL
Entry Checked (Active) SOAP 443 /cxf/<ExternalSalesSystemService> Will be automatically populated.
9. Choose Save.
4.5.3 Financial Data
Integration with SAP ERP for Spend Planning [page 379] With the following instructions you are able to integrate spend data from your system with SAP ERP. A campaign is represented by a project and a spend item as a WBS element. You use these WBS elements as account reference for further processing within SAP ERP.
4.5.3.1 Integration with SAP ERP for Spend Planning
With the following instructions you are able to integrate spend data from your system with SAP ERP. A campaign is represented by a project and a spend item as a WBS element. You use these WBS elements as account reference for further processing within SAP ERP.
Prerequisites
You have SAP ERP 6.0 EHP 4 or higher. You have set up the SAP Marketing Cloud - SAP ERP Actual and Committed Spend integration package. For
more information, see https://api.sap.com/package/ SAPS4HANAMarketingCloudSAPERPActualandCommittedSpendIntegration .
Integration Guide Integration Scenarios
PUBLIC
379
Setting Up the Communication with SAP ERP
To set up the communication between SAP Marketing Cloud and SAP ERP, perform the following steps:
1. Create the system for outbound communication using the Communication Systems configuration application. Enter the following data:
System Name Host Name
Authentication Method
Name of the SAP ERP system, for example, ABC.
Host address of the SAP ERP system, for example, ldiabc.corp.com.
Select an authentication method.
2. Create a communication arrangement with a certificate-based authentication for the outbound scenario. 3. Create a communication arrangement for the Marketing - Planning Spend Integration (SAP_COM_0018)
scenario using the Communication Arrangements configuration application. Enter the following data:
Common Data Arrangement Name
SAP_COM_0018
Common Data Communication System
The SAP ERP system created in the Communication Systems configuration application in the previous step.
Outbound Communication User Name/Certificate
Select certificate-based authentication for the outbound scenario. Download the certificate. It will be used later while setting up SAP ERP and configuring the security.
Outbound Services Port
Port for the communication.
380
PUBLIC
Integration Guide Integration Scenarios
Outbound Services Path
You must set up the following SOAP services in the order defined below and specify the path for each of them: 1. Create service, for exam
ple, /sap/bc/srt/xip/sap/ ecc_projecterpcrtrc1/<client of SAP ERP system>/<name of service/binding that will be used when configuring Web Services>/<name of service/binding that will be used when configuring Web Services> 2. Update service, for exam ple, /sap/bc/srt/xip/sap/ecc_projectupdrc/ <client of SAP ERP system>/<name of service/binding that will be used when configuring Web Services>/<name of service/binding that will be used when configuring Web Services> 3. Get service, for example, /sap/bc/srt/xip/sap/ ecc_projecterpidqr1/<client of SAP ERP system>/<name of service/binding that will be used when configuring Web Services>/<name of service/binding that will be used when configuring Web Services> The path for each service is defined during the SAP ERP setup.
For example, <client of SAP ERP system> could be 100, <name of service/binding that will be used when configuring Web Services> could be cuan_msm. The name you de fine in this step must be the same as the name defined during the SAP ERP setup.
For more information, search for Maintain Communication Arrangements and Maintain Communication Systems on SAP Help Portal at http://help.sap.com under the SAP S/4HANA Cloud product.
Setting Up SAP ERP
1. Configure the Web service runtime as target system connection. For more information, search for Configuring the Web Service Runtime on SAP Help Portal at http://help.sap.com under the SAP NetWeaver product.
2. Configure your security settings for the service provider and service consumer using the SOA Manager. For more information, search for Runtime Configuration with the SOA Manager on SAP Help Portal at http:// help.sap.com under the SAP NetWeaver product.
3. Configure service definitions in the Web service configuration transaction (SOAMANAGER) for the following: ProjectERPCreateRequestConfirmation_In_V1 (ECC_PROJECTERPCRTRC1)
Integration Guide Integration Scenarios
PUBLIC
381
ProjectERPUpdateRequestConfirmation_In (ECC_PROJECTUPDRC) ProjectERPByIDQueryResponse_In_V1 (ECC_PROJECTERPIDQR1) Configure the services as follows: 1. In the Service and Binding Name step, enter the same name in the Service Name and New Binding
Name fields. This must be the same name as the one defined in step 3 of the communication setup with SAP ERP under Outbound Services Path . 2. In the Provider Security step, under Transport Level Security, select the SSL (https) radio button, and under Transport Channel Authentication, select X.509 SSL Client Certificate. 3. Go through the other steps without specifying any values and complete the configuration. You will find the WSDL URL for Binding in the WSDL Generation for Binding of each service. For more information, search for Configuring a Service Provider on SAP Help Portal at http://help.sap.com under the SAP NetWeaver product.
As in SAP Marketing Cloud, prefix 1_CUAN_MSM_<CampaignID> is given for creation of projects and 1/ <CampaignID> for WBS elements in SAP ERP, no predefined coding mask is required for project coding key 1.
Project profile CUAN01 has to be configured in SAP ERP.
Checking for Errors
You can use the Application Log application to check if there are errors with the integration. You can use the CUAN category and the Marketing Spend Integration in External System (CUAN_MSM_SPEND_DISTR) subcategory. You can also use the Message Dashboard application to monitor if there are errors with the integration and to reprocess the integration. For more information, see Data Exchange Messages for Spend Planning Integration. For a complete description of the configuration settings required for the integration scenario, see the setup guide at https://api.sap.com/shell/discover/contentpackage/ SAPS4HANAMarketingCloudSAPERPActualandCommittedSpendIntegration?section=DOCUMENTS .
4.5.3.1.1 Importing Actual and Committed Spend from SAP ERP
You can import actual and committed spend associated to campaigns from SAP ERP and make it available in the Spend area of the Campaigns application.
Prerequisites
You have enabled the integration of spend data with SAP ERP. For more information, see Integration with SAP ERP for Spend Planning [page 379].
382
PUBLIC
Integration Guide Integration Scenarios
You have set up the SAP Marketing Cloud - SAP ERP Actual and Committed Spend integration package. For more information, see https://api.sap.com/package/ SAPS4HANAMarketingCloudSAPERPActualandCommittedSpendIntegration .
You have configured the communication scenario Marketing - Business Data Integration in SAP Marketing Cloud.
You have installed the latest version of the SAP HYBRIS C4C ERP INTEGR product in SAP ERP that contains the COD_ERP_INT 6.00 component. For information about this product and the CODERINT 600 add-on, see the corresponding documentation on SAP Support Portal at http://support.sap.com
Download Software By Alphabetical Index (A-Z) C SAP HYBRIS C4C ERP INTEGR and https:// rapid.sap.com/bp/#/browse/categories/lines_of_business/areas/marketing/packageversions/
BP_CLD_MKT Solution Scope Integration SAP ERP Actual and Committed Spend Integration
(19Y) . You have the authorization to run the CUAN_ERP_MSM_EXTRACT_ACTUAL report in SAP ERP.
Context
You can import actual and committed spend data from SAP ERP using this integration.
Procedure
To import the actual and committed spend, run the CUAN_ERP_MSM_EXTRACT_ACTUAL report.
Results
The actual and committed spend associated to campaigns are shown in the Spend area of the Campaigns application. For a complete description of the configuration settings required for the integration scenario, see the setup guide at https://api.sap.com/shell/discover/contentpackage/ SAPS4HANAMarketingCloudSAPERPActualandCommittedSpendIntegration?section=DOCUMENTS .
4.5.4 Survey Data
The documentation explains the following topics:
How to integrate SAP Qualtrics Surveys with SAP Marketing Cloud using integration flows and you intend to send surveys using the SAP Marketing Cloud system. For more information, see Integration with SAP Qualtrics Surveys [page 384].
Integration Guide Integration Scenarios
PUBLIC
383
How to integrate SAP Qualtrics Surveys with SAP Marketing Cloud using integration flows and you intend to send surveys outside of the SAP Marketing Cloud system. For more information, see Integration with SAP Qualtrics Surveys Using Actions Functionality [page 384]. Integration with SAP Qualtrics Surveys [page 384] Integration with SAP Qualtrics Surveys Using Actions Functionality [page 384]
4.5.4.1 Integration with SAP Qualtrics Surveys
Integration of SAP Qualtrics Surveys with SAP Marketing Cloud using SAP Cloud Integration: SAP Qualtrics Surveys Integration with SAP Marketing Cloud . By supporting the integration of SAP Qualtrics Surveys with SAP Marketing Cloud, customers can benefit from the features of Qualtrics. This integration fetches and stores data easily from SAP Qualtrics Surveys into SAP Marketing Cloud system. To achieve this integration, the following iFlows are provided: Create Survey Data in SAP Marketing Cloud. Create Survey Subscription in Qualtrics. Mapping Qualtrics Surveys Data for SAP Marketing Cloud. Watch this 4-minute video, which provides you a step-by-step integration overview, which helps you to integrate SAP Qualtrics Surveys with SAP Marketing Cloud
For more information, see Integrating SAP Qualtrics Surveys with SAP Marketing Cloud.
4.5.4.2 Integration with SAP Qualtrics Surveys Using Actions Functionality
Integration of SAP Qualtrics Surveys with SAP Marketing Cloud using SAP Cloud Integration Suite: By supporting the integration of SAP Qualtrics Surveys with SAP Marketing Cloud, customers can benefit from the features of Qualtrics. With this integration, you can: distribute surveys from an external system like Qualtrics or a website fetch survey responses of your existing customers fetch survey responses and create a contact profile for nonexistent contacts in your system To achieve this integration, the following integration flows are provided: Create Survey Data and Response in SAP Marketing Cloud. Load Buffered Survey Data to SAP Marketing Cloud. Watch this 3-minute video, which provides you a functional and integration overview of the integration using the Actions functionality.
384
PUBLIC
Integration Guide Integration Scenarios
For more information, see Integrating SAP Qualtrics Surveys with SAP Marketing Cloud Using Actions Functionality.
4.5.5 Personalized Commerce
With the following personalized Commerce options, you can tailor your Commerce implementation to suite your customers.
Integration with SAP Commerce [page 385] Support omnichannel activities by integrating SAP Marketing Cloud with SAP Commerce Cloud.
Consuming Recommendation Models Using an OData Service [page 385] The API_MKT_RECOMMENDATION_SRV and PROD_RECO_RUNTIME_SRV public OData services enable customer channels to receive recommendations generated by Recommendation.
Offer Discovery [page 386] Discover suitable offer content for consumers.
Exporting Offline Sales Data [page 386] Export offline sales data from SAP Marketing Cloud and make it available in other applications.
4.5.5.1 Integration with SAP Commerce
Support omnichannel activities by integrating SAP Marketing Cloud with SAP Commerce Cloud. For more information, see Integration with SAP Commerce Cloud [page 62].
4.5.5.2 Consuming Recommendation Models Using an OData Service
The API_MKT_RECOMMENDATION_SRV and PROD_RECO_RUNTIME_SRV public OData services enable customer channels to receive recommendations generated by Recommendation. You can enable customer channels to receive recommendations generated by Recommendation using the following services:
API_MKT_RECOMMENDATION_SRV
The API_MKT_RECOMMENDATION_SRV public OData service for Recommendations allows a client system to obtain product or offer recommendations from the SAP Marketing Cloud using theSAP Business Technology Platform. The service is easy to consume and enables you to benefit from the following: Built-in redundancy in the event of SAP Marketing Cloud unavailability.
Integration Guide Integration Scenarios
PUBLIC
385
If the SAP Marketing Cloud is unresponsive when a request for a recommendation is submitted, a comprehensive fallback process is initiated. The process begins by trying to retrieve a personalized recommendation from the cache using the user's ID (if available) and the leading items associated with the request. If that fails, a second restricted attempt is made using similar users (for example, a target group) and the leading items associated with the request. If that fails, a third generic request is submitted using the leading items exclusively. This process of submitting personalized, restricted, and generic requests continues using subsets of the leading items from the most to least recent until a recommendation is returned.
Enriched recommendation results. The API retrieves product master data from the SAP Marketing Cloud. The data enriches the recommendation results obtained, for example, by providing product images and descriptions.
For more information, see Recommendations (SAP Business Technology Platform) [page 923].
PROD_RECO_RUNTIME_SRV
The PROD_RECO_RUNTIME_SRV public OData service for Recommendations allows a client system to obtain product recommendations from the SAP Marketing Cloud. For more information, see Recommendations [page 939].
4.5.5.3 Offer Discovery
Discover suitable offer content for consumers. The personalized offer recommendations are based on eligibility and validity. The personalization is determined by geo location, offer attributes, and scores. For more information, see: SAP SCN Offer Recommendation in SAP Commerce . Discover Offers [page 1008].
4.5.5.4 Exporting Offline Sales Data
Export offline sales data from SAP Marketing Cloud and make it available in other applications.
This integration provides a foundation for repurposing offline sales data from SAP Marketing Cloud. v acts as middleware, using the API_MKT_INTERACTION_SRV and API_MKT_CONTACT_SRV services to retrieve information from SAP Marketing Cloud. The integration flow exports the data in a comma-separated value (CSV) file, and then sends it to an SFTP server. From there, you can perform custom development in your target system to upload and use the data.
For a complete description of the configuration settings required for integration, see the Introduction.
For more information, see the offline sales Integration package .
386
PUBLIC
Integration Guide Integration Scenarios
5 Integration APIs
Are you trying to pull or push information for individual marketing entities such as campaigns, target groups, or contacts? There is a wide range of public APIs available to enable you to integrate with SAP Marketing Cloud. Refer to the following table to quickly find the information that will help you get started, no matter what your level of knowledge.
Caution
The API services available in SAP Marketing Cloud must not be used for mass read (GET) operations. In other words, you cannot use them for extracting all available data, for example, to extract millions of contacts or interactions from your marketing system.
Questions This Guide Answers
Read Me
Which API should I use if I want to integrate a third-party data source that provides, for ex ample, agreement, campaign, or contact information.
Quick Guide - Which API for Which Entity [page 389]
What do I need to know before using the marketing APIs?
Getting Started [page 387]
What are SAP APIs?
https://developers.sap.com/ topics/api.html
How do I navigate the SAP API Business Hub?
https://api.sap.com/gettingstarted
I'm new to OData. How does it work?
http://www.odata.org
5.1 Getting Started
This section contains information to help you get started quickly, including communication prerequisites for integrating with APIs, deep-dive videos that will help you find your way around the SAP API Business Hub and understand the data load concepts, as well as some useful best practices and recommendations for efficient integration and data load.
Videos - Best Practices for Data Load [page 388] These short videos provide valuable insight into the data load concepts, and include useful tips for before and after you load data into your marketing system. The videos are available in English only.
Quick Guide - Which API for Which Entity [page 389] SAP Marketing Cloud offers a wide range of services. But which one is right for your purposes? Take a few minutes to browse this table according to the entity type you want to import.
Consuming the Integration APIs [page 395]
Integration Guide Integration APIs
PUBLIC
387
Extending the Integration APIs [page 396] The following table indicates which APIs can be extended and provides links to further information.
Optimize Performance During OData Service Calls [page 397] This section describes how to call an OData service in a way that ensures a high degree of system security and performance. The description uses API_MKT_INTERACTION_SRV as an example, but the method applies to all OData services in SAP Marketing Cloud.
Best Practices and Recommended Package Sizes [page 400] This section contains best practices for optimizing data load of master data entities, recommended package sizes, and some troubleshooting tips.
Import Monitor [page 404] Monitor and explore data imports that are triggered by OData or upload services from external systems.
Data Load Monitor [page 407] Monitor all import messages and keep track of their status.
HTTP Response Status Codes [page 408] Every HTTP request that is received by a server is responded to with a 3-digit HTTP status code. They are grouped into five classes.
5.1.1 Videos - Best Practices for Data Load
These short videos provide valuable insight into the data load concepts, and include useful tips for before and after you load data into your marketing system. The videos are available in English only.
Data Load Videos (English Only)
Planning and Configuring the Contact Data Load This 5-minute video explains what origin IDs are, the significance of the configuration settings you can make, and how these affect the contact match and merge process.
Configuring Origins This 2-minute video explains important points to consider when you configure your data sources and why it is important to have one origin per data source.
How Imported Data Is Processed This 6-minute video explains the match and merge process that contact data undergoes whenever new data is uploaded.
388
PUBLIC
Integration Guide Integration APIs
Data Lifecycle Management - Decluttering Your System This 5-minute video explains how and why your should declutter your system regularly of marketing data that no longer serves any useful purpose.
Note
The application job used as an example in this video has changed and is no longer valid, but the deletion concept recommended in the video still applies.
Analytical List Pages in SAP Marketing Cloud This 3-minute video walks you through the highly-configurable functions of analytical list pages (ALPs). Based on the example of the Browse Contact Origin Data app, explore the insights you can gain from ALPs.
Data Load Monitor This 3-minute video explains the importance of monitoring imports, and of regularly analyzing and fixing common error causes. It shows how the Data Load Monitor can support you in safeguarding the quality of data imports.
Related Information
Video Library
5.1.2 Quick Guide - Which API for Which Entity
SAP Marketing Cloud offers a wide range of services. But which one is right for your purposes? Take a few minutes to browse this table according to the entity type you want to import.
Quick Guide - Which API Should I Use?
You can search, sort, and filter the table to view the data as best suits your requirements. For example, you can quickly search by Entity Type to find the recommended service or other import options, which you can use in exceptional cases, for example for a one-time import for test purposes.
Integration Guide Integration APIs
PUBLIC
389
Integration Services in SAP Marketing Cloud
Area
Entity Type
Recommended Service
Other Import Options
Contacts and Profiles
Contacts
Marketing Permis sions
Public OData API (API_MKT_CONTACT_SRV Version 4) for reading and writing master data about Contacts. Contacts are natural persons who interact with your company.
Data File Load - Contacts
Marketing Contacts [page 412]
Subscrip tions
Note
You must use version 4 of this API service if you implement Contact-to-Account Relationships.
Contacts and Profiles
Interaction Contacts
Marketing Permis sions
Marketing Subscrip tions
Public OData API (API_MKT_INTERACTION_CONTACT_SRV Version 3) for Interaction Contacts. Interaction Contact is a ge neric term to group all natural persons (contacts, con sumers, or suspects), companies and "unknowns", who interact with your company.
Interaction Contacts [page 469]
Contacts and Profiles
Corporate Ac counts
Marketing Permis sions
Marketing Subscrip tions
Public OData API (API_MKT_CORPORATE_ACCOUNT_SRV Version 3) for reading and writing master data about Corporate Ac counts only. Corporate accounts are companies or or ganizations that interact with your company.
Corporate Accounts [page 512]
Data File Load - Corporate Accounts
Contacts and Products Profiles
Public OData API (API_MKT_PRODUCT_SRV) for Prod ucts.
Data File Load - Products
Products [page 582]
Contacts and Profiles
Product Hierar chies and Cate gories
Public OData API (API_MKT_PRODCAT_HIERARCHY_SRV) for Product Hierarchies and Categories.
Product Hierarchies and Categories [page 604]
Data File Load - Product Categories
390
PUBLIC
Integration Guide Integration APIs
Area
Entity Type
Contacts and Interactions Profiles
Recommended Service
Other Import Options
Public OData API (API_MKT_INTERACTION_SRV) for Interactions.
Interactions [page 615]
Business Documents [page 661]
Note
For business docu ments (leads, opportu nities, sales orders, and so on), we recommend that you use the API Service CUAN_BUSINESS_DOC UMENT_IMP_SRV, since it provides an upsert function and updates an already existing en try depending on time stamp information.
Data File Load - Interac tions
Contacts and Profiles
Business Docu ments from SAP Cloud for Customer
Public OData API (CUAN_BUSINESS_DOCUMENT_IMP_SRV) for import ing business documents, such as leads and opportuni ties, from external SAP or non-SAP systems to SAP Marketing Cloud. Use this version of the service when you want to import business documents related to Of fers and Coupons. Lower versions are not suitable for this purpose.
Business Documents [page 661]
Contacts and Profiles
Contacts, Cor porate Ac counts or Rela tionships from SAP ERP, SAP CRM, or S/ 4HANA On Premise
CUAN_BUSINESS_PARTNER_IMPORT_SRV for import ing business partner data from external source sys tems, like, for example, SAP ERP, SAP CRM, SAP S/ 4HANA On Premise.
Import Business Partners [page 574]
Contacts and Profiles
Account Team Members (for Companies)
Public OData API (API_MKT_CORPORATE_ACCOUNT_SRV Version 3) for reading and writing master data about Corporate Ac counts only. Corporate accounts are companies or or ganizations that interact with your company.
Data File Load - Account Team Members
Corporate Accounts [page 512]
Integration Guide Integration APIs
PUBLIC
391
Area
Entity Type
Recommended Service
Other Import Options
Contacts and Profiles
Account Team Members (for Contacts)
Public OData API (API_MKT_CONTACT_SRV Version 4) for reading and writing master data about Contacts. Contacts are natural persons who interact with your company.
Data File Load - Account Team Members
Contacts [page 412]
Contacts and Interests Profiles
Public OData API API_MKT_INTEREST_SRV Interest Items [page 648]
Manage Interests app - Manage Interests
Contacts and Agreements Profiles
Public OData API (API_MKT_AGREEMENT_SRV) for agreements. An agreement can be any kind of cus tomer contract, for example, a sales contract or a con tract that comprises specific services.
Agreements [page 681]
Contacts and Marketing Lo
Profiles
cations
Public OData API (API_MKT_LOCATION) for Market ing Locations. A marketing location is any physical or virtual location where a marketing activity can be con ducted.
Data File Load - Import Marketing Locations
Marketing Locations [page 710]
Contacts and Scores Profiles
Public OData API (API_MKT_SCORE_SRV) for Scores Scores [page 700]
Contacts and Profiles
Marketing Per missions and Marketing Sub scriptions
Public OData API (API_MKT_CONTACT_SRV Version 4) for reading and writing master data about Contacts. Contacts are natural persons who interact with your company.
Data File Load - Permis sions and Subscriptions
Contacts [page 412]
Contacts and Profiles
Marketing Per missions and Marketing Sub scriptions
Public OData API (API_MKT_INTERACTION_CONTACT_SRV Version 3) for Interaction Contacts. Interaction Contact is a ge neric term to group all natural persons (contacts, con sumers, or suspects), companies and "unknowns", who interact with your company.
Data File Load - Permis sions and Subscriptions
Interaction Contacts [page 469]
Contacts and Profiles
Marketing Per missions and Marketing Sub scriptions
Public OData API (API_MKT_CORPORATE_ACCOUNT_SRV Version 3) for reading and writing master data about Corporate Ac counts only. Corporate accounts are companies or or ganizations that interact with your company.
Data File Load - Permis sions and Subscriptions
Corporate Accounts [page 512]
392
PUBLIC
Integration Guide Integration APIs
Area
Entity Type
Recommended Service
Other Import Options
Commerce Marketing
Offers
Use the public OData API CUAN_OFFER_IMPORT_SRV to upload (import) offers from external sources.
Import Offers [page 973]
Commerce Marketing
Read Offers
Public OData API (API_MKT_OFFER_SRV) for Offers Read Offers [page 1002]
Commerce Marketing
Discover Offers
Use the API OData service CUAN_OFFER_DISCOVERY_SRV for SAP Marketing Cloud Offers to find suitable offers for a consumer.
Discover Offers [page 1008]
Commerce Marketing
Coupons
Public OData API (API_MKT_COUPON_SRV) for Cou pons.
Coupons [page 1026]
Commerce Marketing
Recommenda tions Interac tion Data
OData service (PROD_RECO_RUNTIME_SRV) for post ing interactions to an SAP HANA database.
Recommendations Interaction Data [page 971]
Extensibility
Custom Busi ness Objects
Import data into a Custom Business Object by using an OData service
Import of Data into Custom Business Object [page 1057]
Data File Load - Custom Business Objects
Marketing Planning and Performance
Custom Dimen Custom Dimension Values - Import Custom Dimen
sions
sions
Marketing Planning and Performance
Actual and Committed Spend
Actual and Committed Spend Data [page 1041] You can upload actual and committed spend data from an ex ternal ERP system into SAP Marketing Cloud using the CUAN_ACTUAL_IMPORT_SRV OData service.
Financial Data [page 379] SAP ERP Integration is the preferred method wherever possible.
Data File Load - Actual and Committed Spend
Note
If you use the data file load for occasional im ports in parallel to a scheduled job using the OData service, you must consolidate the data to ensure data reconciliation and con sistency.
Integration Guide Integration APIs
PUBLIC
393
Area
Entity Type
Recommended Service
Other Import Options
Campaign
Campaigns
Management
Public OData API (API_MKT_CAMPAIGN_SRV) for Campaigns
Campaigns [page 767]
Campaign Management
Campaign Exe CUAN_MPO_IMPORT_SRV
cution Plans
Campaign Execution Plans [page 763]
Campaign Management
Campaign Mes Public OData API
sage Content (API_MKT_CAMPAIGN_MESSAGE_SRV) for exporting
and Personal and importing message content in multiple languages.
ized Email Con tent
Campaign Message Content and Personalized Email Content [page 793]
Campaign Management
Campaign Per formance
Public OData API (API_MKT_CMPGN_SUCCESS_IMPORT) for importing aggregated success data for Campaigns.
Campaign Success Data [page 812]
Campaign
Survey
Management
OData API (CUAN_SURVEY_IMPORT_SRV) that sup ports operations on survey metadata and survey re sponses.
Survey [page 886]
Data File Load - Campaign Performance
Data File Load - Survey Metadata
Data File Load - Survey Re sponse
Campaign
Marketing
Management Events
Public OData API (API_MKT_EVENT_SRV) for import ing events data from third-party event provider plat forms.
Campaign Management
External Land ing Pages (Landing Pa ges)
Public OData API (API_MKT_LANDING_PAGE) for writ ing external landing pages to the SAP Marketing Cloud system.
External Landing Pages [page 743]
Campaign Management
External Land ing Pages (Forms)
Public OData API (API_MKT_LANDING_PAGE) for writ ing external forms to the SAP Marketing Cloud sys tem.
External Landing Pages [page 743]
Campaign Management
External Land ing Page Value Help
Public OData API (API_MKT_LANDING_PAGE_VALUEHELP) for retriev ing attribute values used in landing pages.
External Landing Page Value Help [page 749]
394
PUBLIC
Integration Guide Integration APIs
Area
Entity Type
Recommended Service
Other Import Options
Marketing An Audiences alytics
Cluster reporting results or assign budgets to audien ces.
Audiences
Marketing An Brands alytics
Add and edit brands, and import brand data from a comma-separated value (CSV) file. You can also delete values of brands that are not used in any business ob jects, such as budget plans.
Brands
Segmentation Target Groups
Public OData API (API_MKT_TARGET_GROUP_SRV) for Export Target Groups and Target
Target Groups
Group Member Data [page 761]
Target Groups [page 755]
Campaign
Export Defini-
Management tions
Public OData API (API_MKT_EXPORT_DEFINITION) for Export Definitions.
An export definition is a template for structuring the export of target group member data, included in a tar get group or a campaign, to CSV files.
Read Content of Export Files in Campaigns [page 901]
Marketing Planning and Performance
Marketing Programs
Public OData API (API_MKT_PROGRAM_SRV) for mar keting programs.
Marketing Programs [page 1045]
5.1.3 Consuming the Integration APIs
Overview
The SAP Marketing Cloud public APIs conform to the OpenAPI specifications. All the OData APIs are listed on the SAP API Business Hub at https://api.sap.com/ . You can test these APIs on the SAP API Business Hub.
Setting Up Communication with SAP Marketing Cloud
To set up a communication system and communication arrangement, you require the business catalog role Communication Management (SAP_CORE_BC_COM) assigned to your user. For more information, see:
Integration Guide Integration APIs
PUBLIC
395
Communication Management How to Create Communication Users How to Create Communication Systems How to Create a Communication Arrangement
.
Extending SAP Marketing Cloud
SAP S/4 HANA Cloud extension procedures are applicable for extension of SAP Marketing Cloud as well. For more information, see Extending SAP S/4HANA Cloud.
Configuring the Extension Application Connectivity to SAP Marketing Cloud
The following SAP S/4 HANA Cloud extension procedures are applicable for SAP Marketing Cloud as well. Using Basic Authentication Using Client Certificate Authentication Using SAML Bearer Assertion Authentication
5.1.4 Extending the Integration APIs
The following table indicates which APIs can be extended and provides links to further information.
For detailed information about:
Adding custom fields to the SAP Marketing Cloud APIs and the relevant business contexts to use, see Custom Fields.
Adding custom fields in an integration package, for example adding a custom field to a replicated business object such as a business partner, see SAP Marketing Cloud Scenario-Based Extensibility.
Extensible API Services in SAP Marketing Cloud
Area
API Service
Business Context
Contact Profiling
Contacts
Marketing: Contact Marketing: Contact and Corporate Account Marketing: Marketing Attributes for Contacts
Contact Profiling
Interaction Contacts
Marketing: Contact Marketing: Contact and Corporate Account
Contact Profiling
Corporate Accounts
Marketing: Corporate Account Marketing: Contact and Corporate Account
396
PUBLIC
Integration Guide Integration APIs
Area Contact Profiling Contact Profiling Contact Profiling Contact Profiling
API Service Products Product Categories Interactions Agreements
Contact Profiling Campaign Management Campaign Management
Marketing Locations Campaigns Campaign Success Data
Campaign Management Commerce Marketing
Marketing Events Import Offers
Commerce Marketing
Read Offers
Commerce Marketing
Discover Offers
Commerce Marketing
Marketing Planning and Performance
Coupons Marketing Programs
Business Context
Marketing: Product
Marketing: Product Category
Marketing: Interaction
Marketing: Agreement Marketing: Agreement Terms (time dep.)
Marketing: Marketing Location
Marketing: Campaign
Marketing: Campaign Performance Actual Measure Marketing: Campaign Performance Dimension Marketing: Campaign Performance Target Measure
Marketing: Marketing Events
Marketing: Offer Header Marketing: Offer Content
Marketing: Offer Header Marketing: Offer Content
Marketing: Offer Header Marketing: Offer Content
Marketing: Coupon Code
Marketing: Program
5.1.5 Optimize Performance During OData Service Calls
This section describes how to call an OData service in a way that ensures a high degree of system security and performance. The description uses API_MKT_INTERACTION_SRV as an example, but the method applies to all OData services in SAP Marketing Cloud.
Importing Data into SAP Marketing Cloud
1. Request an x-CSRF token and a session cookie by calling the metadata document, for example, https:// <mkt.com>/sap/opu/odata/sap/api_mkt_interaction_srv/$metadata.
2. In the get request header, you must add the parameter name x-csrf-token and the value Fetch, as shown in the code snippet. This get request returns the x-CSRF token and session cookie in the response.
3. Create the payload with the data you want to post.
Integration Guide Integration APIs
PUBLIC
397
4. Post the data via the corresponding endpoint and send the x-CSRF token and the session cookie that you received in step 1. In the post request: In the parameter x-csrf-token enter the value from the token you received in step 1. In the parameter Content-type, enter the value application/json. Add the session cookie you received from the get metadata request, for example https:// <mkt.com>/sap.opu.odata/sap/api_mkt_interactions_srv/InteractionsDeepInsert.
5. You should terminate the session cookie by calling the logoff service. For example, https:// <mkt.com>/sap/public/bc/icf/logoff. By doing this, you ensure that the session cookie and the xCSRF token are no longer valid. In this get request, you have to add: The parameter `x-csrf-token' and the value you received in step 1. The session cookie you received from the get metadata request.
Important Points to Note
The session cookie will automatically terminate after 30 minutes idle time. You should reuse the session cookie and the x-CSRF token for as long as you can. In other words, you
should try to avoid exceeding 30 minutes idle time. By reusing the session cookie, you avoid having additional calls to generate a new cookie every time. This
leads to improved performance because you have to execute the get call only once. By terminating the session cookie, you secure the system because the cookie and CSRF token can no
longer be used.
Example
Code Syntax
**************************************************************************
* Establish the connection
* get request to fetch the CSRF Token and session cookie
**************************************************************************
lv_header_field-name = 'x-csrf-token'.
lv_header_field-value = 'Fetch'.
INSERT lv_header_field INTO TABLE lt_header_fields.
TRY.
IF ( lt_cookies IS INITIAL ).
cl_cuan_http_helper=>s_get_instance( )->http_call(
EXPORTING
iv_destination = '<SM59_ENTRY>'
iv_url
= '/sap/opu/odata/sap/api_mkt_interaction_srv/
$metadata'
iv_method
= 'GET'
it_header_fields = lt_header_fields
IMPORTING
ev_status_code = lv_status_code
ev_x_csrf_token = lv_x_csrf_token
et_cookies
= lt_cookies
)
CLEAR lt_header_fields.
lv_header_field-name = 'x-csrf-token'.
lv_header_field-value = lv_x_csrf_token.
INSERT lv_header_field INTO TABLE lt_header_fields.
lv_header_field-name = 'Content-Type'.
Lv_header_field-value = 'application/json'.
INSERT lv_header_field INTO TABLE lt_header_fields.
398
PUBLIC
Integration Guide Integration APIs
ENDIF CATCH cx_cuan_cpred_error INTO exc_cpred_error. * Error handling ENDTRY.
Code Syntax
***************************************************************************
* Create payload and
* send it via post request to SAP Marketing Cloud
***************************************************************************
WHILE lv_true = abap_true.
* creating the payload with your data and store it in variable lv_body
*...
*...
TRY.
cl_cuan_http_helper=>s_get_instance( )->http_call(
EXPORTING
iv_destination = '<SM59_ENTRY>'
iv_url
= '/sap/opu/odata/sap/api_mkt_interaction_srv/
InteractionsDeepInsert'
iv_method
= 'POST'
iv_body_send
= lv_body
it_header_fields = lt_header_fields
it_cookies
= lt_cookies
IMPORTING
ev_body_receive = lv_body_receive
ev_status_code = lv_status_code
).
CATCH cx_cuan_cpred_error INTO exc_cpred_error.
* Error handling
ENDTRY.
IF ( lv_status_code = '403' ).
* generate new CSRF-Token and session cookie and try again go to step 1
*...
*...
ENDIF.
ENDWHILE.
Code Syntax
*************************************************************************
* Terminate the session cookie
*************************************************************************
TRY.
cl_cuan_http_helper=>s_get_instance( )->http_call(
EXPORTING
iv_destination
= 'E3W'
iv_url
= '/sap/public/bc/icf/logoff'
iv_method
= 'GET'
iv_body_send_as_string = lv_basis
it_header_fields
= lt_header_fields
it_cookies
= lt_cookies
IMPORTING
ev_body_receive
= lv_body_receive
ev_status_code
= lv_status_code
).
CATCH cx_cuan_cpred_error INTO exc_cpred_error.
* Error handling
ENDTRY.
Integration Guide Integration APIs
PUBLIC
399
5.1.6 Best Practices and Recommended Package Sizes
This section contains best practices for optimizing data load of master data entities, recommended package sizes, and some troubleshooting tips.
General Recommendations
Object Type All entities
Contacts
Recommendations
When you upload entities synchronously, parallel upload of entities is not allowed since this can lead to data inconsistencies.
As a general principle, upload master data object types before transactional data object types. For example, when you upload data for multiple object types initially, you should do so in the following upload sequence: 1. Product categories 2. Products 3. Interaction Contacts 4. Interactions 5. Marketing Permissions 6. Marketing Subscriptions
Synchronous and Asynchronous Processing
When you import contacts using an OData service, the data is processed asynchronously by de fault. This means that when you trigger a contact import, in most cases an OK response, such as a receipt notification, is returned almost immediately. An exception to this are data uploads that might contain severe errors, such as parse or format errors. These do not return an OK response but an error message. The data you upload lands in a staging area, where it is then further proc essed. To view the processing status of data uploads and to check for errors or success messages, you must open the Import Monitor app. In the event of errors, you can restart or discard the import from the import log. For more information, see Import Monitor [page 404].
You can force imports to be processed synchronously by selecting the flag SAP-CUANForceSynchronousProcessing. In this case, if an error is detected, an error message is re turned immediately.
In a synchronous import of contacts, only contacts with errors are aborted. All contacts within the same package without errors are imported successfully. You should refer to the Import Monitor to check for errors, correct the errors and post these contacts again.
In an asynchronous import of contacts, in the event of errors, you can correct the errors and re start the import from the Import Monitor directly.
Do not mix different types of services for operations involving the same data source for the same business entity. For example, when importing contacts from a web shop, do not use one service for a PUT operation and a different service to PATCH contacts. You should, however, migrate from CUAN_IMPORT to the API* services.
400
PUBLIC
Integration Guide Integration APIs
Object Type Interactions
Recommendations
Synchronous and Asynchronous Processing
Import packages that contain up to 999 interactions are processed synchronously. Packages with 1000 interactions or more are typically posted to the staging area and are processed asyn chronously.
In a synchronous import of interactions, success notifications are returned immediately. In the event of errors, only a warning notification is returned, indicating that there were problems. To see exact details of any errors that occurred, you must open the Import Monitor app.
In an asynchronous import of interactions, processing is done via the staging area. An OK re sponse is returned in most cases, indicating that the import has landed in the staging area. To see exact details of the import status, that is, whether there were errors or whether the import was successful, you must open the Import Monitor app. An exception to this are data uploads that might contain severe errors, such as parse or format errors. These immediately return an error message from Gateway.
Note
The system automatically tries to restart the import of any interactions that have been blocked and written to the staging area. This takes place every minute for up to 9999 at tempts, taking roughly one week. You can manually process interactions with errors by cor recting the errors, for example, by changing the configuration. For more information, see Im port Monitor [page 404].
The entity InteractionDeepInsert is available to enable better performance for imports. We recommend that you use this entity when importing interaction data. For more information, see Interactions [page 615].
For performance reasons, we recommend that you do not import in BATCH. However, if you do use BATCH imports, you should be aware that a 20x HTTP response code is always returned, whether errors are detected or not. You should always refer to the Import Monitor app to check the status messages of your imports. Additionally, you should also check the response message in case a technical error occurred. These are not listed in the Import Monitor.
Integration Guide Integration APIs
PUBLIC
401
Object Type
Recommendations
Marketing Permis sions and Market ing Subscriptions
When you import marketing permissions or marketing subscriptions using the OData services API_MKT_CONTACT (version 0004), API_MKT_CORPORATE_ACCOUNT (version 0003) or API_MKT_INTERACTION_CONTACT (version 0003), data is processed asynchronously by de fault. During asynchronous processing, you will receive an OK response, such as a receipt notification. Only in the event that the payload is not supplied correctly, an error message and an http code > 400 is returned. Such errors are:
Payload cannot be parsed because of an error Format errors Key fields are not supplied properly You can monitor the asynchronous processing by launching the Import Monitor App. In the case of errors, you can restart or discard the messages from the import log.
When you use synchronous processing and the data could not be processed properly, error mes sages are returned immediately to the caller. An error message is returned and the http code will be larger than 400. You will not find these entries in the Import Monitor app.
Note
Be aware that in case of errors, the whole payload is rejected and nothing is posted. If you want to use synchronous processing, you have to set the field SAP-CUANForceSynchronousProcessing to true. You also have to take into account that there might be timeout when sending large payloads with synchronous calls, resulting in data loss. This is avoided during asynchronous processing.
Recommendation
We recommend asynchronous processing for mass data.
As marketing permissions and marketing subscriptions are separate entities as of version 0003 of the API services, you have to populate both nodes if you want to send marketing permissions and marketing subscriptions.
Recommendation
For the initial load, we recommend that you choose a two-step approach: Loading contacts in a first step and loading marketing permissions and marketing subscriptions in a second step after the initial load of contacts has been finished. If you want to send contacts and marketing permissions and marketing subscriptions at the same time, ensure that you send all entities within one request, which will ensure the processing in a proper sequence.
To avoid locking problems, all marketing permissions and marketing subscriptions belonging to a contact should be part of one package.
402
PUBLIC
Integration Guide Integration APIs
Recommended Package Sizes
Object Type
Package Sizes
All entities Contacts
The maximum supported OData request size is 100 megabytes. Depending on your package size, we recommend using at most 5 parallel sessions to load the
data. If you load asynchronously, try increasing the number of concurrent sessions incrementally. Start with just two, then three, and so on.
OData
The recommended package size is 1000 entities per request.
Note
If you send contacts together with their marketing permissions and subscriptions (which is what we recommend), you have to make sure that the sum of all entities does not exceed 1000. For example, 100 contacts with their 900 permissions/subscriptions amounts to 1000 entities. Therefore, you should calculate the average number of permissions and subscrip tions per contact in advance.
More than 10000 will result in error. We recommend to use the default asynchronous processing mode for initial loads.
Interactions
OData API_MKT_INTERACTION The general recommendation is 1000-5000 interactions including sub-nodes. The fewer sub-no des and the less data contained in the sub-nodes, the more interactions can be imported. See also the information above about asynchronous processing [page 401]. We recommend that you do not import single data records. Where possible, interaction imports should always be bundled. Maximum Package Sizes
Without subnodes or long Edm Strings: Max. 50000
Note
You can check the content of Edm Strings in the metadata, which is linked in the section Technical Field Documentation for every API service.
Products
Product Catego ries
Agreements
Without products, 2 interests (on average): 20000 With 5 products, 5 Interests (no long Edm Strings): 5000 With 5 products, 5 Interests (with long Edm Strings): 1000 - 2000 CSV CSV imports are only recommended for test purposes and for small volumes of data. Max. 10000 (memory restricted) Maximum package size: 10000
Maximum package size: 10000
Maximum package size: 10000
Integration Guide Integration APIs
PUBLIC
403
Object Type
Package Sizes
Interests
500 (2 Languages)
Marketing Permis sions and Market ing Subscriptions
Note
Performance basically depends on which other processes are running in parallel in marketing.
Do not use a packages size that exceed 1000 data sets. Use parallel processing. Sending multiple requests in parallel will increase the performance. We
recommend sending 10 to 20 parallel requests. More than 10000 entries per package will result in an error.
Related Information
Import Monitor [page 404] HTTP Response Status Codes [page 408]
5.1.7 Import Monitor
Monitor and explore data imports that are triggered by OData or upload services from external systems.
With this app, administrative users can monitor the data import from outside SAP Marketing Cloud. You can import data via upload services, or OData services.
Within the integration of marketing with sales, data are transferred from SAP Cloud for Customer, and SAP CRM to SAP Marketing Cloud via SAP Cloud Integration. The data import into SAP Marketing Cloud is done by OData services.
As a marketing administrative user, you can handle import notifications that are caused by the import of business partner or business document data from SAP Cloud for Customer, and SAP CRM to SAP Marketing Cloud. SAP Marketing Cloud generates a list of notifications with the related status that denotes the progress of a data import:
Notifications
You can select an import notification from a list that provides all notifications including important metadata, such as service name, date, size, status. The system lists all import notifications grouped by their status: In Process: The notification is not yet finalized. Data import is not complete so far. Error: The import notification has caused an error, for example because of mapping errors. Data import has
not taken place.
404
PUBLIC
Integration Guide Integration APIs
Success: The notification is processed. Data import is finalized.
Note
You can find detailed information for import notifications under Messages available under Data .
, the data records are
Details of an Import Notification
For each import notification, the system provides the following detailed grouped information for the File Import:
Import Notification Size: The number of data records processed in an import notification Interface: The interface that has triggered the data import Service Name: The service, for example an OData service that has triggered the import of data, such as business partners, business documents, or marketing attributes Source System: Source system of the data records to be transferred Created By: The technical user used for import processing. Force Synchronous Processing: Indicates whether data is stored for the import notification or not, and whether a restart of the notification is possible or not: Yes: No data is available to inspect and a restart is not possible No: Data is available to inspect and a restart is possible. Reference message that allows you to identify the message in all involved systems, such as middleware or sending system, with different monitoring tools: SAP Cloud Integration (Middleware) In SAP Cloud Integration, choose Operations, and under Monitor Message Processing click on All Integration Flows. Enter the Reference Message ID under Application Message ID. The system displays the message. If Message Tracing is activated, you can also display the message payload. Source system SAP Cloud for Customer In SAP Cloud for Customer, navigate to the Web Service Message Monitoring under Administration. Open the Advanced Search, enter the Reference Message ID in search field Message ID, and choose Go. The system displays the original message. Source System SAP CRM To find the original message in source system SAP CRM you have to carry out multiple steps: In SAP Cloud Integration, choose Operations, and under Monitor Message Processing click on All Integration Flows. Enter the Reference Message ID under Application Message ID. The system displays the message. Click on Message Processing Log, and search for string com.sap.sod.utils.idoc.soap.idocassign. The system displays one or more entries, as follows: com.sap.sod.utils.idoc.soap.idocassign0= [0000000000006115,0000000000081447] The second number displayed in the square brackets is the IDoc number. In the SAP CRM system, call transaction IDoc List (WE05), and search for the corresponding IDoc with the IDoc number copied from SAP Cloud Integration.
Timestamps Date and time, when the notification was generated or changed.
Integration Guide Integration APIs
PUBLIC
405
External: Timestamp of the arrived import notification as set from sender system; Local time of the sender.
External (UTC): Timestamp of the arrived import notification as set from sender system; Universal date and time.
Created: Timestamp of the arrived import notification as set from receiving system; Local time of the user.
Changed: Timestamp of the latest change of the import notification as set from the receiving system; Local time of the user.
Status Status of the notification Number of messages
Messages about the performed notification
Data for all import notifications with status Error.
Note
Errors, that is, data records that cannot be saved in SAP Marketing Cloud, can be caused by the following reasons:
Data is locked by another user Customizing data is missing, such as origins of contact IDs, because the relevant BC set was not
unpacked Mapping errors occurred in SAP Cloud Integration
By restarting or discarding, the notification errors can be resolved. For mapping errors, you can only discard the notification, because the error must be resolved in the relevant SAP Cloud Integration system.
Features
The following features are available: Features Overview of Import Monitor Feature Multiple Selection
Search Sort
406
PUBLIC
Description
You can select several import notifications, and restart or discard them in one step. You can search for import notifications by entering the user name, or the notification ID.
You can sort the import notifications by: Service name Source system Data and time, ascending, or descending
Integration Guide Integration APIs
Feature Restart
Discard Share Data Messages
Description
You can select a notification, and Restart it to recheck to processed data. Example: For notifications with status Error you can trigger actions to resolve the error. After the correction, you can restart the notification, that is, the processing of the imported data, to check whether your correction was successful. The notification status then turns to Successful.
Note
If no restart is possible for the current import notification you can correct error only externally, that is, in the source system, or in the middleware system.
You can Discard a notification that is no longer necessary or valid.
You can share the notification via email, or on SAP Jam.
You find data records of the current data import, with status Error. By Show Full Reord, all fields of a data record are revealed. You can switch between the different data records using Previous Record, and Next Record.
You find all messages generated by the current import notification. The messages contain descriptions of the activities per formed for a notification, classified by their severity: Information, Warning, or Error. You find detailed information for a message, if available, underMore Information.
5.1.8 Data Load Monitor
Monitor all import messages and keep track of their status. The Data Load Monitor app enables you to optimize your data imports by enabling you to: View import messages across the landscape and decide what action to take. Correct errors in the Marketing or in the source systems in a timely fashion and restart imports. Analyze imports and messages by multiple dimensions, and quickly resolve issues. Identify system issues that may have been previously hidden.
Integration Guide Integration APIs
PUBLIC
407
View various status messages such as success messages, errors, and warnings to identify issues with data mapping or system configuration.
Video (English Only)
This short video shows how the Data Load Monitor can support you in safeguarding the quality of data imports.
Analyzing Import Errors
The Data Load Monitor collects all import messages (errors, warnings, and success messages) and displays the number of times individual messages occur across all imports. We recommend that you use the app to preform error analysis on a regular basis, eliminate frequent causes of error, and so optimize the quality of your data imports. Error analysis can be done in 4 simple steps:
1. Gain an overview of the errors and warning occurring in your imports by setting the filter options according to your requirements.
Note
There are a large number of filter options available in the Compact Filters, for example, import header, import service used, or source system ID. Note, however, that you cannot search on individual payload content. Use the Import Monitor app if you want to analyze specific payloads.
2. Analyze the list of errors and warnings and decide which errors can be fixed in the Marketing system, and which errors must be fixed in the source system.
3. When you have fixed all possible errors, filter the list for all messages that have been fixed and choose Restart All to restart these imports.
4. You can then use the Discard All function to discard all other entries in the list.
Related Information
Best Records Videos - Best Practices for Data Load [page 388]
5.1.9 HTTP Response Status Codes
Every HTTP request that is received by a server is responded to with a 3-digit HTTP status code. They are grouped into five classes. The class of a status code can be quickly identified by its first digit:
408
PUBLIC
Integration Guide Integration APIs
1xx: Informational 2xx: Success 3xx: Redirection 4xx: Client Error 5xx: Server Error
Note
HTTP errors are often caused by incorrect URLs, interconnected proxy servers, or by slow processing in a system. Some typical 4xx and 5xx error codes are described in the next section.
5.1.9.1 Client Errors (4xx)
Client errors, or HTTP status codes from 400 to 499, are the result of HTTP requests sent by a HTTP client. Even though these types of errors are client-related, it is often useful to know which error code a user is encountering to determine if the potential issue can be fixed by server configuration.
Error Code 400 Bad Request 401 Unauthorized
403 Forbidden 404 Not Found
Description
The 400 status code, or Bad Request error, means the HTTP request that was sent to the server has invalid syntax.
The 401 status code, or an Unauthorized error, means that the user trying to access the re source has not been authenticated or has not been authenticated correctly. This means that the user must provide credentials to be able to view the protected resource. An example scenario where a 401 Unauthorized error would be returned is if a user tries to access a re source that is protected by HTTP authentication if enters invalid username and password.
The 403 status code, or a Forbidden error, means that the user made a valid request but the server is refusing to serve the request, due to a lack of permission to access the requested resource.
The 404 status code, or a Not Found error, means that the user is able to communicate with the server but it is unable to locate the requested resource.
Integration Guide Integration APIs
PUBLIC
409
5.1.9.2 Server Errors (5xx)
Server errors, or HTTP status codes from 500 to 599, are returned by server when it is aware that an error has occurred or is otherwise not able to process the request.
Error Code 500 Internal Server Error 502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Description
The 500 status code, or Internal Server Error, means that server cannot process the request for an unknown reason.
The 502 status code, or Bad Gateway error, means that the server is a gateway or proxy server, and it is not receiving a valid response from the backend servers that should actually fulfill the request.
The 503 status code, or Service Unavailable error, means that the server is overloaded or under maintenance. This error implies that the service should become available at some point.
The 504 status code, or Gateway Timeout error, means that the server is a gateway or proxy server, and it is not receiving a response from the backend servers within the allowed time period.
5.2 Contact Profiling
The following integration APIs are available in the context of contacts:
Contacts [page 412] Public OData API (API_MKT_CONTACT_SRV Version 4) for reading and writing master data about Contacts. Contacts are natural persons who interact with your company.
Interaction Contacts [page 469] Public OData API (API_MKT_INTERACTION_CONTACT_SRV Version 3) for Interaction Contacts. Interaction Contact is a generic term to group all natural persons (contacts, consumers, or suspects), companies and "unknowns", who interact with your company.
Corporate Accounts [page 512] Public OData API (API_MKT_CORPORATE_ACCOUNT_SRV Version 3) for reading and writing master data about Corporate Accounts only. Corporate accounts are companies or organizations that interact with your company. The public API for Corporate Account supports operations on the Corporate Account Business Object and the Marketing Permissions Business Object.
Business Partners from SAP Cloud for Customer [page 555] Import business partners from SAP Cloud for Customer via CUAN_BUSINESS_PARTNER_IMP_SRV to marketing.
Import Business Partners [page 574] CUAN_BUSINESS_PARTNER_IMPORT_SRV for importing business partner data from external source systems, like, for example, SAP ERP, SAP CRM, SAP S/4HANA On Premise.
410
PUBLIC
Integration Guide Integration APIs
Products [page 582] Public OData API (API_MKT_PRODUCT_SRV) for Products.
Product Hierarchies and Categories [page 604] Public OData API (API_MKT_PRODCAT_HIERARCHY_SRV) for Product Hierarchies and Categories.
Interactions [page 615] Public OData API (API_MKT_INTERACTION_SRV) for Interactions.
Interest Items [page 648] Public OData API (API_MKT_INTEREST_SRV) for InterestItems. An interest represents the content or subject of a contact's interaction.
Business Documents [page 661] Public OData API (CUAN_BUSINESS_DOCUMENT_IMP_SRV) for importing business documents, such as leads and opportunities, from external SAP or non-SAP systems to SAP Marketing Cloud. Use this version of the service when you want to import business documents related to Offers and Coupons. Lower versions are not suitable for this purpose.
Agreements [page 681] Public OData API (API_MKT_AGREEMENT_SRV) for agreements. An agreement can be any kind of customer contract, for example, a sales contract or a contract that comprises specific services.
Scores [page 700] Public OData API (API_MKT_SCORE_SRV) for Scores
Marketing Locations [page 710] Public OData API (API_MKT_LOCATION) for Marketing Locations. A marketing location is any physical or virtual location where a marketing activity can be conducted.
Classifications (Deprecated) [page 722] Public OData API (API_MKT_ML_CLASSIFICATION, deprecated) for reading and writing data about classifications. A classification is the truth about whether a certain event in the past or not. You define this event yourself.
Marketing Attribute Categories [page 735] OData API (API_MKT_ATTRIBUTE_CATEGORY) for writing master data about marketing attribute categories. Marketing attribute categories are freely-definable classifications of information that can be assigned to customers, for instance, to store their hobbies or education history.
Import Monitoring [page 740] Public OData API (API_MKT_IMPORT_MONITORING) for reading messages output for a specific data import using the import header ID. This service can be used by all API services whose imports are processed via the staging area.
Integration Guide Integration APIs
PUBLIC
411
5.2.1 Contacts
Public OData API (API_MKT_CONTACT_SRV Version 4) for reading and writing master data about Contacts. Contacts are natural persons who interact with your company.
Note
We recommend that you use the current version 4 of this service. Do not revert to using version 3, once you start using version 4 since this may result in data inconsistencies. However, if you want to continue using one of the previous versions, you'll find the help links here: Contacts API, Version 3: Contacts API, Version 0003 Version 2 of Contacts, Interaction Contacts, and Corporate Accounts: Contact, Interaction Contact,
Corporate Account API, Version 0002
Technical Data
Caution
The API services available in SAP Marketing Cloud must not be used for mass read (GET) operations. In other words, you cannot use them for extracting all available data, for example, to extract millions of contacts or interactions from your marketing system.
Name of the Service Authorizations
Communication Scenario ID Component for Incidents
API_MKT_CONTACT
The following business catalog roles are required: For version 4: SAP_CEC_BC_MKT_API_IC4_PC For version 3: SAP_CEC_BC_MKT_API_IC3_PC For version 2: SAP_CEC_BC_MKT_API_IC2_PC
SAP_COM_0207
CEC-MKT-DM-IC (Interaction Contacts) CEC-MKT-DM-PER (Permissions and Subscriptions)
Note
Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408].
OData Version Root URI
2.0
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_CONTACT_SRV;v=0004
412
PUBLIC
Integration Guide Integration APIs
Service Metadata URI Field Extensibility Supported
https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$metadata
Yes. For more information, search for extensibility in Structure of OData Service API_MKT_CONTACTS [page 418].
Note
You need to open the collapsible sections of the docu ment first.
Technical Field Documentation
You can access detailed technical documentation for the API fields by downloading a metadata file in one of the following ways:
Access Link
Remarks
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$me tadata?sap-documentation=all
Only for internal access. You need to provide the server and port names.
Marketing - Contacts Details Page
General access to the Details page of the service on SAP API Hub. One-time regis tration is required for first-time users.
1. On the Details page, click Download Specification and download as EDMX. 2. Specify which application you want to use to open the EDMX file type.
Contacts API
General access link takes you directly to the Contacts metadata file. One-time registration or logon is required.
Note
You can convert the XML file to an XML table to make it easier to read.
Please note the meaning of the following values in the file:
Metadata Value in XML sap:updatable sap:creatable nullable
Basic Concepts [page 414]
Meaning When FALSE read-only field read-only field mandatory field
Integration Guide Integration APIs
PUBLIC
413
The public API for Contacts API_MKT_CONTACT_SRV supports operations on the Interaction Contact Business Object and the Marketing Permissions Business Object. There is no separate public OData API for marketing permissions. The corresponding entity is part of this service since marketing permissions are always stored for a certain interaction contact. Structure of OData Service API_MKT_CONTACTS [page 418] This document describes the structure of the Public OData API service API_MKT_CONTACT. Payload Examples [page 445] Payload examples for API_MKT_CONTACT. Function Imports [page 464] Function imports are used to perform custom operations on an entity, which are typically not provided by OData operations. This section contains payload examples for the following function imports:
5.2.1.1 Basic Concepts
The public API for Contacts API_MKT_CONTACT_SRV supports operations on the Interaction Contact Business Object and the Marketing Permissions Business Object. There is no separate public OData API for marketing permissions. The corresponding entity is part of this service since marketing permissions are always stored for a certain interaction contact.
Note
For generally applicable recommendations and best practices, make sure you refer to the section Best Practices and Recommended Package Sizes [page 400].
Switching to Version 4
Version 0004 of API_MKT_CONTACT_SRV is the prerequisite if you implement the B2B function Contact-toAccount Relationships. Regardless of whether you implement Contact-to-Account Relationships, we strongly recommend that you use version 0004 of this service for importing contacts. If you switch from a lower version of the service to version 0004, please note the following: If you migrate from API_MKT_CONTACT_SRV_0002 to API_MKT_CONTACT_SRV_0004, be aware that
version 0002 had only one entity MarketingPermission for both Permissions and Subscriptions, whereas in version 0004 there are separate entities for Permissions and Subscriptions. Email, phone, mobile and fax IDs can now only be imported as AdditionalID entities. In previous versions, these sub-entities were imported as part of the OriginData entity. So what happens to existing IDs that you previously loaded using another service? The table explains what happens to existing email, fax, phone, and mobile IDs when you start importing data with version 0004.
414
PUBLIC
Integration Guide Integration APIs
Operations with API_MKT_CONTACT_0004 If You Perform This Operation
Are Existing IDs Deleted?
PUT on OriginData
Yes
PUT on OriginData and AdditionalIDs
Yes
PUT on OriginData and AdditionalIDs and Function Import ContactOriginDeleteAddi Yes tionalIDs
PUT on AdditionalIDs
No
PUT on AdditionalIDs and Function Import ContactOriginDeleteAdditionalIDs
Yes
PATCH on OriginData
No
PATCH on OriginData and AdditionalIDs
No
PATCH on OriginData and AdditionalIDs and Function Import ContactOriginDeleteAd Yes ditionalIDs
PATCH on AdditionalIDs
No
PATCH on AdditionalIDs and Function Import ContactOriginDeleteAdditionalIDs
Yes
Function Import ContactOriginDeleteAdditionalIDs
Yes
Sample Use Cases If You Want To
The Recommended Method Is
Perform a full update of a contact in a running system
PATCH on OriginData, Function Import ContactOriginDele teAdditionalIDs, and PATCH on AdditionalIDs
Add an additional ID to an existing contact, for example, a cookie ID
PUT on AdditionalID
Read contact data out of the system
GET Request on relevant entity
Processing Info and Best Practices
The minimum data required when importing contacts is an ID, an ID Origin, a timestamp, and at least one other attribute.
When to use PUT and PATCH: PUT requests are most suitable for an initial data import, for example, when you want to create a new contact. A PUT request requires that you always send all properties. Any properties that you omit are overwritten by blank entries. That is, any existing entries are deleted. If no record is found, a new record is created. In other words. the PUT request functions as a full upsert. We recommend that you use PATCH requests for all other imports. A PATCH request updates only the properties provided in the request body and leaves everything untouched that was not provided. So,
Integration Guide Integration APIs
PUBLIC
415
you can omit all properties that are not to be changed. Like the PUT request, if no record is found, a new record is created with the available properties. In other words. the PATCH request functions as a delta upsert.
An additional advantage of using PATCH is that you specify your own sequence ID. For this reason, it is more flexible than a PUT operation, where the sequence ID is set by default and cannot be changed.
Basically, since you can use PATCH with the same payload as you would use for PUT, the PATCH operation is more universal and you can work with it exclusively.
We recommend that you don't mix PUT and PATCH operations. Doing so can lead to unwanted results since a PUT operation is processed before a PATCH.
Do not combine a DELETE operation with other OData operations in one changeset. We recommend that you do not combine the OData operations PUT, PATCH, POST, with a DELETE operation in the same changeset. For example, let's say you want to update data for Contact A by adding an additional email address and at the same time delete a mobile number that is no longer valid. So, you send a PUT operation on the AdditionalId entity with the new email address and a DELETE operation within the same changeset. One of these operations could cancel out the other and the resulting dataset will not be as intended. Recommended Practice: For such combined operations including a DELETE operation, we recommend that you always use the relevant function import, which allows deletion of specific entities, together with the appropriate OData operation PUT, PATCH, or POST within the same changeset.
Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service as described in [OData-URI ]. The batch request must contain a header parameter content-type, specifying the value multipart/mixed and boundary=batch.
Use of codes versus free text: The properties listed in the left column of the table require code values. Incorrect codes will result in import errors, indicating that the corresponding code is not valid. If you are not thoroughly familiar with the internal codes available in SAP Marketing for these properties, you should use properties that allow a free text. For example, if you do not know that DE is the country code for Germany, you can use Germany as the free text.
Code in SAP Marketing Country Industry Department Function GenderCode Language MaritalStatus AddressRegion FormOfAddress
Free Text Property CountryName IndustryName DepartmentName ContactFunctionName GenderCodeName LanguageName MaritalStatusName RegionName FormOfAddressName
You must map your free text names to the available codes in the Map Free Text app. For more information, see Map Free Texts.
Do not mix different types of services for operations involving the same data source. For example, when importing contacts from a web shop, do not use the CUAN_IMPORT service for a PUT operation and then the API_MKT_CONTACT service to PATCH contacts. You can, however, migrate from CUAN_IMPORT to the API* services.
416
PUBLIC
Integration Guide Integration APIs
The origin that you pass via the property ContactOrigin cannot be shareable. If the main origin is set to Shareable, this will trigger an error. For more information, see Configuring Origins. You can view sample payloads and test the API at https://api.sap.com/api/API_MKT_CONTACT_SRV_0004/resource .
UTC Timestamp of Permissions: The UTC timestamp of permissions cannot lie in the future. When you import permissions, they must not have a timestamp that lies in the future. The timestamp of imported permissions is always in UTC. The field name in the OData service is called PermissionUTCDateTime. If you want to use your local timestamp, you have to add the time zone information, that is, your local time zone together with the time zone offset or enter a timestamp that is converted to UTC.
Example
The date and time information is adapted by the standard time difference (offset) with +01:00 for Central European Time (CET) or -05:00 for Eastern Standard Time (EST). For example: 2019-01-01T12:00:00+01:00
If you live east of UTC and enter your timestamp in your local time zone without time zone offset, this will result in a future timestamp. For example, you live in Germany and your local time is 8 a.m on November, 28. If you enter this as the UTC timestamp without a time zone offset, the UTC permission timestamp will show as 8 a.m., November 28, while in the UTC time zone it is 7 a.m., November 28. You have created a UTC permission timestamp that lies in the future and is invalid.
Error Messages
If the OData service is not accessible, for example due to missing authorization, or because the system is not available, a corresponding HTTP status code is returned.
If the OData service is accepted by the gateway component in the SAP Marketing Cloud system, the HTTP status code 201 or 204 is returned. Any processing errors are recorded in the SAP Marketing Cloud system in the Import Monitor app, where they can be monitored, restarted and discarded.
By default, data processing for contacts, interaction contacts, corporate accounts, or marketing permissions is asynchronous. In most cases an OK response, such as a receipt notification, is returned almost immediately. An exception to this would be data uploads that might contain severe errors, such as parse or format errors, and so would not return an OK response but an error message. The data you upload lands in a staging area, where it is then further processed. You can change the default setting to synchronous processing by setting the property Sap-Cuan-ForceSynchronousProcessing to True. In this case, any error messages are returned as soon as they are detected.
To view the processing status and to check for errors or success messages, you must launch the Import Monitor app. Messages for marketing permissions in this app are displayed under the API for Contact, API for Interaction Contacts, or API for Corporate Accounts depending on the API OData service you use. In the event of errors, you can restart or discard the import in the Import Monitor.
For more information, see HTTP Response Status Codes [page 408].
Integration Guide Integration APIs
PUBLIC
417
Field Extensibility
You can add customer-specific fields using the Custom Fields app. For more information about how to do this, see Custom Fields App and Custom Logic App. Please enable the Data Source under UIs and Reports: API_MKT_CONTACT_SRV 0004
Parent topic: Contacts [page 412]
Related Information
Structure of OData Service API_MKT_CONTACTS [page 418] Payload Examples [page 445] Function Imports [page 464] Best Practices and Recommended Package Sizes [page 400]
5.2.1.2 Structure of OData Service API_MKT_CONTACTS
This document describes the structure of the Public OData API service API_MKT_CONTACT. Make sure you read these topics before you start: Best Practices and Recommended Package Sizes [page 400] Basic Concepts [page 414]
Request Header
The request header contains the additional header fields listed in the table. Remember to include at least the mandatory request header fields in each payload.
Property
Sap-CuanRequestTimestamp
Example '2017-09-28T12:13:14'
Description
Max.Le Manda
ngth
tory
Timestamp of the import run in
X
this format.
418
PUBLIC
Integration Guide Integration APIs
Property Sap-Cuan-SequenceId
Example PatchAddress
Sap-Cuan-
EXT
SourceSystemType
Sap-Cuan-SourceSystemId HYBRIS
Sap-Cuan-
X
ForceSynchronousProcessi
ng
Sap-Cuan-ReferenceId
345g67980907
Description
Max.Le Manda
ngth
tory
This defines a set of fields that are to be updated, for example, address fields, which can be in terpreted as a field group. The combination of the header fields Sap-Cuan-SequenceId and SapCuan-RequestTimestamp is used to check the sequence of the data received. If the data that is received has a timestamp older than already imported data, it is ignored.
X (only manda tory for Patch Mode)
Type of source system. This is a 20 free text field.
Identifier of source system. This 255 is a free text field.
This flag is deselected by de fault, which means that up loaded data is processed asyn chronously. On upload, a suc cess message is output immedi ately, unless there are errors such as authorization issues or bad requests. Objects are up loaded to the staging area and processed successively from there. All status messages can be displayed in the Import Monitor app.
You can force imports to be processed synchronously by setting this flag. In this case, an error message will be returned as soon as an error is detected. Such error messages are output in the Import Monitor app
External reference of the in
32
bound message
Integration Guide Integration APIs
PUBLIC
419
Entity Sets
The Contact OData API provides the following entity sets:
Entity Set Contacts AccountTeamMembers AdditionalIDs ContactOriginData
Description
Path
This entity contains all contact informa /Contacts tion from the contact's best record.
This entity contains information about /AccountTeamMembers the account team members.
This entity contains information about /AdditionalIDs contacts' additional IDs.
This entity contains contact origin data. /ContactOriginData
Note
The property OriginDataLastChgUTCDateTi me is mandatory. It must be speci fied.
ContactRelationData
This entity contains information about /ContactRelationData contacts' relationship data.
Note
The property RelationDataLastChgUTCDate Time is mandatory. It must be specified.
ContactRelationAdditionalIDs MarketingAttributes MarketingAreas MarketingPermissions MarketingSubscriptions
This entity contains information about /ContactRelationAdditionalIDs additional IDs of contact relationships.
This entity contains information about /MarketingAttributes marketing attributes.
This entity contains information about /MarketingAreas marketing areas.
This entity contains information about /MarketingPermissions marketing permissions.
This entity contains information about /MarketingSubscriptions marketing subscriptions.
420
PUBLIC
Integration Guide Integration APIs
Entity Set MarketingLocations
Description
Path
This entity contains information about /MarketingLocations marketing locations.
Contacts
GET: Entity Path: /Contacts
Field Extensibility: The following business contexts are relevant: Marketing: Contact and Marketing: Contact and Corporate Account
You can perform the following operations on the Contacts entity set:
HTTP Method GET
Description
Path
Get a list of contacts. This method supports standard /Contacts?$top=1 OData parameters such as $filter, $select, $top,
$skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 contacts can be fetched in a single request
Specification of TOP is mandatory.
Get the details of a specific contact using the Contact UUID.
/Contacts(guid'<Contact UUID>')
AccountTeamMembers
You can perform the following operations on the AccountTeamMember entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ AccountTeamMembers
PUT, PATCH, or DELETE in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$batch
PUT, PATCH, or DELETE in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/AccountTeamMembers (ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',TeamMemberID='<TeamMemb erID>',Role='<Role>')
Integration Guide Integration APIs
PUBLIC
421
HTTP Method GET
POST (Batch)
PUT
Description Get a list of account team members.
Path
/AccountTeamMembers?$top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 account team members can be fetched in a single request
Specification of TOP is mandatory.
Get the details of a specific account team member.
This operation is not supported.
Update or create an account team member in batch mode.(Full Update)
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
Note
The maximum number of requests in a changeset is 10000 (ten thou sand).
Delete an account team member in batch mode.
Add one new account team member.
Update or create an account team member.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ AccountTeamMembers (ContactID='<ContactID>',Contac tOrigin='<ContactOrigin>',TeamM emberID='<TeamMemberID>',Role=' <Role>')
422
PUBLIC
Integration Guide Integration APIs
HTTP Method PATCH
DELETE
Description Add one new account team member.
Delete an account team member.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ AccountTeamMembers (ContactID='<ContactID>',Contac tOrigin='<ContactOrigin>',TeamM emberID='<TeamMemberID>',Role=' <Role>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ AccountTeamMembers (ContactID='<ContactID>',Contac tOrigin='<ContactOrigin>',TeamM emberID='<TeamMemberID>',Role=' <Role>')
AdditionalIDs
You can perform the following operations on the AdditionalIDs entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ AdditionalIDs
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ AdditionalIDs(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',ContactAdd itionalOrigin='<ContactAdditionalOrigin>',ContactAdditionalID='<ContactAdditiona lID>')
Integration Guide Integration APIs
PUBLIC
423
HTTP Method GET
POST (Batch)
Description
Get a list of additional IDs by Contact ID and ID Origin.
Path
/AdditionalIDs?$top=1
This method supports standard OData pa rameters such as $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 additional IDs can be fetched in a single request.
Specification of TOP is mandatory. $filter is not supported for additional
IDs.
Get the details of a specific additional ID.
/ AdditionalIDs('<ContactID>,<Con tactOrigin>,<ContactAdditionalO rigin>,<ContactAdditionalID>')
Note
The maximum number per change set is 10000 (ten thousand) entities.
Update or create an additional ID in batch mode.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
Note
The maximum number of requests in a changeset is 10000 (ten thou sand).
Add one new additional ID.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
424
PUBLIC
Integration Guide Integration APIs
HTTP Method PUT
PATCH
Description Update or create an additional ID.
Add one new additional ID.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ AdditionalIDs(ContactID='<Conta ctID>',ContactOrigin='<ContactO rigin>',ContactAdditionalOrigin ='<ContactAdditionalOrigin>',Co ntactAdditionalID='<ContactAddi tionalID>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ AdditionalIDs(ContactID='<Conta ctID>',ContactOrigin='<ContactO rigin>',ContactAdditionalOrigin ='<ContactAdditionalOrigin>',Co ntactAdditionalID='<ContactAddi tionalID>')
ContactOriginData
You can perform the following operations on the ContactOriginData entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ ContactOriginData
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ContactOriginData(ContactID=' <ContactID>',ContactOrigin='<ContactOrigin>')
Field Extensibility: The following business contexts are relevant: Marketing: Contact and Marketing: Contact and Corporate Account
Integration Guide Integration APIs
PUBLIC
425
HTTP Method GET
POST (Batch)
PUT
Description Get a list of Contact Origin Data.
Path
/ContactOriginData?$top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 contact origin data entities can be fetched in a sin gle request
Specification of TOP is mandatory.
Get the details of specific contact origin data.
/ ContactOriginData('<ContactID>, <ContactOrigin>')
Update or create contact origin data in batch mode. This creates a contact if the contact not exist.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
Note
The property OriginDataLastChgUTCDateTime is mandatory and must be specified.
Delta Update PATCH attributes of the entity ContactOriginData.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
Update or create contact origin data. This cre https://
ates a contact if the contact not exist.
<Server>:<Port>/sap/opu/
odata/SAP/
API_MKT_CONTACT_SRV;v=0004/
ContactOriginData(ContactID='
<ContactID>',ContactOrigin='<Co
ntactOrigin>')
Note
The property OriginDataLastChgUTCDateTime is mandatory and must be specified.
426
PUBLIC
Integration Guide Integration APIs
HTTP Method PATCH
Description
Delta Update PATCH attributes of the entity ContactOriginData.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ ContactOriginData(ContactID=' <ContactID>',ContactOrigin='<Co ntactOrigin>')
Note
The property OriginDataLastChgUTCDateTime is mandatory and must be specified.
ContactRelationData
You can perform the following operations on the ContactRelationData entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ ContactRelationData
PUT, PATCH and DELETE in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$batch
PUT, PATCH and DELETE in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ ContactRelationData(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Rela tionshipCategory='<RelationshipCategory>',ReltdIntactnContactID='<ReltdIntactnCo ntactID>',ReltdIntactnContactOrigin='<ReltdIntactnContactOrigin>')
HTTP Method GET
Description
Path
Get a list of contact relationship data by Con tact ID and ID Origin.
/ContactRelationData?$top=1
This method supports standard OData pa rameters such as $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 entities can be fetched in a single request.
Specification of TOP is mandatory. $filter is not supported for additional
IDs.
Integration Guide Integration APIs
PUBLIC
427
HTTP Method POST (Batch) PUT
Description
Path
Get the details of a specific additional ID.
/ ContactRelationData(ContactID=' <ContactID>',ContactOrigin='<Co ntactOrigin>',RelationshipCateg ory='<RelationshipCategory>',Re ltdIntactnContactID='<ReltdInta ctnContactID>',ReltdIntactnCont actOrigin='<ReltdIntactnContact Origin>')
Update or create contact relationship data in batch mode.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
Note
The property RelationDataLastChgUTC DateTime is mandatory and must be specified.
Add one new contact relationship data. Update or create contact relationship data.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
/ ContactRelationData(ContactID=' <ContactID>',ContactOrigin='<Co ntactOrigin>',RelationshipCateg ory='<RelationshipCategory>',Re ltdIntactnContactID='<ReltdInta ctnContactID>',ReltdIntactnCont actOrigin='<ReltdIntactnContact Origin>')
Note
The property RelationDataLastChgUTC DateTime is mandatory and must be specified.
428
PUBLIC
Integration Guide Integration APIs
HTTP Method PATCH
DELETE
Description Add one new contact relationship data.
Delete contact relationship data.
Path
/ ContactRelationData(ContactID=' <ContactID>',ContactOrigin='<Co ntactOrigin>',RelationshipCateg ory='<RelationshipCategory>',Re ltdIntactnContactID='<ReltdInta ctnContactID>',ReltdIntactnCont actOrigin='<ReltdIntactnContact Origin>')
/ ContactRelationData(ContactID=' <ContactID>',ContactOrigin='<Co ntactOrigin>',RelationshipCateg ory='<RelationshipCategory>',Re ltdIntactnContactID='<ReltdInta ctnContactID>',ReltdIntactnCont actOrigin='<ReltdIntactnContact Origin>')
ContactRelationAdditionalIDs
You can perform the following operations on the ContactRelationAdditionalIDs entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ ContactRelationAdditionalIDs
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ ContactRelationAdditionalIDs(ContactID='<ContactID>',ContactOrigin='<ContactOrig in>',RelationshipCategory='<RelationshipCategory>',ReltdIntactnContactID='<Reltd IntactnContactID>',ReltdIntactnContactOrigin='<ReltdIntactnContactOrigin>',Cntct RelationAdditionalID='<CntctRelationAdditionalID>',CntctRelationAdditionalOrigin ='<CntctRelationAdditionalOrigin>')
Integration Guide Integration APIs
PUBLIC
429
HTTP Method GET
POST (Batch)
Description
Get a list of additional IDs of a contact rela tionship.
Path
/ContactRelationAdditionalIDs? $top=1
This method supports standard OData pa rameters such as $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 additional IDs can be fetched in a single request.
Specification of TOP is mandatory.
Get the details of a specific additional ID of a contact relationship.
/ ContactRelationAdditionalIDs(Co ntactID='<ContactID>',ContactOr igin='<ContactOrigin>',Relation shipCategory='<RelationshipCate gory>',ReltdIntactnContactID='< ReltdIntactnContactID>',ReltdIn tactnContactOrigin='<ReltdIntac tnContactOrigin>',CntctRelation AdditionalID='<CntctRelationAdd itionalID>',CntctRelationAdditi onalOrigin='<CntctRelationAddit ionalOrigin>')
Update or create an additional ID of a contact relationship in batch mode.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
Add one new additional ID of a contact rela tionship.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
430
PUBLIC
Integration Guide Integration APIs
HTTP Method PUT
PATCH
Description
Path
Update or create an additional ID of a contact relationship.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ ContactRelationAdditionalIDs(Co ntactID='<ContactID>',ContactOr igin='<ContactOrigin>',Relation shipCategory='<RelationshipCate gory>',ReltdIntactnContactID='< ReltdIntactnContactID>',ReltdIn tactnContactOrigin='<ReltdIntac tnContactOrigin>',CntctRelation AdditionalID='<CntctRelationAdd itionalID>',CntctRelationAdditi onalOrigin='<CntctRelationAddit ionalOrigin>')
Add one new additional ID of a contact rela tionship.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ ContactRelationAdditionalIDs(Co ntactID='<ContactID>',ContactOr igin='<ContactOrigin>',Relation shipCategory='<RelationshipCate gory>',ReltdIntactnContactID='< ReltdIntactnContactID>',ReltdIn tactnContactOrigin='<ReltdIntac tnContactOrigin>',CntctRelation AdditionalID='<CntctRelationAdd itionalID>',CntctRelationAdditi onalOrigin='<CntctRelationAddit ionalOrigin>')
Projections
A projection is the technical term used for the automatically generated best record of a contact from the perspective of the specific relationship the contact has with an account, within a specific marketing area. For more information, see Glossary. You can perform the following operation on the Projections entity set: GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/Projections
Integration Guide Integration APIs
PUBLIC
431
HTTP Method GET
Description Get a list of projections.
Path
/Projections?$top=2
This method supports standard OData pa rameters such as $select, $top, $skip, $count, $inlinecount, and $orderby
MarketingAttributes
You can perform the following operations on the MarketingAttributes entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ MarketingAttributes
PUT, PATCH, or DELETE in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$batch
PUT, PATCH, or DELETE in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ MarketingAttributes(ContactID='<ContactID>',ContactOrigin=' <ContactOrigin>',MarketingAttributeCategory='<MarketingAttributeCategory>',Marke tingAttributeValue='<MarketingAttributeValue>')
Field Extensibility: The following business context is relevant: Marketing: Marketing Attributes for Contacts
HTTP Method GET
Description
Get a list of marketing attributes by Contact ID and ID Origin.
Path
/MarketingAttributes?$top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 marketing at tributes can be fetched in a single re quest
Specification of TOP is mandatory.
Get the details of a specific marketing attrib ute.
/ MarketingAttributes('<ContactID >','<ContactOrigin>','<Marketin gAttributeCategory>','<Marketin gAttributeValue>')
432
PUBLIC
Integration Guide Integration APIs
HTTP Method POST (Batch)
PUT PATCH
Description Update or create marketing attributes in batch mode. Delete marketing attributes in batch mode. Add one new marketing attribute. Update or create marketing attributes.
Add one new marketing attribute.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ MarketingAttributes(ContactID=' <ContactID>',ContactOrigin=' <ContactOrigin>',MarketingAttri buteCategory='<MarketingAttribu teCategory>',MarketingAttribute Value='<MarketingAttributeValue >')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ MarketingAttributes(ContactID=' <ContactID>',ContactOrigin=' <ContactOrigin>',MarketingAttri buteCategory='<MarketingAttribu teCategory>',MarketingAttribute Value='<MarketingAttributeValue >')
Integration Guide Integration APIs
PUBLIC
433
HTTP Method DELETE
Description Delete marketing attributes.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ MarketingAttributes(ContactID=' <ContactID>',ContactOrigin=' <ContactOrigin>',MarketingAttri buteCategory='<MarketingAttribu teCategory>',MarketingAttribute Value='<MarketingAttributeValue >')
MarketingAreas
You can perform the following operations on the MarketingAreas entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004 PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/
API_MKT_CONTACT_SRV;v=0004/$batch PUT, PATCH in a sngle operation: https://<Server>:<Port>/sap/opu/odata/SAP/
API_MKT_CONTACT_SRV;v=0004/ MarketingAreas(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Interacti onContactMktgArea='<InteractionContactMktgArea>')
HTTP Method GET
Description
Get a list of marketing areas by Contact ID and ID Origin.
Path
/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ Contacts? $expand=MarketingAreas&$top=2
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 marketing areas can be fetched in a single re quest
Specification of TOP is mandatory.
434
PUBLIC
Integration Guide Integration APIs
HTTP Method POST (Batch)
PUT PATCH
Description Get the details of a specific marketing area. Update or create marketing areas in batch mode.
Add one new marketing area. Update or create marketing areas.
Add one new marketing area.
Path
/ MarketingAreas('<ContactID>,<Co ntactOrigin>,InteractionContact MktgArea>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch/ MarketingAreas('<ContactID>,<Co ntactOrigin>,InteractionContact MktgArea>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ MarketingAreas(ContactID='<Cont actID>',ContactOrigin='<Contact Origin>',InteractionContactMktg Area='<InteractionContactMktgAr ea>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ MarketingAreas(ContactID='<Cont actID>',ContactOrigin='<Contact Origin>',InteractionContactMktg Area='<InteractionContactMktgAr ea>')
MarketingLocations
You can perform the following operations on the MarketingAreas entity set:
GET: /MarketingAreas('https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/MarketingLocations
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0004/
Integration Guide Integration APIs
PUBLIC
435
MarketingLocations(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>', MarketingLocationExternalID='< MarketingLocationExternalID>')
HTTP Method GET POST (Batch)
PUT
PATCH
Description
Path
Get a list of marketing locations by Contact ID and ID Origin.
/MarketingLocations?$top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Update or create marketing areas in batch mode.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
Add one new marketing area
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/$bat ch
Update or create marketing locations
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ MarketingLocations(ContactID='< ContactID>',ContactOrigin='<Con tactOrigin>', MarketingLocationExternalID='< MarketingLocationExternalID>
Add one new marketing location
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0004/ MarketingLocations(ContactID='< ContactID>',ContactOrigin='<Con tactOrigin>', MarketingLocationExternalID='< MarketingLocationExternalID
MarketingPermissions
Entity Path: /MarketingPermissions Field Extensibility: The following business context is relevant: Marketing: Marketing Permissions. Custom fields for business object MKT_PERMISSION (Marketing: Permission) are only supported if you use version 2 or version 3 of the API_MKT_CONTACT service.
436
PUBLIC
Integration Guide Integration APIs
Note
For all HTTP operations both $batch requests and single requests can be used. Interactions are assigned when marketing permissions are created or updated to allow for analysis of
contacts.
You can perform the following operations on the MarketingPermissions entity set:
HTTP Method GET
Description
Path
Get a list of marketing permissions by Contact /MarketingPermissions?$top=1 ID and ID Origin. This method supports stand ard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 marketing per missions can be fetched in a single request
Specification of TOP is mandatory.
PATCH PUT
Update or create marketing permissions. This creates a marketing permission if the permis sion does not exist.
Delta Update of PATCH attributes of the entity MarketingPermission.
/ MarketingPermissions(ContactID= '<ContactID>',ContactOrigin='<C ontactOrigin>',ContactPermissio nID='<ContactPermissionID>',Con tactPermissionOrigin='<ContactP ermissionOrigin>',MarketingArea ='<MarketingArea>',Communicatio nMedium='<CommunicationMedium>' )
Update or create marketing permissions. This creates a marketing permission if the permis sion does not exit.
/ MarketingPermissions(ContactID= '<ContactID>',ContactOrigin='<C ontactOrigin>',ContactPermissio nID='<ContactPermissionID>',Con tactPermissionOrigin='<ContactP ermissionOrigin>',MarketingArea ='<MarketingArea>',Communicatio nMedium='<CommunicationMedium>' )
Marketing Permission Property Descriptions The table describes the properties for the MarketingPermissions entity.
Integration Guide Integration APIs
PUBLIC
437
MarketingPermissions Property Names and Descriptions
Property Name
Property Description
Usage
ContactID
The ContactID and ContactOrigin iden tify the contact uniquely.
Example: a business partner ID from the CRM system.
ContactOrigin
The ContactID and ContactOrigin iden tify the contact uniquely.
The ContactID will not be saved to the MarketingPermission but is only used to derive a unique ContactUUID. This data will not be returned in GET re quests.
Example: SAP_CRM_BUPA
ContactPermissionID
The ContactPermissionID and Contact PermissionOrigin store marketing per missions.
Mandatory
Example: first.lastname@mail.de
ContactPermissionOrigin
The ContactPermissionID and Contact PermissionOrigin store marketing per missions.
Mandatory
ContactPermissionOrigin is the origin of a contact ID that stores marketing per missions. The origin indicates the source of an ID. By defining the origin, you determine that a contact with an ID associated to a source can be analyzed.
Example: EMAIL
You can configure origins of contact IDs in the Configuring Origins configuration app.
ContactPermissionOriginName
Description of property ContactPer missionOrigin
Read-Only
MarketingArea
Identifies an area of responsibility or an organizational unit.
You use a marketing area to restrict ac cess to instances of an object, such as campaign, email message, email tem plate, target group, or permission.
Mandatory
The MarketingArea property field must be passed, but can be left empty.
438
PUBLIC
Integration Guide Integration APIs
Property Name MarketingAreaName CommunicationMedium
CommunicationMediumName ContactUUID PermissionGranted PermissionUTCDateTime
PermissionUUID PermissionSourceObject
PermissionSourceObjectType
PermissionSourceSystem
Property Description
Usage
Description of property MarketingArea Read-Only
Represents the type of permission, for Mandatory example, EMAIL or PHONE.
You can configure communication me dia in the Managing Interaction Content configuration app.
Description of property Communica tionMedium
Read-Only
Unique ID of a contact in SAP Marketing Read-Only
Cloud .
The field value is returned internally.
The permission can be YES (Y) or NO (N).
Mandatory
This is the timestamp for when the per Mandatory mission was given or removed.
Note
The timestamp must not be initial or null.
Unique ID of a permission in SAP Marketing Cloud .
Read-Only The field value is returned internally.
This field provides information on the source of the permission, that is, where it came from. For example, the ID of a landing page.
If you enter a value for the Permission SourceObject property, you must also specify a value for the PermissionSour ceObjectType.
This field can be filled with freetext.
Both fields must be filled or left empty.
This field provides information on the source of the permission and its type. For example, the business object name of a landing page.
This field can be filled with freetext.
This is the system that stores the per mission. For example, your local system ID.
This field can be filled with freetext.
If you enter a value for the Permission SourceSystem property, you must also specify a value for the PermissionSour ceSystemType.
Both fields must be filled or left empty.
Integration Guide Integration APIs
PUBLIC
439
Property Name
Property Description
Usage
PermissionSourceSystemType
This is the type of system where the permission is stored. For example, SAP_CEI.
This field can be filled with freetext.
PermissionSourceCommMedium
Indicates where the permission comes from, such as WEB, EMAIL, or PHONE. In case PermissionSourceCommMedium is not filled, this property is set to WEB.
Mandatory
PermissionSourceCommMediumName Description of property Permission SourceCommMedium
Read-Only
PermissionIsImplicit
If the system sets this field to TRUE, then it is an implicit permission, which is determined by country-specific regu lation.
Read-Only
If the system sets this field to FALSE, the contact has given this permission explicitly.
IsConfirmationRequired
This is a boolean parameter. If the pa rameter is set to TRUE, the permission is stored using the double opt-in or optout process.
If the property is not specified in the payload or it is set to FALSE the permis sion is directly stored.
LastChangedByUser
Name of the user who has changed the Read-Only permissions last.
LastChangeDateTime
Date and time of the last permission change.
Read-Only
PermissionNoteText
A text to describe a permission change.
MarketingSubscriptions
Entity Path: /MarketingSubscriptions Field Extensibility: The following business context is relevant: Marketing: Marketing Permissions. Custom fields for business object MKT_PERMISSION (Marketing: Permission) are only supported if you use version 2 or version 3 of the API_MKT_CONTACT service.
440
PUBLIC
Integration Guide Integration APIs
Note
For all HTTP operations both $batch requests and single requests can be used. Interactions are assigned when marketing permissions are created or updated to allow for analysis of
contacts.
You can perform the following operations on the MarketingSubscriptions entity set:
HTTP Method GET
Description
Path
Get a list of marketing subscriptions by Contact ID and ID Origin. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
/ MarketingSubscriptio ns?$top=1
Note
A maximum of 5000 marketing subscriptions can be fetched in a single request
Specification of TOP is mandatory.
PATCH PUT
Update or create subscriptions. This creates a subscription if the subscription does not exit.
/ MarketingSubscriptio ns(ContactID='<Conta ctID>',ContactOrigin ='<ContactOrigin>',C ontactPermissionID=' <ContactPermissionID >',ContactPermission Origin='<ContactPerm issionOrigin>',Commu nicationMedium='<Com municationMedium>',S ubscriptionTopic='<S ubscriptionTopic>')
Update or create subscriptions. This creates a subscription if the subscription does not exit.
Delta Update of PATCH attributes of the entity MarketingSub scriptions.
/ MarketingSubscriptio ns(ContactID='<Conta ctID>',ContactOrigin ='<ContactOrigin>',C ontactPermissionID=' <ContactPermissionID >',ContactPermission Origin='<ContactPerm issionOrigin>',Commu nicationMedium='<Com municationMedium>',S ubscriptionTopic='<S ubscriptionTopic>')
Marketing Subscription Property Descriptions The table describes the properties for the MarketingSubscription entity.
Integration Guide Integration APIs
PUBLIC
441
MarketingSubscription Property Names and Descriptions
Property Name
Property Description
Usage
ContactID
The ContactID and ContactOrigin iden tify the contact uniquely.
Example: a business partner ID from the CRM system.
ContactOrigin
The ContactID and ContactOrigin iden tify the contact uniquely.
The ContactID will not be saved to the MarketingSubscription but is only used to derive a unique ContactUUID. This data will not be returned in GET re quests.
Example: SAP_CRM_BUPA
ContactSubscriptionID
The ContactPermissionID and Contact SubscriptionOrigin store marketing subscription.
Mandatory
Example:
ContactSubscriptionOrigin
The ContactSubscriptionID and Con tactSubscriptionOrigin store marketing subscriptions.
Mandatory
ContactSubscriptionOrigin is the origin of a contact ID that stores marketing subscriptions. The origin indicates the source of an ID. By defining the origin, you determine that a contact with an ID associated to a source can be analyzed.
Example: EMAIL
You can configure origins of contact IDs in the Configuring Origins configuration app.
ContactSubscriptionOriginName
Description of property ContactSub scriptionOrigin
Read-Only
CommunicationMedium
Represents the type of subscription, for Mandatory example, EMAIL or PHONE.
You can configure communication me dia in the Managing Interaction Content configuration app.
442
PUBLIC
Integration Guide Integration APIs
Property Name CommunicationMediumName ContactUUID SubscriptionUUID SubscriptionUTCDateTime
SubscriptionSignUpExists SubscriptionTopic
SubscriptionTopicName SubscriptionSourceObject
SubscriptionSourceObjectType
SubscriptionSourceSystem
Property Description
Usage
Description of property Communica tionMedium
Read-Only
Unique ID of a contact in SAP Marketing Read-Only
Cloud .
The field value is returned internally.
Unique ID of a subscription in SAP Marketing Cloud .
Read-Only The field value is returned internally.
This is the timestamp for when the sub Mandatory scription was given or removed.
Note
The time stamp must not be initial or null.
The subscription can be YES (Y) or NO Mandatory (N).
Represents a newsletter in SAP Marketing Cloud .
Mandatory
The SubscriptionTopic property field must be passed, but can be left empty.
If you want to create a newsletter sub scription, you must specify the Sub scriptionTopic.
Name of the subscription topic.
This field provides information on the source of the subscription, that is, where it came from. For example, the ID of a landing page.
This field can be filled with freetext.
This field provides information on the source of the subscription and its type. For example, the business object name of a landing page.
This field can be filled with freetext.
This is the system that stores the sub scription. For example, your local sys tem ID.
This field can be filled with freetext.
Integration Guide Integration APIs
PUBLIC
443
Property Name SubscriptionSourceSystemType
SubscriptionSourceCommMedium
SubscriptionSourceCommMedium Name IsConfirmationRequired
LastChangedByUser LastChangeDateTime SubscriptionNoteText
Property Description
Usage
This is the type of system where the subscription is stored. For example, SAP_CEI.
This field can be filled with freetext.
Indicates where the subscription comes Mandatory from, such as WEB, EMAIL, or PHONE. In case SubscriptionSourceCommMedium is not filled, this property is set to WEB.
Description of property Subscription SourceCommMedium
Read-Only
This is a boolean parameter. If the pa rameter is set to TRUE, the subscription is stored using the double opt-in or optout process.
If the property is not specified in the payload or it is set to FALSE the sub scription is directly stored.
Name of the user who has changed the Read-Only subsrciption last.
Date and time of the last permission change.
Read-Only
A text to describe a subscription change.
Parent topic: Contacts [page 412]
Related Information
Basic Concepts [page 414] Payload Examples [page 445] Function Imports [page 464]
444
PUBLIC
Integration Guide Integration APIs
5.2.1.3 Payload Examples
Payload examples for API_MKT_CONTACT.
Note
Before you start, please read the Processing Info and Best Practices section in Basic Concepts [page 414].
Ensure that you include at least the mandatory request header fields in each payload and that you use the syntax as indicated in the examples for the different entries.
Available Payload Examples
Contacts, Marketing Permissions, and Marketing Subscriptions [page 445] GET Requests [page 453] Account Team Members [page 455] Additional IDs [page 456] Contact Origin Data [page 457] Contact Relation Data [page 459] Contact Relation Additional IDs [page 460] Marketing Attributes [page 461] Marketing Areas [page 463]
Contacts, Marketing Permissions, and Marketing Subscriptions
Create Contacts with Additional IDs Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT ContactOriginData(ContactID='4711',ContactOrigin='SAP_HYBRIS_CONSUMER') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "OriginDataLastChgUTCDateTime" : "2017-10-01T13:13:14Z", "CityName" : "Kiel", "Country" : "DE", "FirstName" : "Otto", "LastName" : "Normalverbraucher",
Integration Guide Integration APIs
PUBLIC
445
"FullName" : "Otto Normalverbraucher", "BirthDate":"1961-10-28T00:00:00", "GenderCode" : "1", "AddressHouseNumber" : "1", "IsConsumer" : false, "IsContactPerson" : true, "Language" : "DE", "MaritalStatus" : "2", "MaritalStatusName" : "Married", "IsObsolete" : false, "ContactPostalCode" : "24105", "AddressRegion" : "01", "StreetName" : "Hauptstrasse" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(ContactID='4711',ContactOrigin='SAP_HYBRIS_CONSUMER',ContactAddi tionalOrigin='EMAIL',ContactAdditionalID='otto.normalverbraucher@company.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(ContactID='4711',ContactOrigin='SAP_HYBRIS_CONSUMER',ContactAddi tionalOrigin='EMAIL',ContactAdditionalID='otto.normalverbraucher5@company.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(ContactID='4711',ContactOrigin='SAP_HYBRIS_CONSUMER',Marke tingAttributeCategory='HOBBY',MarketingAttributeValue='Soccer') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(ContactID='4711',ContactOrigin='SAP_HYBRIS_CONSUMER',Marke tingAttributeCategory='HOBBY',MarketingAttributeValue='Volleyball') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT
446
PUBLIC
Integration Guide Integration APIs
Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(ContactID='4711',ContactOrigin='SAP_HYBRIS_CONSUMER',Marke tingAttributeCategory='Spoken_Language',MarketingAttributeValue='English') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(ContactID='4711',ContactOrigin='SAP_HYBRIS_CONSUMER',Marke tingAttributeCategory='Spoken_Language',MarketingAttributeValue='Romanian') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT ContactOriginData(ContactID='4712',ContactOrigin='SAP_HYBRIS_CONSUMER') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-ForceSynchronousProcessing: X Content-Type: application/json {
"OriginDataLastChgUTCDateTime" : "2017-10-01T13:13:14Z", "CityName" : "Walldorf", "Country" : "DE", "Department" : "", "FirstName" : "Erika", "LastName" : "Mustermann", "FullName" : "Erika Mustermann", "BirthDate":"1961-10-28T00:00:00", "Function" : " ", "GenderCode" : "2", "AddressHouseNumber" : "1", "Industry" : "", "IsConsumer" : true, "IsContactPerson" : false, "Language" : "DE", "MaritalStatus" : "1", "IsObsolete" : false, "ContactPostalCode" : "69190", "AddressRegion" : "08", "StreetName" : "Hauptstrasse" }
Integration Guide Integration APIs
PUBLIC
447
--changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(ContactID='4712',ContactOrigin='SAP_HYBRIS_CONSUMER',ContactAddi tionalOrigin='EMAIL',ContactAdditionalID='erika.mustermann4@privat.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(ContactID='4712',ContactOrigin='SAP_HYBRIS_CONSUMER',ContactAddi tionalOrigin='EMAIL',ContactAdditionalID='erika.mustermann5@privat.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Contact Note A PUT request is executed to set the IsEndOfPurposeBlocked flag.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT ContactOriginData(ContactID='AB20180612001P',ContactOrigin='SAP_ERP_BUPA') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-07-23T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "IsEndOfPurposeBlocked": true, "OriginDataLastChgUTCDateTime":"2018-07-23T12:13:14" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
448
PUBLIC
Integration Guide Integration APIs
Create Contacts with Marketing Permissions and Marketing Subscriptions Note The batch request is sent via http method POST containing PUT requests to create a new contact, marketing permission and marketing subscription. To update single attributes, you must use the PATCH request.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT ContactOriginData(ContactID='C98979992',ContactOrigin='SAP_C4C_BUPA') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-03-27T07:14:34' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 {
"OriginDataLastChgUTCDateTime" : "2019-07-01T13:04:46.000", "CityName" : "Walldorf", "Country" : "DE", "FirstName" : "Max", "LastName" : "Mustermann", "FullName" : "Max Mustermann", "GenderCode" : "1", "AddressHouseNumber" : "99", "Language" : "DE", "MaritalStatus" : "2", "MaritalStatusName" : "Married", "ContactPostalCode" : "24105", "StreetName" : "Dietmar-Hopp-Allee" } --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(ContactID='C98979992',ContactOrigin='SAP_C4C_BUPA',ContactAdditi onalOrigin='EMAIL',ContactAdditionalID='max.mustermann@mail.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.001' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C Content-Type: application/json { } --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingPermissions(ContactID='C98979992',ContactOrigin='SAP_C4C_BUPA',Contac tPermissionID='max.mustermann@mail.de',ContactPermissionOrigin='EMAIL',Marketi ngArea='',CommunicationMedium='EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.002' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1
Integration Guide Integration APIs
PUBLIC
449
Content-Type: application/json Content-Length: 1021 {
"PermissionUTCDateTime" : "2019-07-01T13:04:46.002", "PermissionGranted" : "Y", "PermissionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "PermissionNoteText" : "Sample Permission" } --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingSubscriptions(ContactID='C98979992',ContactOrigin='SAP_C4C_BUPA',Cont actSubscriptionID='max.mustermann@mail.de',ContactSubscriptionOrigin='EMAIL',C ommunicationMedium='EMAIL',SubscriptionTopic='1') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 { "SubscriptionUTCDateTime" : "2019-07-01T13:04:46.005", "SubscriptionSignUpExists" : "N", "SubscriptionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "SubscriptionNoteText" : "Sample Subscription" } --changeset_01869434-0010-0001---batch--
PATCH: Update Marketing Permissions and Marketing Subscriptions for a Contact Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PATCH MarketingPermissions(ContactID='C98979992',ContactOrigin='SAP_C4C_BUPA',Contac tPermissionID='max.mustermann@mail.de',ContactPermissionOrigin='EMAIL',Marketi ngArea='',CommunicationMedium='EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.002' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 { "PermissionUTCDateTime" : "2019-07-01T13:04:46.003", "PermissionGranted" : "Y" } --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PATCH MarketingSubscriptions(ContactID='C98979992',ContactOrigin='SAP_C4C_BUPA',Cont actSubscriptionID='max.mustermann@mail.de',ContactSubscriptionOrigin='EMAIL',C ommunicationMedium='EMAIL',SubscriptionTopic='1') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005'
450
PUBLIC
Integration Guide Integration APIs
Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "SubscriptionUTCDateTime" : "2019-07-01T13:04:46.006", "SubscriptionSignUpExists" : "N" }
--changeset_01869434-0010-0001---batch--
PUT: Update or Create Marketing Permissions and Marketing Subscriptions for a Contact Note The sample code has a PUT request that updates marketing permissions and marketing subscriptions, or creates new marketing permissions and marketing subscriptions if they do not exist. To update single attributes, you must use the PATCH request. In addition, if the value of the property IsConfirmationRequired is set to true, a double opt-in is executed. Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingPermissions(ContactID='C98979992',ContactOrigin='SAP_C4C_BUPA',Con tactPermissionID='max.mustermann@mail.de',ContactPermissionOrigin='EMAIL',M arketingArea='',CommunicationMedium='EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.002' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "PermissionUTCDateTime" : "2019-07-01T13:04:46.002", "PermissionGranted" : "Y", "PermissionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "PermissionNoteText" : "Sample Permission"
} --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingSubscriptions(ContactID='C98979992',ContactOrigin='SAP_C4C_BUPA',C ontactSubscriptionID='max.mustermann@mail.de',ContactSubscriptionOrigin='EM AIL',CommunicationMedium='EMAIL',SubscriptionTopic='1') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "SubscriptionUTCDateTime" : "2019-07-01T13:04:46.005", "SubscriptionSignUpExists" : "N", "SubscriptionSourceCommMedium" : "WEB",
Integration Guide Integration APIs
PUBLIC
451
"IsConfirmationRequired" : false, "SubscriptionNoteText" : "Sample Subscription" } --changeset_01869434-0010-0001---batch--
PUT: Update Additional IDs and their Permissions and Subscriptions Within One Changeset Example Use Case: 1. A contact is created with opt-ins for email a@b.c and mobile +12345. 2. You want to change the email to d@e.f but retain the mobile number and the opt-ins for both. 3. To enssure that you do not lose the mobile opt-in, steps 4 and 5 must be in the same changeset. 4. To delete the email a@b.c, you use the Function Import. 5. You send all IDs, including the new email ID and the mobile ID.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactOriginDeleteAdditionalIDs? ContactID='98979992'&ContactOrigin='SAP_HYBRIS_CONSUMER' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(ContactID='98979992',ContactOrigin='SAP_HYBRIS_CONSUMER',Contact AdditionalOrigin='EMAIL',ContactAdditionalID='tobias.tester@company.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(ContactID='98979992',ContactOrigin='SAP_HYBRIS_CONSUMER',Contact AdditionalOrigin='EMAIL',ContactAdditionalID='peter.tester@company.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json {
452
PUBLIC
Integration Guide Integration APIs
} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingPermissions(ContactID='98979992',ContactOrigin='SAP_HYBRIS_CONSUMER', ContactPermissionID='tobias.tester@company.de',ContactPermissionOrigin='EMAIL' ,MarketingArea='',CommunicationMedium='EMAIL') HTTP/1.1 Content-Length: 2035 Accept: application/json Sap-Cuan-RequestTimestamp:'2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "PermissionUTCDateTime" : "2018-11-02T09:19:12", "PermissionGranted" : "Y", "PermissionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingSubscriptions(ContactID='98979992',ContactOrigin='SAP_HYBRIS_CONSUMER ',ContactSubscriptionID='peter.tester@company.de',ContactSubscriptionOrigin='E MAIL',CommunicationMedium='EMAIL',SubscriptionTopic='') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json {
"SubscriptionUTCDateTime" : "2018-11-02T09:19:12", "SubscriptionSignUpExists" : "Y", "SubscriptionSourceCommMedium" : "WEB" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
GET Requests
Get contact origin data for a specific contact from one origin /sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ ContactOriginData(ContactOrigin='SAP_CRM_BUPA',ContactID='5320174712')
Get additional IDs of a contact from a specific origin Note $filter is not supported for additional IDs.
/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ ContactOriginData(ContactOrigin='SAP_CRM_BUPA',ContactID='5320174712')/ AdditionalIDs
Integration Guide Integration APIs
PUBLIC
453
Get the first 500 contacts created on or after a given date /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/Contacts?$format=json& $filter=CreationDateTime ge datetimeoffset'2018-10-01T00:00:00'&$top=500
Get the first 500 contacts whose first name is Walter /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/Contacts?$format=json& $filter=FirstName eq 'Walter'&$top=500
Get the first five contacts related to a specific corporate account /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/Contacts?$format=json& $filter=CorporateAccountUUID eq (guid'6c0b84b7-5523-1ed8-b1b8-34d75322d097')&$top=5
Get all explicit marketing permissions for a specific ContactUUID /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/ ContactOriginData(ContactID='C98979992 ',ContactOrigin='SAP_C4C_BUPA')/ MarketingPermissions?$filter=PermissionIsImplicit eq false&$top=10
Get all marketing permissions and marketing subscriptions for a contact with a certain ID and origin /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/ ContactOriginData(ContactID='C98979992 ',ContactOrigin='SAP_C4C_BUPA')? $expand=MarketingPermissions,MarketingSubscriptions
Get all marketing permissions and marketing subscriptions for a ContactUUID /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/ Contacts(ContactUUID=guid'6c0b84b7-5523-1ed9-a780-e4f6f36b1bfe')? $expand=MarketingPermissions,MarketingSubscriptions
Get contact data via ID and origin together with its marketing permissions and marketing subscriptions /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/ ContactOriginData(ContactID='C98979992 ',ContactOrigin='SAP_C4C_BUPA')/ MarketingPermissions
Get all marketing subscriptions for a contact with a certain ID and origin /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/ ContactOriginData(ContactID='C98979992 ',ContactOrigin='SAP_C4C_BUPA')/ MarketingSubscriptions
Get a contact via ContactUUID together with its marketing permissions and marketing subscriptions /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/MarketingSubscriptions? $filter=ContactUUID eq guid'6c0b84b7-5523-1ed9-a780-e4f6f36b1bfe'&$top=20
Get all marketing permissions for a specific email address of a contact /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/MarketingPermissions? $filter=ContactPermissionID eq 'max.mustermann@mail.de' and ContactPermissionOrigin eq 'EMAIL' &$top=20
454
PUBLIC
Integration Guide Integration APIs
Get the first 500 contacts that subscribed to newsletter Fashion /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/MarketingSubscriptions?$top=500& $filter=SubscriptionTopicName eq 'Fashion
Get the first 100 marketing permissions that are newer than a certain date and time /sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0004/MarketingPermissions?$top=10& $filter=PermissionUTCDateTime gt datetimeoffset'2019-01-01T00:00:00.001'
Get the first 100 projections (relationship best record) /sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/Projections?$top=100
Account Team Members
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AccountTeamMembers(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Tea mMemberID='<TeamMemberID>',Role='<Role>') HTTP/1.1Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
DELETE Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE AccountTeamMembers(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Tea mMemberID='<TeamMemberID>',Role='<Role>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json
Integration Guide Integration APIs
PUBLIC
455
{ } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH AccountTeamMembers(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Tea mMemberID='<TeamMemberID>',Role='<Role>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "ContactID": "<ContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Additional IDs
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',ContactA dditionalOrigin='<ContactAdditionalOrigin>',ContactAdditionalID='<ContactAddit ionalID>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
456
PUBLIC
Integration Guide Integration APIs
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH AdditionalIDs(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',ContactA dditionalOrigin='<ContactAdditionalOrigin>',ContactAdditionalID='<ContactAddit ionalID>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "ContactID": "<ContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Contact Origin Data
PUT - Batch Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT ContactOriginData(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json {"OriginDataLastChgUTCDateTime":"2017-10-01T13:13:14" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PATCH - Batch Sample Code --batch
Integration Guide Integration APIs
PUBLIC
457
Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ContactOriginData(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "OriginDataLastChgUTCDateTime":"2017-10-01T13:13:14", "AddressHouseNumber": "<AddressHouseNumber>", "ContactPostalCode": "<ContactPostalCode>", "StreetName": "<StreetName>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PUT Single Entity (with ForceSync flag in Request Header) Note When you import single entities, the response body is empty. You can read the status of the import only in the response header in the attributes Status and Sap-Message.
Sample Code
Request: PUT: /sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/ ContactOriginData(ContactID='C_20180828_00008',ContactOrigin='SAP_ERP_CONTACT' ) {
"OriginDataLastChgUTCDateTime" : "2017-10-01T13:13:14Z", "CityName" : "Kiel", "Country" : "DE", "FirstName" : "Otto", "LastName" : "Normalverbraucher", "FullName" : "Otto Normalverbraucher", "GenderCode" : "1", "AddressHouseNumber" : "1", "IsConsumer" : false, "IsContactPerson" : true, "Language" : "DE", "MaritalStatus" : "2", "MaritalStatusName" : "Married", "IsObsolete" : false, "ContactPostalCode" : "24105", "AddressRegion" : "01", "StreetName" : "Hauptstrasse", }
458
PUBLIC
Integration Guide Integration APIs
Contact Relation Data
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ContactRelationData(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Re lationshipCategory='<RelationshipCategory>',ReltdIntactnContactID='<ReltdIntac tnContactID>',ReltdIntactnContactOrigin='<ReltdIntactnContactOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "ContactID": "<ContactID>" "RelationDataLastChgUTCDateTime":"2017-09-29T12:13:14" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT ContactRelationData(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Re lationshipCategory='<RelationshipCategory>',ReltdIntactnContactID='<ReltdIntac tnContactID>',ReltdIntactnContactOrigin='<ReltdIntactnContactOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "RelationDataLastChgUTCDateTime":"2017-09-29T12:13:14" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
459
DELETE Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE ContactRelationData(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Re lationshipCategory='<RelationshipCategory>',ReltdIntactnContactID='<ReltdIntac tnContactID>',ReltdIntactnContactOrigin='<ReltdIntactnContactOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Contact Relation Additional IDs
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ContactRelationAdditionalIDs(ContactID='<ContactID>',ContactOrigin='<ContactOr igin>',RelationshipCategory='<RelationshipCategory>',ReltdIntactnContactID='<R eltdIntactnContactID>',ReltdIntactnContactOrigin='<ReltdIntactnContactOrigin>' ,CntctRelationAdditionalID='<CntctRelationAdditionalID>',CntctRelationAddition alOrigin='<CntctRelationAdditionalOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "ContactID": "<ContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
460
PUBLIC
Integration Guide Integration APIs
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT ContactRelationAdditionalIDs(ContactID='<ContactID>',ContactOrigin='<ContactOr igin>',RelationshipCategory='<RelationshipCategory>',ReltdIntactnContactID='<R eltdIntactnContactID>',ReltdIntactnContactOrigin='<ReltdIntactnContactOrigin>' ,CntctRelationAdditionalID='<CntctRelationAdditionalID>',CntctRelationAddition alOrigin='<CntctRelationAdditionalOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
GET (Projections) Get the first 100 projections
Sample Code
/sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0004/Projections?$top=100
Marketing Attributes
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Ma rketingAttributeCategory='<MarketingAttributeCategory>',MarketingAttributeValu e='<MarketingAttributeValue>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json {
Integration Guide Integration APIs
PUBLIC
461
} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
DELETE Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE MarketingAttributes(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Ma rketingAttributeCategory='<MarketingAttributeCategory>',MarketingAttributeValu e='<MarketingAttributeValue>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH MarketingAttributes(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Ma rketingAttributeCategory='<MarketingAttributeCategory>',MarketingAttributeValu e='<MarketingAttributeValue>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "ContactID": "<ContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
462
PUBLIC
Integration Guide Integration APIs
Marketing Areas
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAreas(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Interac tionContactMktgArea='<InteractionContactMktgArea>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp:'2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH MarketingAreas(ContactID='<ContactID>',ContactOrigin='<ContactOrigin>',Interac tionContactMktgArea='<InteractionContactMktgArea>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp:'2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "ContactID": "<ContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Parent topic: Contacts [page 412]
Integration Guide Integration APIs
PUBLIC
463
Related Information
Basic Concepts [page 414] Structure of OData Service API_MKT_CONTACTS [page 418] Function Imports [page 464] Payload Examples for Contact-to-Account Relationships
5.2.1.4 Function Imports
Function imports are used to perform custom operations on an entity, which are typically not provided by OData operations. This section contains payload examples for the following function imports:
Set Main Contact [page 464] Delete Relationship Additional IDs [page 465] Delete Marketing Area [page 465] Delete All Marketing Areas from Origin [page 466] Delete Account Team Members [page 467] Delete Marketing Attribute [page 467] Delete Additional IDs [page 468] Delete Marketing Locations [page 468]
Set Main Contact
HTTP Method POST
Function Import
ContactRelationDataSetMainContact Flags (when true) a contact relationship as the main contact for an account. Setting the value to false unflags a main contact.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactRelationDataSetMainContact? ContactID='DEV_TEST'&ContactOrigin='SAP_ERP_CONTACT'&RelationshipCategory='BUR 001'&ReltdIntactnContactID='DEV_TEST'&ReltdIntactnContactOrigin='SAP_CRM_BUPA' &IsMainContact=true HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT
464
PUBLIC
Integration Guide Integration APIs
Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Relationship Additional IDs
HTTP Method POST
Function Import ContactRelationDataDeleteAdditionalIDs Deletes all additional IDs belonging to one contact relation data.
Payload Example POST Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactRelationDataDeleteAdditionalIDs? ContactID='DEV_TEST'&ContactOrigin='SAP_ERP_CONTACT'&RelationshipCategory='BUR 001'&ReltdIntactnContactID='DEV_TEST'&ReltdIntactnContactOrigin='SAP_CRM_BUPA' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Marketing Area
HTTP Method POST
Function Import ContactDeleteMarketingArea Deletes all occurrences of a marketing area from a contact.
Integration Guide Integration APIs
PUBLIC
465
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactDeleteMarketingArea? ContactID='DEV_TEST'&ContactOrigin='SAP_ERP_CONTACT'&InteractionContactMktgAre a='GLOBAL' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete All Marketing Areas from Origin
HTTP Method POST
Function Import ContactOriginDeleteAllMktgAreas Deletes all marketing areas from one origin.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactOriginDeleteAllMktgAreas? ContactID='DEV_TEST'&ContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
466
PUBLIC
Integration Guide Integration APIs
Delete Account Team Members
HTTP Method POST
Function Import ContactDeleteAllAccountTeamMembers Deletes all account team members for one contact.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactDeleteAllAccountTeamMembers? ContactID='DEV_TEST'&ContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Marketing Attribute
HTTP Method POST
Function Import ContactOriginDeleteAllMktgAttributes Deletes all marketing attributes from one origin.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactOriginDeleteAllMktgAttributes? ContactID='DEV_TEST'&ContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT
Integration Guide Integration APIs
PUBLIC
467
Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Additional IDs
HTTP Method POST
Function Import ContactOriginDeleteAdditionalIDs Deletes all additional IDs from one origin except for IDs that come from the origin data.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactOriginDeleteAdditionalIDs? ContactID='DEV_TEST'&ContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Marketing Locations
HTTP Method POST
Function Import ContactOriginDeleteAllMktgLocations Deletes all marketing locations from one origin.
Payload Example Sample Code --batch
468
PUBLIC
Integration Guide Integration APIs
Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ContactOriginDeleteAllMktgLocations? ContactID='DEV_TEST'&ContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Function Import Parameters
Property
Description
Edm Core Type Max Length
Mandatory
Key
ContactID
ID of Contact
Edm. String
255
X
X
ContactOrigin Origin of Contact Edm. String
20
X
X
Parent topic: Contacts [page 412]
Related Information
Basic Concepts [page 414] Structure of OData Service API_MKT_CONTACTS [page 418] Payload Examples [page 445]
5.2.2 Interaction Contacts
Public OData API (API_MKT_INTERACTION_CONTACT_SRV Version 3) for Interaction Contacts. Interaction Contact is a generic term to group all natural persons (contacts, consumers, or suspects), companies and "unknowns", who interact with your company.
Note
We recommend that you use the current version 0003 of this service. If you want to use the previous version, you'll find the help links here:
Integration Guide Integration APIs
PUBLIC
469
Version 0002: Contact, Interaction Contact, Corprorate Account API, Version 0002
Note
This is a generic API Service. It should only be used in exceptional cases, as it has a limited subset of attributes, common to both natural persons and corporate contacts. Such an exceptional use case could be reading stored cookie IDs or reading "unknowns", that is, entities for whom it could not be determined whether they are natural persons or corporate accounts.
Technical Data
Caution
The API services available in SAP Marketing Cloud must not be used for mass read (GET) operations. In other words, you cannot use them for extracting all available data, for example, to extract millions of contacts or interactions from your marketing system.
Name of the Service Authorizations
Communication Scenario ID Component for Incidents
API_MKT_INTERACTION_CONTACT
The following business catalog roles are required: For version 2: SAP_CEC_BC_MKT_API_IC2_PC For version 3: SAP_CEC_BC_MKT_API_IC3_PC
SAP_COM_0207
CEC-MKT-DM-IC (Interaction Contacts) CEC-MKT-DM-PER (Permissions and Subscriptions)
Note
Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408].
OData Version Root URI
Service Metadata URI:
2.0
https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003
https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/$ metadata
470
PUBLIC
Integration Guide Integration APIs
Field Extensibility Supported
Yes
For more information, see the Field Extensibility section for marketing permissions in Structure of API_MKT_INTERAC TION_CONTACT [page 475].
Note
You need to open the collapsible sections of the docu ment first.
Technical Field Documentation
You can access detailed technical documentation for the API fields by downloading a metadata file in one of the following ways:
Access Link
Comment
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SR V;v=0003/$metadata?sapdocumentation=all
Only for internal access. You need to provide the server and port names.
Interaction Contacts Details Page
General access to the Details page of the service on SAP API Hub. One-time regis tration is required for first-time users.
1. On the Details page, click Download Specification and download as EDMX. 2. Specify which application you want to use to open the EDMX file type.
Marketing - Interaction Contacts API
General access link takes you directly to the Contacts metadata file. One-time registration or logon is required.
Note
You can convert the XML file to an XML table to make it easier to read.
Please note the meaning of the following values in the file:
Metadata Value in XML sap:updatable sap:creatable nullable
Basic Concepts [page 472]
Meaning When FALSE read-only field read-only field mandatory field
Integration Guide Integration APIs
PUBLIC
471
Public OData API (API_MKT_INTERACTION_CONTACT_SRV) for Interaction Contacts. Interaction Contact is a generic term to group all natural persons (contacts, consumers, or suspects), companies and "unknowns", who interact with your company. Structure of API_MKT_INTERACTION_CONTACT [page 475] This document describes the structure of the Public OData API API_MKT_INTERACTION_CONTACT. Payload Examples for Interaction Contacts [page 495] Payload examples for API_MKT_INTERACTION_CONTACT. Function Imports [page 508] Function imports are used to perform custom operations on an entity, which are typically not provided by OData operations. This section contains payload examples for the following function imports:
5.2.2.1 Basic Concepts
Public OData API (API_MKT_INTERACTION_CONTACT_SRV) for Interaction Contacts. Interaction Contact is a generic term to group all natural persons (contacts, consumers, or suspects), companies and "unknowns", who interact with your company.
Overview
The public API for Interaction Contact supports operations on the Interaction Contact Business Object and the Marketing Permissions Business Object.
Note
There is no separate public OData API for marketing permissions. The corresponding entity is part of this service since marketing permissions are always stored for a certain interaction contact.
Processing Info and Best Practices
Note
For generally applicable recommendations and best practices, make sure you refer to the section Best Practices and Recommended Package Sizes [page 400].
The minimum data required when importing interaction contacts is an ID, an ID Origin, a timestamp, and at least one other attribute.
When to use PUT and PATCH: PUT requests are most suitable for an initial data import, for example, when you want to create a new contact. A PUT request requires that you always send all properties. Any properties that you omit are overwritten by blank entries. That is, any existing entries are deleted. If no record is found, a new record is created. In other words. the PUT request functions as a full upsert
472
PUBLIC
Integration Guide Integration APIs
We recommend that you use PATCH requests for all other imports. A PATCH request updates only the properties provided in the request body and leaves everything untouched that was not provided. So, you can omit all properties that are not to be changed. Like the PUT request, if no record is found, a new record is created with the available properties.. In other words. the PATCH request functions as a delta upsert.
An additional advantage of using PATCH is that you specify your own sequence ID. For this reason, it is more flexible than a PUT operation, where the sequence ID is set by default and cannot be changed.
Basically, since you can use PATCH with the same payload as you would use for PUT, the PATCH operation is more universal and you can work with it exclusively.
We recommend that you don't mix PUT and PATCH operations. Doing so can lead to unwanted results since a PUT operation is processed before a PATCH.
Do not combine a DELETE operation with other OData operations in one changeset. We recommend that you do not combine the OData operations PUT, PATCH, POST, with a DELETE operation in the same changeset. For example, let's say you want to update data for Contact A by adding an additional email address and at the same time delete a mobile number that is no longer valid. So, you send a PUT operation on the AdditionalId entity with the new email address and a DELETE operation within the same changeset. One of these operations could cancel out the other and the resulting dataset will not be as intended. Recommended Practice: For such combined operations including a DELETE operation, we recommend that you always use the relevant function import, which allows deletion of specific entities, together with the appropriate OData operation PUT, PATCH, or POST within the same changeset.
Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service as described in [OData-URI ]. The batch request must contain a header parameter content-type, specifying the value multipart/mixed and boundary=batch.
Do not mix different types of services for operations involving the same data source. For example, when importing contacts from a web shop, do not use the CUAN_IMPORT service for a PUT operation and then the API_MKT_INTERACTION_CONTACT service to PATCH contacts. You can, however, migrate from CUAN_IMPORT to the API* services.
The origin that you pass via the property ContactOrigin cannot be shareable. If the main origin is set to Shareable, this will trigger an error. For more information, see Configuring Origins.You can view sample payloads and test the API at https://api.sap.com/api/API_MKT_INTERACTION_CONTACT_SRV_0003/ resource .
SAP internal codes: If you are not thoroughly familiar with the internal codes used by SAP for the following entities, you should use a free text version of these instead to avoid errors during import: Ad Network, Country, Customer Industry Code, Department, Device Type, Function, Gender, Language, Marital Status, Region, and Title. You should then map your free text name to the SAP internal code in the Map Free Text app. For more information, see Map Free Texts.
Note
The UTC timestamp of permissions can't lie in the future.
When you import permissions, they must not have a timestamp that lies in the future. The timestamp of imported permissions is always in UTC. The field name in the OData service is called PermissionUTCDateTime.
If you want to use your local timestamp, you have to add the time zone information, that is, your local time zone together with the time zone offset or enter a timestamp that is converted to UTC.
Integration Guide Integration APIs
PUBLIC
473
The date and time information is adapted by the standard time difference (offset) with +01:00 for Central European Time (CET) or -05:00 for Eastern Standard Time (EST). For example: 2019-01-01T12:00:00+01:00 If you live east of UTC and enter your timestamp in your local time zone without time zone offset, this will result in a future timestamp. For example, you live in Germany and your local time is 8 a.m on November, 28. If you enter this as the UTC timestamp without a time zone offset, the UTC permission timestamp will show as 8 a.m., November 28, while in the UTC time zone it's 7 a.m., November 28.You've created a UTC permission timestamp that lies in the future and is invalid.
Error Messages
If the OData service is not accessible, for example due to missing authorization, or because the system is not available, a corresponding HTTP status code is returned. If the OData service is accepted by the gateway component in the SAP Marketing Cloud system, the HTTP status code 201 or 204 is returned. Any processing errors are recorded in the SAP Marketing Cloud system in the Import Monitor app, where they can be monitored, restarted and discarded. By default, data processing for contacts, interaction contacts, corporate accounts, or marketing permissions is asynchronous. In most cases an OK response, such as a receipt notification, is returned almost immediately. An exception to this would be data uploads that might contain severe errors, such as parse or format errors, and so would not return an OK response but an error message. The data you upload lands in a staging area, where it is then further processed. You can change the default setting to synchronous processing by setting the property Sap-Cuan-ForceSynchronousProcessing to True. In this case, any error messages are returned as soon as they are detected. To view the processing status and to check for errors or success messages, you must launch the Import Monitor app. Messages for marketing permissions in this app are displayed under the API for Contact, API for Interaction Contacts, or API for Corporate Accounts depending on the API OData service you use. In the event of errors, you can restart or discard the import in the Import Monitor.
Parent topic: Interaction Contacts [page 469]
Related Information
Structure of API_MKT_INTERACTION_CONTACT [page 475] Payload Examples for Interaction Contacts [page 495] Function Imports [page 508]
474
PUBLIC
Integration Guide Integration APIs
5.2.2.2 Structure of API_MKT_INTERACTION_CONTACT
This document describes the structure of the Public OData API API_MKT_INTERACTION_CONTACT. Make sure you read these topics before you start: Best Practices and Recommended Package Sizes [page 400] Basic Concepts [page 472]
Request Header
The request header contains the additional header fields listed in the table. Remember to include at least the mandatory request header fields in each payload.
Property
Sap-CuanRequestTimestamp
Sap-Cuan-SequenceId
Example '2017-09-28T12:13:14'
PatchAddress
Sap-Cuan-
EXT
SourceSystemType
Sap-Cuan-SourceSystemId HYBRIS
Description
Max.
Manda
Length tory
Timestamp of the import run in
X
this format.
This defines a set of fields that are to be updated, for example, address fields, which can be in terpreted as a field group. The combination of the header fields Sap-Cuan-SequenceId and SapCuan-RequestTimestamp is used to check the sequence of the data received. If the data that is received has a timestamp older than already imported data, it is ignored.
X (only manda tory for Patch Mode)
Type of source system. This is a 20 free text field.
Identifier of source system. This 255 is a free text field.
Integration Guide Integration APIs
PUBLIC
475
Property
Example
Sap-Cuan-
X
ForceSynchronousProcessi
ng
Sap-Cuan-ReferenceId
345g67980907
Description
Max.
Manda
Length tory
This flag is deselected by de fault, which means that up loaded data is processed asyn chronously. On upload, a suc cess message is output immedi ately, unless there are errors such as authorization issues or bad requests. Objects are up loaded to the staging area and processed successively from there. All status messages can be displayed in the Import Monitor app.
You can force imports to be processed synchronously by setting this flag. In this case, an error message will be returned as soon as an error is detected. Such error messages are output in the Import Monitor app
External reference of the in
32
bound message
Entity Sets
The Interaction Contact OData API provides the following entity sets:
Entity Set
Description
InteractionContacts This entity contains all interaction contact information from the root.
AccountTeamMem bers
This entity contains information about the account team members.
AdditionalIDs
This entity contains information about additional IDs.
Path
/InteractionContacts /AccountTeamMem bers /AdditionalIDs
476
PUBLIC
Integration Guide Integration APIs
Entity Set
Description
Path
InteractionContactOri ginData
This entity contains interaction contact origin data.
Note
The property OriginDataLastChgUTCDateTime is mandatory and must be specified.
/InteractionContac tOriginData
MarketingAttributes This entity contains information about marketing attributes.
MarketingAreas
This entity contains information about marketing areas.
MarketingPermissions This entity contains information about marketing permissions.
MarketingSubscrip tions
This entity contains information about marketing subscriptions.
/MarketingAttributes
/MarketingAreas
/MarketingPermis sions
/MarketingSubscrip tions
InteractionContacts
GET: Entity Path: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/InteractionContacts
You can perform the following operations on the InteractionContacts entity set:
HTTP Method GET
Description
Path
Get a list of interaction contacts. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
/ InteractionCont acts?$top=1
Note
A maximum of 5000 interaction contacts can be fetched in a single request
Specification of TOP is mandatory.
Get the details of a specific contact using the InteractionContact UUID.
/ InteractionCont acts(guid'<Inte ractionContact UUID>')
Integration Guide Integration APIs
PUBLIC
477
AccountTeamMembers
You can perform the following operations on the AccountTeamMember entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/AccountTeamMembers
PUT, PATCH, or DELETE in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/$batch
PUT, PATCH, or DELETE in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/ AccountTeamMembers (InteractionContactID='<InteractionContactID>',InteractionContactOrigin='<Intera ctionContactOrigin>',TeamMemberID='<TeamMemberID>',Role='<Role>')
HTTP Method GET
Description Get a list of account team members.
Path
/AccountTeamMembers?$top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 account team members can be fetched in a single request
Specification of TOP is mandatory.
POST (Batch)
Get the details of a specific account team member.
This operation is not supported.
Update or create an account team member in batch mode
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
Delete account team member in batch mode
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
Append one new account team member
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
478
PUBLIC
Integration Guide Integration APIs
HTTP Method PUT
PATCH
DELETE
Description Update or create an account team member.
Add one new account team member.
Delete an account team member.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/ AccountTeamMembers (InteractionContactID='<Interac tionContactID>',InteractionCont actOrigin='<InteractionContactO rigin>',TeamMemberID='<TeamMemb erID>',Role='<Role>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/ AccountTeamMembers (InteractionContactID='<Interac tionContactID>',InteractionCont actOrigin='<InteractionContactO rigin>',TeamMemberID='<TeamMemb erID>',Role='<Role>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/ AccountTeamMembers (InteractionContactID='<Interac tionContactID>',InteractionCont actOrigin='<InteractionContactO rigin>',TeamMemberID='<TeamMemb erID>',Role='<Role>')
AdditionalIDs
You can perform the following operations on the AdditionalIDs entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/AdditionalIDs
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/ AdditionalIDs(InteractionContactID='<InteractionContactID>',InteractionContactOr igin='<InteractionContactOrigin>',InteractionContactAdditionalOrigin='<Interacti onContactAdditionalOrigin>',InteractionContactAdditionalExternalID='<Interaction ContactAdditionalExternalID>')
Integration Guide Integration APIs
PUBLIC
479
HTTP Method GET
POST (Batch) PUT
Description
Path
Get a list of additional IDs by Interaction Con tact ID and ID Origin.
/AdditionalIDs?$top=1
This method supports standard OData pa rameters such as $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 additional IDs can be fetched in a single request
Specification of TOP is mandatory. $filter is not supported for additional
IDs.
Get the details of a specific additional ID.
Update or create an additional ID in batch mode Add one new Additional ID
Update or create an additional ID.
/ AdditionalIDs('<InteractionCont actID>,<InteractionContactOrigi n>,<InteractionContactAdditiona lOrigin>,<InteractionContactAdd itionalExternalID>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/ AdditionalIDs(InteractionContac tID='<InteractionContactID>',In teractionContactOrigin='<Intera ctionContactOrigin>',Interactio nContactAdditionalOrigin='<Inte ractionContactAdditionalOrigin> ',InteractionContactAdditionalE xternalID='<InteractionContactA dditionalExternalID>')
480
PUBLIC
Integration Guide Integration APIs
HTTP Method PATCH
Description Add one new additional ID.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/ AdditionalIDs(InteractionContac tID='<InteractionContactID>',In teractionContactOrigin='<Intera ctionContactOrigin>',Interactio nContactAdditionalOrigin='<Inte ractionContactAdditionalOrigin> ',InteractionContactAdditionalE xternalID='<InteractionContactA dditionalExternalID>')
InteractionContactOriginData
You can perform the following operations on the InteractionContactOriginData entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/InteractionContactOriginData
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/ InteractionContactOriginData(InteractionContactID=' <InteractionContactID>',InteractionContactOrigin='<InteractionContactOrigin>')
HTTP Method GET
Description Get a list of Interaction Contact Origin Data.
Path
/InteractionContactOriginData? $top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 interaction con tact origin data entities can be fetched in a single request
Specification of TOP is mandatory.
Integration Guide Integration APIs
PUBLIC
481
HTTP Method POST (Batch)
PUT PATCH
Description
Path
Get the details of specific interaction contact origin data.
/ InteractionContactOriginData('< InteractionContactID>,<Interact ionContactOrigin>')
Note
The property OriginDataLastChgUTCDateTime is mandatory and must be specified.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
Delta update: PATCH attributes of the entity https://
InteractionContactOriginDataUpdate or cre <Server>:<Port>/sap/opu/
ate interaction contact origin data in batch
odata/SAP/
mode; (creates a contact if the contact not ex API_MKT_INTERACTION_CONTACT_SRV
ist)
;v=0003/$batch
Update or create interaction contact origin data. This creates an interaction contact if the contact not exist.
Note
The property OriginDataLastChgUTCDateTime is mandatory and must be specified.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/ InteractionContactOriginData(In teractionContactID=' <InteractionContactID>',Interac tionContactOrigin='<Interaction ContactOrigin>')
Delta Update: PATCH attributes of the entity InteractionContactOriginData.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/ InteractionContactOriginData(In teractionContactID=' <InteractionContactID>',Interac tionContactOrigin='<Interaction ContactOrigin>')
MarketingAttributes
You can perform the following operations on the MarketingAttributes entity set: GET: https://<Server>:<Port>/sap/opu/odata/SAP/
API_MKT_INTERACTION_CONTACT_SRV;v=0003/MarketingAttributes PUT, PATCH, or DELETE in batch: https://<Server>:<Port>/sap/opu/odata/SAP/
API_MKT_INTERACTION_CONTACT_SRV;v=0003/$batch
482
PUBLIC
Integration Guide Integration APIs
PUT, PATCH, or DELETE in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/ MarketingAttributes(InteractionContactID=' <InteractionContactID>',InteractionContactOrigin=' <InteractionContactOrigin>',MarketingAttributeCategory='<MarketingAttributeCateg ory>',MarketingAttributeValue='<MarketingAttributeValue>')
HTTP Method GET
Description
Path
Update or create interaction contact origin data in batch mode;Get a list of marketing at tributes by Interaction Contact ID and Origin.
/MarketingAttributes?$top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 marketing at tributes can be fetched in a single re quest
Specification of TOP is mandatory.
POST (Batch) PUT
Get the details of a specific marketing attrib ute.
Update or create marketing attributes in batch mode
Append one new marketing attribute
Update or create marketing attributes.
/ MarketingAttributes('<Interacti onContactID>,<InteractionContac tOrigin>,<MarketingAttributeCat egory>,<MarketingAttributeValue >')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_INTERAC TION_CONTACT_SRV;v=0003/MarketingAt tributes(InteractionContactID=' <Contac tID>',ContactOrigin=' <ContactOrigin>',Mar ketingAttributeCategory='<MarketingAttribu teCategory>',MarketingAttributeValue='<Mar ketingAttributeValue>')
Integration Guide Integration APIs
PUBLIC
483
HTTP Method PATCH
DELETE
Description Add one new marketing attribute.
Delete marketing attributes.
Path
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_INTERAC TION_CONTACT_SRV;v=0003/MarketingAt tributes(InteractionContactID=' <Interaction ContactID>',InteractionContactOrigin=' <In teractionContactOrigin>',MarketingAttribute Category='<MarketingAttributeCate gory>',MarketingAttributeValue='<Marketin gAttributeValue>')
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_INTERAC TION_CONTACT_SRV;v=0003/MarketingAt tributes(InteractionContactID=' <Interaction ContactID>',InteractionContactOrigin=' <In teractionContactOrigin>',MarketingAttribute Category='<MarketingAttributeCate gory>',MarketingAttributeValue='<Marketin gAttributeValue>')
Marketing Areas
You can perform the following operations on the MarketingAreas entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV;v=0003/ MarketingAreas(InteractionContactID='<InteractionContactID>',InteractionContactO rigin='<InteractionContactOrigin>',InteractionContactMktgArea='<InteractionConta ctMktgArea>')
484
PUBLIC
Integration Guide Integration APIs
HTTP Method GET
POST (Batch) PUT
Description
Get a list of marketing areas by Interaction Contact ID and Origin.
Path
/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0003/ Contacts? $expand=MarketingAreas&$top=2
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 marketing areas can be fetched in a single re quest
Specification of TOP is mandatory.
Get the details of a specific marketing attrib ute.
Update or create marketing areas in batch mode
Append one new marketing area
Update or create marketing areas.
/ MarketingAreas('<InteractionCon tactID>,<InteractionContactOrig in>,<InteractionContactMktgArea >,')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/$batch
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_INTERAC TION_CONTACT_SRV;v=0003/MarketingAr eas(InteractionContactID='<InteractionCon tactID>',InteractionContactOrigin='<Interac tionContactOrigin>',InteractionContactMkt gArea='<InteractionContactMktgArea>')
Integration Guide Integration APIs
PUBLIC
485
HTTP Method PATCH
Description Add one new marketing area.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_INTERACTION_CONTACT_SRV ;v=0003/ MarketingAreas(InteractionConta ctID='<InteractionContactID>',I nteractionContactOrigin='<Inter actionContactOrigin>',Interacti onContactMktgArea='<Interaction ContactMktgArea>')
MarketingPermissions
Entity Path: /MarketingPermissions
Field Extensibility: The following business context is relevant: Marketing: Marketing Permissions. Custom fields for business object MKT_PERMISSION (Marketing: Permission) are only supported if you use version 3 of the API_MKT_INTERACTION_CONTACT service.
Note
Please note the following:
For all HTTP operations both $batch requests and single requests can be used. Interactions are assigned when marketing permissions are created or updated to allow for analysis of
interaction contacts.
You can perform the following operations on the MarketingPermissions entity set:
HTTP Method GET
Description
Path
Get a list of marketing permissions by Interaction Contact ID and ID Ori gin. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
/ MarketingPermis sions?$top=1
Note
A maximum of 5000 marketing permissions can be fetched in a single request
Specification of TOP is mandatory.
486
PUBLIC
Integration Guide Integration APIs
HTTP Method PATCH
PUT
Description Update or create marketing permissions. This creates a marketing per mission if the permission does not exit.
Update or create marketing permissions. This creates a marketing per mission if the permission does not exit. Delta Update of PATCH attributes of the entity MarketingPermission.
Path
/ MarketingPermis sions(Interacti onContactID='<I nteractionConta ctID>',Interact ionContactOrigi n='<Interaction ContactOrigin>' ,InteractionCon tactPermissionI D='<Interaction ContactPermissi onID>',Interact ionContactPermi ssionOrigin='<I nteractionConta ctPermissionOri gin>',Marketing Area='<Marketin gArea>',Communi cationMedium='< CommunicationMe dium>')
/ MarketingPermis sions(Interacti onContactID='<I nteractionConta ctID>',Interact ionContactOrigi n='<Interaction ContactOrigin>' ,InteractionCon tactPermissionI D='<Interaction ContactPermissi onID>',Interact ionContactPermi ssionOrigin='<I nteractionConta ctPermissionOri gin>',Marketing Area='<Marketin gArea>',Communi cationMedium='< CommunicationMe dium>')
The table below describes the properties for the entity MarketingPermissions.
Integration Guide Integration APIs
PUBLIC
487
MarketingPermissions Property Names and Descriptions
Property Name
Property Description
Usage
InteractionContactID
The InteractionContactID and Interac tionContactOrigin identify the contact uniquely.
Mandatory
Example: a business partner ID from the CRM system
InteractionContactOrigin
The InteractionContactID and Interac tionContactOrigin identify the contact uniquely.
Mandatory
Example: SAP_CRM_BUPA
InteractionContactPermissionID
The InteractionContactPermissionID Mandatory and IntactnCntctPermissionOrigin store marketing permissions.
Example: first.lastname@mail.de
IntactnCntctPermissionOrigin
The InteractionContactPermissionID Mandatory and IntactnCntctPermissionOrigin store marketing permissions.
IntactnCntctPermissionOrigin is the ori gin of the interaction contact ID that stores marketing permissions.
The origin indicates the source of an ID. By defining the origin, you determine that an interaction contact with an ID associated to a source is eligible to be analyzed.
You can configure origins of contacts IDs in the Configuring Origins configuration app.
Example: EMAIL
IntactnCntctPrmssnOriginName
Description of property IntactnCntct PermissionOrigin
Read-Only
MarketingArea
Identifies an area of responsibility or an organizational unit.
You use a marketing area to restrict ac cess to instances of an object, such as campaign, email message, email tem plate, target group, or permission.
Mandatory
The MarketingArea property field must be passed, but can be left empty.
MarketingAreaName
Description of property MarketingArea.
488
PUBLIC
Integration Guide Integration APIs
Property Name CommunicationMedium
CommunicationMediumName InteractionContactUUID PermissionUTCDateTime
PermissionUUID PermissionGranted PermissionSourceObject
PermissionSourceObjectType
PermissionSourceSystem
Property Description
Usage
Represents the type of permission, for Mandatory example, EMAIL or PHONE.
You can configure communication me dia in the Managing Interaction Content configuration app.
Description of property Communica tionMedium
Unique ID of an interaction contact in SAP Marketing Cloud .
Read-Only
This is the timestamp for when the per Mandatory mission was given or removed.
Note
The time stamp must not be initial or null.
Unique ID of a permission in SAP Marketing Cloud .
The permission can be YES (Y) or NO (N).
Mandatory
This field provides information on the source of the permission, that is, where it came from. For example, the ID of a landing page.
If you enter a value for the Permission SourceObject property, you must also specify a value for the PermissionSour ceObjectType.
This field can be filled with freetext.
Both fields must be filled or left empty.
This field provides information on the source of the permission and its type. For example, the business object name of a landing page.
This field can be filled with freetext.
This is the system that stores the per mission. For example, ABD client 100.
This field can be filled with freetext.
If you enter a value for the Permission SourceSystem property, you must also specify a value for the PermissionSour ceSystemType.
Integration Guide Integration APIs
PUBLIC
489
Property Name
Property Description
Usage
PermissionSourceSystemType
This is the type of system where the permission is stored. For example, SAP_CEI.
This field can be filled with freetext.
PermissionSourceCommMedium
Indicates where the permission comes from, such as WEB, EMAIL, or PHONE. In case PermissionSourceCommMedium is not filled, this property is set to WEB.
PermissionSourceCommMediumName Description of property Permission SourceCommMedium
Read-Only
PermissionIsImplicit
If the system sets this field to TRUE, then it is an implicit permission, which is determined by country-specific regu lation.
Read-Only
If the system sets this field to FALSE, the contact has given this permission explicitly.
PermissionNoteText
A text to describe a permission change.
IsConfirmationRequired
This is a boolean parameter. If the pa rameter is set to TRUE, the permission is stored using the double opt-in or optout process.
If the property is not specified in the payload or it is set to FALSE the permis sion is directly stored.
LastChangedByUser
Name of the user who has changed the Read-Only permissions last.
LastChangeDateTime
Date and time of the last permission change.
Read-Only
MarketingSubscriptions
Entity Path: /MarketingSubscriptions
Note
For all HTTP operations both $batch requests and single requests can be used.
490
PUBLIC
Integration Guide Integration APIs
Interactions are assigned when marketing permissions are created or updated to allow for analysis of contacts.
You can perform the following operations on the MarketingSubscriptions entity set:
HTTP Method GET
Description
Path
Get a list of marketing subscriptions by Contact ID and ID Origin. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
/ MarketingSubscriptio ns?$top=1
Note
A maximum of 5000 marketing subscriptions can be fetched in a single request
Specification of TOP is mandatory.
PATCH PUT
Update or create subscriptions. This creates a subscription if the subscription does not exit.
/ MarketingSubscriptio ns(ContactID='<Conta ctID>',ContactOrigin ='<ContactOrigin>',C ontactPermissionID= '<ContactPermissionI D>',ContactPermissio nOrigin='<ContactPer missionOrigin>',Comm unicationMedium='<Co mmunicationMedium>', SubscriptionTopic='< SubscriptionTopic>')
Update or create subscriptions. This creates a subscription if the subscription does not exit.
Delta Update of PATCH attributes of the entity MarketingSub scriptions.
/ MarketingSubscriptio ns(ContactID='<Conta ctID>',ContactOrigin ='<ContactOrigin>',C ontactPermissionID= '<ContactPermissionI D>',ContactPermissio nOrigin='<ContactPer missionOrigin>',Comm unicationMedium='<Co mmunicationMedium>', SubscriptionTopic='< SubscriptionTopic>')
Marketing Subscription Property Descriptions The table describes the properties for the MarketingSubscription entity.
Integration Guide Integration APIs
PUBLIC
491
MarketingSubscription Property Names and Descriptions
Property Name
Property Description
Usage
InteractionContactID
The InteractionContactID and Interac tionContactOrigin identify the contact uniquely.
Example: a business partner ID from the CRM system.
InteractionContactOrigin
The InteractionContactID and Interac tionContactOrigin identify the contact uniquely.
The InteractionContactID will not be saved to the MarketingSubscription but is only used to derive a unique Interac tionContactUUID. This data will not be returned in GET requests.
Example: SAP_CRM_BUPA
IntactnCntctSubscriptionID
The InteractionContactPermissionID Mandatory and InteractionContactSubscriptionOri gin store marketing subscription.
IntactnCntctSubscriptionOrigin
The InteractionContactSubscriptionID Mandatory and InteractionContactSubscriptionOri gin store marketing subscriptions.
InteractionContactSubscriptionOrigin is the origin of an interaction contact ID that stores marketing subscriptions. The origin indicates the source of an ID. By defining the origin, you determine that an interaction contact with an ID associated to a source can be analyzed.
Example: EMAIL
You can configure origins of contact IDs in the Configuring Origins configuration app.
InteractionContactSubscriptionOrigin Description of property Interaction
Name
ContactSubscriptionOrigin
Read-Only
CommunicationMedium
Represents the type of subscription, for Mandatory example, EMAIL or PHONE.
You can configure communication me dia in the Managing Interaction Content configuration app.
492
PUBLIC
Integration Guide Integration APIs
Property Name CommunicationMediumName InteractionContactUUID SubscriptionUUID SubscriptionUTCDateTime
SubscriptionSignUpExists SubscriptionTopic
SubscriptionTopicName SubscriptionSourceObject
SubscriptionSourceObjectType
SubscriptionSourceSystem
Property Description
Usage
Description of property Communica tionMedium
Read-Only
Unique ID of an interaction contact in SAP Marketing Cloud .
Read-Only The field value is returned internally.
Unique ID of a subscription in SAP Marketing Cloud .
This is the timestamp for when the sub Mandatory scription was given or removed.
Note
The time stamp must not be initial or null.
The subscription can be YES (Y) or NO Mandatory (N).
Represents a newsletter in SAP Marketing Cloud .
Mandatory
The SubscriptionTopic property field must be passed, but can be left empty.
If you want to create a newsletter sub scription, you must specify the Sub scriptionTopic.
Name of the subscription topic.
This field provides information on the source of the subscription, that is, where it came from. For example, the ID of a landing page.
This field can be filled with freetext.
This field provides information on the source of the subscription and its type. For example, the business object name of a landing page.
This field can be filled with freetext.
This is the system that stores the sub scription. For example, your local sys tem ID.
This field can be filled with freetext.
Integration Guide Integration APIs
PUBLIC
493
Property Name SubscriptionSourceSystemType
SubscriptionSourceCommMedium
SubscriptionSourceCommMedium Name IsConfirmationRequired
LastChangedByUser LastChangeDateTime SubscriptionNoteText
Property Description
Usage
This is the type of system where the subscription is stored. For example, SAP_CEI.
This field can be filled with freetext.
Indicates where the subscription comes from, such as WEB, EMAIL, or PHONE. In case SubscriptionSourceCommMedium is not filled, this property is set to WEB.
Description of property Subscription SourceCommMedium
This is a boolean parameter. If the pa rameter is set to TRUE, the subscription is stored using the double opt-in or optout process.
If the property is not specified in the payload or it is set to FALSE the sub scription is directly stored.
Name of the user who has changed the Read-Only subscription last.
Date and time of the last permission change.
Read-Only
A text to describe a subscription change.
Parent topic: Interaction Contacts [page 469]
Related Information
Basic Concepts [page 472] Payload Examples for Interaction Contacts [page 495] Function Imports [page 508]
494
PUBLIC
Integration Guide Integration APIs
5.2.2.3 Payload Examples for Interaction Contacts
Payload examples for API_MKT_INTERACTION_CONTACT.
Note
Before you start, please read the Processing Info and Best Practices section in Basic Concepts [page 472].
Remember to include at least the mandatory request header fields in each payload.
Available Payload Examples
Interaction Contacts, Marketing Permissions, and Marketing Subscriptions [page 495] GET Requests [page 501] Account Team Members [page 502] Additional IDs [page 503] Interaction Contact Origin Data [page 504] Marketing Attributes [page 506] Marketing Areas [page 507]
Interaction Contacts, Marketing Permissions, and Marketing Subscriptions
Create Interaction Contacts with Additional IDs Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT InteractionContactOriginData(InteractionContactID='4711',InteractionContactOri gin='SAP_HYBRIS_CONSUMER') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "OriginDataLastChgUTCDateTime":"2017-10-01T13:13:14Z", "CityName": "Kiel", "Country": "DE", "EmailAddress": "otto.normalverbraucher@company.de", "FullName": "Normalverbraucher", "AddressHouseNumber": "1", "MobileNumber": "+49119201412191", "PhoneNumber": "+49115", "ContactPostalCode": "24105",
Integration Guide Integration APIs
PUBLIC
495
"AddressRegion": "01", "StreetName": "Hauptstrasse" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(InteractionContactID='4711',InteractionContactOrigin='SAP_HYBRIS _CONSUMER',InteractionContactAdditionalOrigin='EMAIL',InteractionContactAdditi onalExternalID='otto.normalverbraucher@company.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(InteractionContactID='4711',InteractionContactOrigin='SAP_HYBRIS _CONSUMER',InteractionContactAdditionalOrigin='EMAIL',InteractionContactAdditi onalExternalID='otto.normalverbraucher5@company.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(InteractionContactID='4711',InteractionContactOrigin='SAP_ HYBRIS_CONSUMER',MarketingAttributeCategory='HOBBY',MarketingAttributeValue='S occer') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(InteractionContactID='4711',InteractionContactOrigin='SAP_ HYBRIS_CONSUMER',MarketingAttributeCategory='HOBBY',MarketingAttributeValue='V olleyball') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(InteractionContactID='4711',InteractionContactOrigin='SAP_
496
PUBLIC
Integration Guide Integration APIs
HYBRIS_CONSUMER',MarketingAttributeCategory='Spoken_Language',MarketingAttribu teValue='English') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(InteractionContactID='4711',InteractionContactOrigin='SAP_ HYBRIS_CONSUMER',MarketingAttributeCategory='Spoken_Language',MarketingAttribu teValue='Romanian') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Interaction Contact Note A PUT request is executed to set the IsEndOfPurposeBlocked flag.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT InteractionContactOriginData(InteractionContactID='AB20180612001P',InteractionContactOrigin='SAP_ERP_BUPA') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-07-23T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "IsEndOfPurposeBlocked": true, "OriginDataLastChgUTCDateTime":"2018-07-23T12:13:14" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
497
Create Interaction Contacts with Marketing Permissions and Marketing Subscriptions Note The batch request is sent via http method POST containing PUT requests to create a new interaction contact, marketing permission and marketing subscription. To update single attributes, you must use the PATCH request.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT InteractionContactOriginData(InteractionContactID='IC98979992',InteractionCont actOrigin='SAP_C4C_BUPA') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-03-27T07:14:34' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 {
"OriginDataLastChgUTCDateTime" : "2019-07-01T13:04:46.000", "CityName" : "Walldorf", "Country" : "DE", "EmailAddress" : "max.mustermann@mail.de", "PhoneNumber" : "+619022580475611", "MobileNumber" : "+622485500519911", "FullName" : "Max Mustermann", "AddressHouseNumber" : "99", "Language" : "DE", "ContactPostalCode" : "24105", "StreetName" : "Dietmar-Hopp-Allee" } --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingPermissions(InteractionContactID='IC98979992',InteractionContactOrigi n='SAP_C4C_BUPA',InteractionContactPermissionID='max.mustermann@mail.de',Intac tnCntctPermissionOrigin='EMAIL',MarketingArea='',CommunicationMedium='EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.002' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 { "PermissionUTCDateTime" : "2019-07-01T13:04:46.002", "PermissionGranted" : "Y", "PermissionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "PermissionNoteText" : "Sample Permission" } --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingSubscriptions(InteractionContactID='IC98979992',InteractionContactOri
498
PUBLIC
Integration Guide Integration APIs
gin='SAP_C4C_BUPA',IntactnCntctSubscriptionID='max.mustermann@mail.de',Intactn CntctSubscriptionOrigin='EMAIL',CommunicationMedium='EMAIL',SubscriptionTopic= '1') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 {
"SubscriptionUTCDateTime" : "2019-07-01T13:04:46.005", "SubscriptionSignUpExists" : "N", "SubscriptionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "SubscriptionNoteText" : "Sample Subscription" } --changeset_01869434-0010-0001---batch--
PATCH: Update Marketing Permissions and Marketing Subscriptions for an Interaction Contact
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PATCH MarketingPermissions(InteractionContactID='IC98979992',InteractionContactOrigi n='SAP_C4C_BUPA',InteractionContactPermissionID='max.mustermann@mail.de',Intac tnCntctPermissionOrigin='EMAIL',MarketingArea='',CommunicationMedium='EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "PermissionUTCDateTime" : "2019-07-01T13:04:46.005", "PermissionGranted" : "N"
} --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PATCH MarketingSubscriptions(InteractionContactID='IC98979992',InteractionContactOri gin='SAP_C4C_BUPA',IntactnCntctSubscriptionID='max.mustermann@mail.de',Intactn CntctSubscriptionOrigin='EMAIL',CommunicationMedium='EMAIL',SubscriptionTopic= '1') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "SubscriptionUTCDateTime" : "2019-07-01T13:04:46.007", "SubscriptionSignUpExists" : "Y"
} --changeset_01869434-0010-0001--
Integration Guide Integration APIs
PUBLIC
499
--batch--
PUT: Update or Create Marketing Permissions and Marketing Subscriptions for an Interaction Contact
Note
The sample code has a PUT request that updates marketing permissions and marketing subscriptions, or creates new marketing permissions and marketing subscriptions if they do not exist. To update single attributes, you must use the PATCH request. In addition, if the value of the property IsConfirmationRequired is set to true, a double opt-in is executed.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingPermissions(InteractionContactID='IC98979992',InteractionContactOr igin='SAP_C4C_BUPA',InteractionContactPermissionID='max.mustermann@mail.de' ,IntactnCntctPermissionOrigin='EMAIL',MarketingArea='',CommunicationMedium= 'EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.002' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "PermissionUTCDateTime" : "2019-07-01T13:04:46.002", "PermissionGranted" : "Y", "PermissionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "PermissionNoteText" : "Sample Permission" }
--changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingSubscriptions(InteractionContactID='IC98979992',InteractionContact Origin='SAP_C4C_BUPA',IntactnCntctSubscriptionID='max.mustermann@mail.de',I ntactnCntctSubscriptionOrigin='EMAIL',CommunicationMedium='EMAIL',Subscript ionTopic='1') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "SubscriptionUTCDateTime" : "2019-07-01T13:04:46.005", "SubscriptionSignUpExists" : "N", "SubscriptionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "SubscriptionNoteText" : "Sample Subscription"
} --changeset_01869434-0010-0001---batch--
500
PUBLIC
Integration Guide Integration APIs
GET Requests
Get all explicit marketing permissions for a specific InteractionContactUUID
/sap/opu/odata/sap/API_MKT_INTERACTION_CONTACT_SRV;v=0003/MarketingPermissions? $filter=InteractionContactUUID eq guid'6c0b84b7-5523-1ed9-a792-18a320d91baf' and PermissionIsImplicit eq false&$top=10
Get all marketing permissions and marketing subscriptions for an interaction contact with a certain ID and origin
/sap/opu/odata/sap/API_MKT_INTERACTION_CONTACT_SRV;v=0003/ InteractionContactOriginData(InteractionContactID='IC98979992 ',InteractionContactOrigin='SAP_C4C_BUPA')? $expand=MarketingPermissions,MarketingSubscriptions
Get all marketing permissions and marketing subscriptions for an InteractionContactUUID
/sap/opu/odata/sap/API_MKT_INTERACTION_CONTACT_SRV;v=0003/ InteractionContacts(InteractionContactUUID=guid'6c0b84b7-5523-1ed9a792-18a320d91baf')?$expand=MarketingPermissions,MarketingSubscriptions
Get all marketing permissions for an interaction contact with a certain ID and origin
/sap/opu/odata/sap/API_MKT_INTERACTION_CONTACT_SRV;v=0003/ InteractionContactOriginData(InteractionContactID='IC98979992 ',InteractionContactOrigin='SAP_C4C_BUPA')/MarketingPermissions
Get interaction contact data via ID and origin together with its marketing permissions and marketing subscriptions
/sap/opu/odata/sap/API_MKT_INTERACTION_CONTACT_SRV;v=0003/ InteractionContactOriginData(InteractionContactID='IC98979992 ',InteractionContactOrigin='SAP_C4C_BUPA')/MarketingSubscriptions
Get an interaction contact via InteractionContactUUIDID together with its marketing permissions and marketing subscriptions
/sap/opu/odata/sap/API_MKT_INTERACTION_CONTACT_SRV;v=0003/MarketingSubscriptions? $filter=InteractionContactUUID eq guid'6c0b84b7-5523-1ed9-a792-18a320d91baf'& $top=20
Get all marketing permissions for a specific email address of an interaction contact
/sap/opu/odata/sap/API_MKT_INTERACTION_CONTACT_SRV;v=0003/MarketingPermissions? $filter=InteractionContactPermissionID eq 'max.mustermann@mail.de' and IntactnCntctPermissionOrigin eq 'EMAIL' &$top=20
Get the first 500 interaction contacts that subscribed to newsletter Fashion
/sap/opu/odata/sap/API_MKT_INTERACTION_CONTACT_SRV;v=0003/MarketingSubscriptions? $top=500&$filter=SubscriptionTopicName eq 'Fashion'
Integration Guide Integration APIs
PUBLIC
501
Get the first 100 marketing permissions that are newer than a certain date and time
/sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0003/MarketingPermissions?$top=10& $filter=PermissionUTCDateTime gt datetimeoffset'2019-01-01T00:00:00.001'
Account Team Members
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AccountTeamMembers(InteractionContactID='<InteractionContactID>',InteractionCo ntactOrigin='<InteractionContactOrigin>',TeamMemberID='<TeamMemberID>',Role='< Role>') HTTP/1.1Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
DELETE Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE AccountTeamMembers(InteractionContactID='<InteractionContactID>',InteractionCo ntactOrigin='<InteractionContactOrigin>',TeamMemberID='<TeamMemberID>',Role='< Role>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
502
PUBLIC
Integration Guide Integration APIs
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH AccountTeamMembers(InteractionContactID='<InteractionContactID>',InteractionCo ntactOrigin='<InteractionContactOrigin>',TeamMemberID='<TeamMemberID>',Role='< Role>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "InteractionContactID": "<InteractionContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Additional IDs
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(InteractionContactID='<InteractionContactID>',InteractionContact Origin='<InteractionContactOrigin>',InteractionContactAdditionalOrigin='<Inter actionContactAdditionalOrigin>',InteractionContactAdditionalExternalID='<Inter actionContactAdditionalExternalID>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
503
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH AdditionalIDs(InteractionContactID='<InteractionContactID>',InteractionContact Origin='<InteractionContactOrigin>',InteractionContactAdditionalOrigin='<Inter actionContactAdditionalOrigin>',InteractionContactAdditionalExternalID='<Inter actionContactAdditionalExternalID>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "InteractionContactID": "<InteractionContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Interaction Contact Origin Data
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT InteractionContactOriginData(InteractionContactID='<InteractionContactID>',Int eractionContactOrigin='<InteractionContactOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
504
PUBLIC
Integration Guide Integration APIs
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH InteractionContactOriginData(InteractionContactID='<InteractionContactID>',Int eractionContactOrigin='<InteractionContactOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "OriginDataLastChgUTCDateTime":"2017-10-01T13:13:14", "AddressHouseNumber": "<AddressHouseNumber>", "ContactPostalCode": "<ContactPostalCode>", "StreetName": "<StreetName>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PUT Single Entity (with ForceSync flag in Request Header) Note When you import single entities, the response body is empty. You can read the status of the import only in the response header in the attributes Status and Sap-Message.
Sample Code
Request: PUT: /sap/opu/odata/SAP/API_MKT_INTERACTION_CONTACT_SRV;v=0003/ InteractionContactOriginData(ContactID='C_20180828_00008',InteractionContactOr igin='SAP_ERP_CONTACT') {
"OriginDataLastChgUTCDateTime" : "2017-10-01T13:13:14Z", "CityName" : "Kiel", "Country" : "DE", "EmailAddress" : "otto.normalverbraucher@company.de", "FirstName" : "Otto", "LastName" : "Normalverbraucher", "FullName" : "Otto Normalverbraucher", "GenderCode" : "1", "AddressHouseNumber" : "1", "IsConsumer" : false, "IsContactPerson" : true, "Language" : "DE", "MaritalStatus" : "2", "MaritalStatusName" : "Married", "MobileNumber" : "+49119201412191", "IsObsolete" : false, "PhoneNumber" : "+49115", "ContactPostalCode" : "24105", "AddressRegion" : "01", "StreetName" : "Hauptstrasse", }
Integration Guide Integration APIs
PUBLIC
505
Marketing Attributes
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(InteractionContactID='<InteractionContactID>',InteractionC ontactOrigin='<InteractionContactOrigin>',MarketingAttributeCategory='<Marketi ngAttributeCategory>',MarketingAttributeValue='<MarketingAttributeValue>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
DELETE Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE MarketingAttributes(InteractionContactID='<InteractionContactID>',InteractionC ontactOrigin='<InteractionContactOrigin>',MarketingAttributeCategory='<Marketi ngAttributeCategory>',MarketingAttributeValue='<MarketingAttributeValue>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
506
PUBLIC
Integration Guide Integration APIs
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH MarketingAttributes(InteractionContactID='<InteractionContactID>',InteractionC ontactOrigin='<InteractionContactOrigin>',MarketingAttributeCategory='<Marketi ngAttributeCategory>',MarketingAttributeValue='<MarketingAttributeValue>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "InteractionContactID": "<InteractionContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Marketing Areas
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAreas(InteractionContactID='<InteractionContactID>',InteractionContac tOrigin='<InteractionContactOrigin>',InteractionContactMktgArea='<InteractionC ontactMktgArea>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp:'2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
507
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH MarketingAreas(InteractionContactID='<InteractionContactID>',InteractionContac tOrigin='<InteractionContactOrigin>',InteractionContactMktgArea='<InteractionC ontactMktgArea>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp:'2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "InteractionContactID": "<InteractionContactID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Parent topic: Interaction Contacts [page 469]
Related Information
Basic Concepts [page 472] Structure of API_MKT_INTERACTION_CONTACT [page 475] Function Imports [page 508]
5.2.2.4 Function Imports
Function imports are used to perform custom operations on an entity, which are typically not provided by OData operations. This section contains payload examples for the following function imports: Delete Marketing Areas [page 509] Delete All Marketing Areas from Origin [page 509] Delete Account Team Members [page 510] Delete Marketing Attributes [page 510] Delete Additional IDs [page 511]
508
PUBLIC
Integration Guide Integration APIs
Delete Marketing Areas
HTTP Method POST
Function Import InteractionContactDeleteMarketingArea Deletes all occurrences of a marketing area from an interaction contact.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST InteractionContactDeleteMarketingArea? InteractionContactID='DEV_TEST'&InteractionContactOrigin='SAP_ERP_CONTACT'&Int eractionContactMktgArea='GLOBAL' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete All Marketing Areas from Origin
HTTP Method POST
Function Import IntactnCntctOriginDeleteAllMktgAreas Deletes all marketing areas from one origin.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST InteractionContactOriginDeleteAllMktgAreas? InteractionContactID='DEV_TEST'&InteractionContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json
Integration Guide Integration APIs
PUBLIC
509
Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Account Team Members
HTTP Method POST
Function Import IntactnCntctDeleteAllAccountTeamMembers Deletes all account team members for one interaction contact.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST InteractionContactDeleteAllAccountTeamMembers? InteractionContactID='DEV_TEST'&InteractionContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Marketing Attributes
HTTP Method POST
Function Import IntactnCntctOrignDeleteAllMktgAttributes Deletes all marketing attributes from one origin.
510
PUBLIC
Integration Guide Integration APIs
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST IntactnCntctOrignDeleteAllMktgAttributes? InteractionContactID='DEV_TEST'&InteractionContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Additional IDs
HTTP Method POST
Function Import IntactnCntctOriginDeleteAdditionalIDs Deletes all additional IDs from one origin except for IDs that come from the origin data.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST IntactnCntctOriginDeleteAdditionalIDs? InteractionContactID='DEV_TEST'&InteractionContactOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
511
Function Import Parameters
Property
Description
Edm Core Type Max Length
Mandatory
Key
InteractionCon ID of Interaction Edm. String
255
X
X
tactID
Contact
InteractionCon Origin of Interac Edm. String
20
X
X
tactOrigin
tion Contact
InteractionCon Marketing Area tactMktgArea
Edm. String
X
X
Parent topic: Interaction Contacts [page 469]
Related Information
Basic Concepts [page 472] Structure of API_MKT_INTERACTION_CONTACT [page 475] Payload Examples for Interaction Contacts [page 495]
5.2.3 Corporate Accounts
Public OData API (API_MKT_CORPORATE_ACCOUNT_SRV Version 3) for reading and writing master data about Corporate Accounts only. Corporate accounts are companies or organizations that interact with your company. The public API for Corporate Account supports operations on the Corporate Account Business Object and the Marketing Permissions Business Object.
Note
We recommend that you use the current version 0003 of this service. If you want to use the previous version, you'll find the help links here: Version 0002: Contact, Interaction Contact, Corprorate Account API, Version 0002
512
PUBLIC
Integration Guide Integration APIs
Technical Data
Caution
The API services available in SAP Marketing Cloud must not be used for mass read (GET) operations. In other words, you cannot use them for extracting all available data, for example, to extract millions of contacts or interactions from your marketing system.
Name of the Service Authorizations
Communication Scenario ID Component for Incidents
API_MKT_CORPORATE_ACCOUNT
The following business catalog roles are required: For version 2: SAP_CEC_BC_MKT_API_IC2_PC For version 3: SAP_CEC_BC_MKT_API_IC3_PC
SAP_COM_0207
CEC-MKT-DM-IC (Interaction Contacts) CEC-MKT-DM-PER (Permissions and Subscriptions)
Note
Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408].
OData Version Root URI Service Metadata URI:
Field Extensibility Supported
2.0
https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003
https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/$me tadata
Yes. For more information, search for extensibility in Structure of API_MKT_CORPORATE_ACCOUNT [page 517].
Note
You need to open the collapsible sections of the docu ment first.
Technical Field Documentation
You can access detailed technical documentation for the API fields by downloading a metadata file in one of the following ways:
Integration Guide Integration APIs
PUBLIC
513
Access Link
Comment
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV; v=0003/$metadata?sapdocumentation=all
Only for internal access. You need to provide the server and port names.
Corporate Account Details Page
General access to the Details page of the service on SAP API Hub. One-time regis tration is required for first-time users.
1. On the Details page, click Download Specification and download as EDMX. 2. Specify which application you want to use to open the EDMX file type.
Marketing - Corporate Accounts API
General access link takes you directly to the Contacts metadata file. One-time registration or logon is required.
Note
You can convert the XML file to an XML table to make it easier to read.
Please note the meaning of the following values in the file:
Metadata Value in XML sap:updatable sap:creatable nullable
Meaning When FALSE read-only field read-only field mandatory field
Basic Concepts [page 515] Public OData API (API_MKT_CORPORATE_ACCOUNT_SRV) for reading and writing master data about Corporate Accounts only. Corporate accounts are companies or organizations that interact with your company.
Structure of API_MKT_CORPORATE_ACCOUNT [page 517] This document describes the structure of the Public OData API API_MKT_CORPORATE_ACCOUNT.
Payload Examples for Corporate Accounts [page 538] Payload examples for API_MKT_CORPORATE_ACCOUNT.
Function Imports [page 551] Function imports are used to perform custom operations on an entity, which are typically not provided by OData operations. This section contains payload examples for the following function imports:
514
PUBLIC
Integration Guide Integration APIs
5.2.3.1 Basic Concepts
Public OData API (API_MKT_CORPORATE_ACCOUNT_SRV) for reading and writing master data about Corporate Accounts only. Corporate accounts are companies or organizations that interact with your company.
Processing Info and Best Practices
Note
For generally applicable recommendations and best practices, make sure you refer to the section Best Practices and Recommended Package Sizes [page 400].
The minimum data required when importing corporate accounts is an ID, an ID Origin, a timestamp, and at least one other attribute.
When to use PUT and PATCH: PUT requests are most suitable for an initial data import, for example, when you want to create a new corporate account. A PUT request requires that you always send all properties. Any properties that you omit are overwritten by blank entries. That is, any existing entries are deleted. If no record is found, a new record is created. In other words. the PUT request functions as a full upsert. We recommend that you use PATCH requests for all other imports. A PATCH request updates only the properties provided in the request body and leaves everything untouched that was not provided. So, you can omit all properties that are not to be changed. Like the PUT request, if no record is found, a new record is created with the available properties.. In other words. the PATCH request functions as a delta upsert. An additional advantage of using PATCH is that you specify your own sequence ID. For this reason, it is more flexible than a PUT operation, where the sequence ID is set by default and cannot be changed. Basically, since you can use PATCH with the same payload as you would use for PUT, the PATCH operation is more universal and you can work with it exclusively. We recommend that you don't mix PUT and PATCH operations. Doing so can lead to unwanted results since a PUT operation is processed before a PATCH.
Do not combine a DELETE operation with other OData operations in one changeset. We recommend that you do not combine the OData operations PUT, PATCH, POST, with a DELETE operation in the same changeset. For example, let's say you want to update data for corporate account A by adding an additional email address and at the same time delete a mobile number that is no longer valid. So, you send a PUT operation on the AdditionalId entity with the new email address and a DELETE operation within the same changeset. One of these operations could cancel out the other and the resulting dataset will not be as intended. Recommended Practice: For such combined operations including a DELETE operation, we recommend that you always use the relevant function import, which allows deletion of specific entities, together with the appropriate OData operation PUT, PATCH, or POST within the same changeset.
Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service as described in [OData-URI ]. The batch request must contain a header parameter content-type, specifying the value multipart/mixed and boundary=batch.
Use of codes versus free text: The properties listed in the left column of the table require code values. Incorrect codes will result in import errors, indicating that the corresponding code is not valid. If you are
Integration Guide Integration APIs
PUBLIC
515
not thoroughly familiar with the internal codes available in SAP Marketing for these properties, you should use properties that allow a free text. For example, if you do not know that DE is the country code for Germany, you can use Germany as the free text.
Code in SAP Marketing Country Industry Department Function GenderCode Language MaritalStatus AddressRegion FormOfAddress
Free Text Property CountryName IndustryName DepartmentName FunctionName GenderCodeName LanguageName MaritalStatusName RegionName FormOfAddressName
You must map your free text names to the available codes in the Map Free Text app. For more information, see Map Free Texts.
Do not mix different types of services for operations involving the same data source. For example, when importing contacts from a web shop, do not use the CUAN_IMPORT service for a PUT operation and then the API_MKT_CORPORATE_ACCOUNTS service to PATCH contacts. You can, however, migrate from CUAN_IMPORT to the API* services.
One contact can be assigned to a maximum of one corporate account, while one corporate account can have more than one contact.
The origin that you pass via the property ContactOrigin cannot be shareable. If the main origin is set to Shareable, this will trigger an error. For more information, see Configuring Origins.You can view sample payloads and test the API at https://api.sap.com/api/API_MKT_CORPORATE_ACCOUNT_SRV_0003/ resource .
Note
The UTC timestamp of permissions can't lie in the future.
When you import permissions, they must not have a timestamp that lies in the future. The timestamp of imported permissions is always in UTC. The field name in the OData service is called PermissionUTCDateTime.
If you want to use your local timestamp, you have to add the time zone information, that is, your local time zone together with the time zone offset or enter a timestamp that is converted to UTC.
The date and time information is adapted by the standard time difference (offset) with +01:00 for Central European Time (CET) or -05:00 for Eastern Standard Time (EST). For example: 2019-01-01T12:00:00+01:00
If you live east of UTC and enter your timestamp in your local time zone without time zone offset, this will result in a future timestamp. For example, you live in Germany and your local time is 8 a.m on November, 28. If you enter this as the UTC timestamp without a time zone offset, the UTC permission timestamp will show as 8 a.m., November 28, while in the UTC time zone it's 7 a.m., November 28.You've created a UTC permission timestamp that lies in the future and is invalid.
516
PUBLIC
Integration Guide Integration APIs
Error Messages
If the OData service is not accessible, for example due to missing authorization, or because the system is not available, a corresponding HTTP status code is returned.
If the OData service is accepted by the gateway component in the SAP Marketing Cloud system, the HTTP status code 201 or 204 is returned. Any processing errors are recorded in the SAP Marketing Cloud system in the Import Monitor app, where they can be monitored, restarted and discarded.
By default, data processing for contacts, interaction contacts, corporate accounts, or marketing permissions is asynchronous. In most cases an OK response, such as a receipt notification, is returned almost immediately. An exception to this would be data uploads that might contain severe errors, such as parse or format errors, and so would not return an OK response but an error message. The data you upload lands in a staging area, where it is then further processed. You can change the default setting to synchronous processing by setting the property Sap-Cuan-ForceSynchronousProcessing to True. In this case, any error messages are returned as soon as they are detected.
To view the processing status and to check for errors or success messages, you must launch the Import Monitor app. Messages for marketing permissions in this app are displayed under the API for Contact, API for Interaction Contacts, or API for Corporate Accounts depending on the API OData service you use. In the event of errors, you can restart or discard the import in the Import Monitor.
Field Extensibility
In addition to the pre-delivered attributes, you can add customer-specific fields using the Custom Fields app. For more information about how to do this, see Custom Fields. Please enable the Data Source under UIs and Reports: API_MKT_CORPORATE_ACCOUNT_SRV 0002
Parent topic: Corporate Accounts [page 512]
Related Information
Structure of API_MKT_CORPORATE_ACCOUNT [page 517] Payload Examples for Corporate Accounts [page 538] Function Imports [page 551]
5.2.3.2 Structure of API_MKT_CORPORATE_ACCOUNT
This document describes the structure of the Public OData API API_MKT_CORPORATE_ACCOUNT. Make sure you read these topics before you start: Best Practices and Recommended Package Sizes [page 400]
Integration Guide Integration APIs
PUBLIC
517
Basic Concepts [page 515]
Request Header
The request header contains the additional header fields listed in the table. Remember to include at least the mandatory request header fields in each payload.
Property
Sap-CuanRequestTimestamp
Sap-Cuan-SequenceId
Example '2017-09-28T12:13:14'
PatchAddress
Sap-Cuan-
EXT
SourceSystemType
Sap-Cuan-SourceSystemId HYBRIS
Description
Max.
Manda
Length tory
Timestamp of the import run in
X
this format.
This defines a set of fields that are to be updated, for example, address fields, which can be in terpreted as a field group. The combination of the header fields Sap-Cuan-SequenceId and SapCuan-RequestTimestamp is used to check the sequence of the data received. If the data that is received has a timestamp older than already imported data, it is ignored.
X (only manda tory for Patch Mode)
Type of source system. This is a 20 free text field.
Identifier of source system. This 255 is a free text field.
518
PUBLIC
Integration Guide Integration APIs
Property
Example
Sap-Cuan-
X
ForceSynchronousProcessi
ng
Sap-Cuan-ReferenceId
345g67980907
Description
Max.
Manda
Length tory
This flag is deselected by de fault, which means that up loaded data is processed asyn chronously. On upload, a suc cess message is output immedi ately, unless there are errors such as authorization issues or bad requests. Objects are up loaded to the staging area and processed successively from there. All status messages can be displayed in the Import Monitor app.
You can force synchronous processing of imports by setting this flag. In this case, an error message will be returned as soon as an error is detected. Such error messages are output in the Import Monitor app
External reference of the in
32
bound message
Entity Sets
The Corporate OData API provides the following entity sets:
Entity Set CorporateAccount AccountTeamMembers
Description
Path
This entity contains all contact information from the root.
/CorporateAccount
This entity contains information about the account team mem bers.
Note
As TeamMemberID, you must enter the employee ID.
/AccountTeamMembers
AdditionalIDs
This entity contains information about additional IDs.
/AdditionalIDs
Integration Guide Integration APIs
PUBLIC
519
Entity Set
Description
Path
CorporateAccountOrigin Data
This entity contains contact origin data.
Note
/CorporateAccountOrigin Data
The property OriginDataLastChgUTCDateTime is manda tory and must be specified.
MarketingAttributes MarketingAreas
This entity contains information about marketing attributes. This entity contains information about marketing areas.
/MarketingAttributes /MarketingAreas
Corporate Accounts
GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ CorporateAccount
Field Extensibility: The following business contexts are relevant: Marketing: Corporate Account and Marketing: Contact and Corporate Account
You can perform the following operations on the Corporate Account entity set:
HTTP Method GET
Description
Get a list of corporate accounts. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 corporate accounts can be fetched in a single request
Specification of TOP is mandatory.
Path
/CorporateAccount? $top=1
Get the details of a specific corporate accounts using the Corporate Account UUID.
/Corporate Accounts(guid'<Corpo rateAccount UUID>')
AccountTeamMembers
You can perform the following operations on the AccountTeamMember entity set: GET: https://<Server>:<Port>/sap/opu/odata/SAP/
API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/AccountTeamMembers PUT, PATCH, or DELETE in batch: https://<Server>:<Port>/sap/opu/odata/SAP/
API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/$batch
520
PUBLIC
Integration Guide Integration APIs
PUT, PATCH, or DELETE in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ AccountTeamMembers (CorporateAccountID='<CorporateAccountID>',CorporateAccountOrigin='<CorporateAcc ountOrigin>',TeamMemberID='<TeamMemberID>',Role='<Role>')
HTTP Method GET
Description Get a list of account team members.
Path
/AccountTeamMembers?$top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 account team members can be fetched in a single request
Specification of TOP is mandatory.
POST (Batch) PUT
Get the details of a specific account team member.
This operation is not supported.
Update or create an account team member in batch mode.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
Delete an account team member in batch mode.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
Add one new account team member
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
Update or create an account team member.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/ AccountTeamMembers (CorporateAccountID='<Corporate AccountID>',CorporateAccountOri gin='<CorporateAccountOrigin>', TeamMemberID='<TeamMemberID>',R ole='<Role>')
Integration Guide Integration APIs
PUBLIC
521
HTTP Method PATCH
DELETE
Description Add one new account team member.
Delete an account team member.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/ AccountTeamMembers (CorporateAccountID='<Corporate AccountID>',CorporateAccountOri gin='<CorporateAccountOrigin>', TeamMemberID='<TeamMemberID>',R ole='<Role>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/ AccountTeamMembers (CorporateAccountID='<Corporate AccountID>',CorporateAccountOri gin='<CorporateAccountOrigin>', TeamMemberID='<TeamMemberID>',R ole='<Role>')
AdditionalIDs
You can perform the following operations on the AdditionalIDs entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/AdditionalIDs
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ AdditionalIDs(CorporateAccountID='<CorporateAccountID>',CorporateAccountOrigin=' <CorporateAccountOrigin>',InteractionContactAdditionalOrigin='<InteractionContac tAdditionalOrigin>',InteractionContactAdditionalExternalID='<InteractionContactA dditionalExternalID>')
522
PUBLIC
Integration Guide Integration APIs
HTTP Method GET
POST (Batch) PUT
Description
Get a list of additional IDs by Account ID and ID Origin.
Path
/AdditionalIDs?$top=1
This method supports standard OData pa rameters such as $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 additional IDs can be fetched in a single request
Specification of TOP is mandatory. $filter is not supported for additional
IDs.
Get the details of a specific additional ID.
Update or create an additional ID in batch mode. Append one new additional ID
Update or create an additional ID.
/ AdditionalIDs('<CorporateAccoun tID>,<CorporateAccountOrigin>,< InteractionContactAdditionalOri gin>,<InteractionContactAdditio nalExternalID>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/ AdditionalIDs(CorporateAccountI D='<CorporateAccountID>',Corpor ateAccountOrigin='<CorporateAcc ountOrigin>',InteractionContact AdditionalOrigin='<InteractionC ontactAdditionalOrigin>',Intera ctionContactAdditionalExternalI D='<InteractionContactAdditiona lExternalID>')
Integration Guide Integration APIs
PUBLIC
523
HTTP Method PATCH
Description Add one new additional ID.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/ AdditionalIDs(CorporateAccountI D='<CorporateAccountID>',Corpor ateAccountOrigin='<CorporateAcc ountOrigin>',InteractionContact AdditionalOrigin='<InteractionC ontactAdditionalOrigin>',Intera ctionContactAdditionalExternalI D='<InteractionContactAdditiona lExternalID>')
CorporateAccountOriginData
You can perform the following operations on the CorporateAccountOriginData entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/CorporateAccountOriginData
PUT, PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/$batch
PUT, PATCH in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ CorporateAccountOriginData(CorporateAccountID=' <CorporateAccountID>',CorporateAccountOrigin='<CorporateAccountOrigin>')
Field Extensibility: The following business contexts are relevant: Marketing: Corporate Account and Marketing: Contact and Corporate Account
524
PUBLIC
Integration Guide Integration APIs
HTTP Method GET
POST (Batch)
PUT
Description Get a list of Corporate Account Origin Data.
Path
/CorporateAccountOriginData? $top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 corporate ac count origin data entities can be fetched in a single request
Specification of TOP is mandatory.
Get the details of specific corporate account origin data.
/ CorporateAccountOriginData('<Co rporateAccountID>,<CorporateAcc ountOrigin>')
Update or create contact origin data in batch mode. Creates a CorporateAccount if the Cor porateAccount not exist.
Note
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
The property OriginDataLastChgUTCDateTime is mandatory and must be specified.
Delta Update PATCH attributes of the entity CorporateAccountOriginData
Update or create corporate account origin data. This creates a contact if the corporate account not exist.
Note
The property OriginDataLastChgUTCDateTime is mandatory and must be specified.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/ CorporateAccountOriginData(Corp orateAccountID=' <CorporateAccountID>',Corporate AccountOrigin='<CorporateAccoun tOrigin>')
Integration Guide Integration APIs
PUBLIC
525
HTTP Method PATCH
Description
Delta Update PATCH attributes of the entity CorporateAccountOriginData.
Path
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/ CorporateAccountOriginData(Corp orateAccountID=' <CorporateAccountID>',Corporate AccountOrigin='<CorporateAccoun tOrigin>')
MarketingAttributes
You can perform the following operations on the MarketingAttributes entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/MarketingAttributes
PUT, PATCH, or DELETE in BATCH: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/$batch
PUT, PATCH, or DELETE in a single operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/MarketingAttributes(CorporateAccountID=' <CorporateAccountID>',CorporateAccountOrigin=' <CorporateAccountOrigin>',MarketingAttributeCategory='<MarketingAttributeCategor y>',MarketingAttributeValue='<MarketingAttributeValue>')
Field Extensibility: The following business contexts are relevant: Marketing: Marketing Attributes for Contacts.
HTTP Method GET
Description
Path
Get a list of marketing attributes by Contact ID and ID Origin.
/MarketingAttributes?$top=1
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 marketing at tributes can be fetched in a single re quest
Specification of TOP is mandatory.
526
PUBLIC
Integration Guide Integration APIs
HTTP Method POST POST POST PUT
PATCH
DELETE
Description
Path
Get the details of a specific marketing attribute.
/ MarketingAttributes('<Corporate AccountID>,<CorporateAccountOri gin>,<MarketingAttributeCategor y>,<MarketingAttributeValue>')
Update or create marketing attributes in batch mode.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
Delete marketing attributes in batch mode.
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
Append one new Marketing Attribute
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
Update or create marketing attributes. Add one new marketing attribute. Delete marketing attributes.
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_CORPO RATE_ACCOUNT_SRV;v=0003/MarketingAt tributes(ContactID=' <CorporateAccoun tID>',CorporateAccountOrigin=' <Corpora teAccountOrigin>',MarketingAttributeCate gory='<MarketingAttributeCategory>',Mar ketingAttributeValue='<MarketingAttribute Value>')
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_CORPO RATE_ACCOUNT_SRV;v=0003/MarketingAt tributes(CorporateAccountID=' <Corpora teAccountID>',CorporateAccountOrigin=' <CorporateAccountOrigin>',MarketingAttri buteCategory='<MarketingAttributeCate gory>',MarketingAttributeValue='<Marketin gAttributeValue>')
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_CORPO RATE_ACCOUNT_SRV;v=0003/MarketingAt tributes(CorporateAccountID=' <Corpora teAccountID>',CorporateAccountOrigin=' <CorporateAccountOrigin>',MarketingAttri buteCategory='<MarketingAttributeCate gory>',MarketingAttributeValue='<Marketin gAttributeValue>')
Integration Guide Integration APIs
PUBLIC
527
MarketingAreas
You can perform the following operations on the MarketingAreas entity set:
GET: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003
PUT, PATCH in BATCH: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/$batch
PUT, PATCH in a sngle operation: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ MarketingAreas(CorporateAccountID='<CorporateAccountID>',CorporateAccountOrigin= '<CorporateAccountOrigin>',InteractionContactMktgArea='<InteractionContactMktgAr ea>')
HTTP Method GET
Description
Get a list of marketing areas by Contact ID and ID Origin.
Path
/sap/opu/odata/SAP/ API_MKT_CONTACT_SRV;v=0003/ Contacts? $expand=MarketingAreas&$top=2
This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
Note
A maximum of 5000 marketing areas can be fetched in a single re quest
Specification of TOP is mandatory.
POST POST
Get the details of a specific marketing area.
Update or create marketing areas in batch mode. Append one new Marketing Area
/ MarketingAreas('<CorporateAccou ntID>,<CorporateAccountOrigin>, < InteractionCorporateAccountMktg Area>,')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/$batch
528
PUBLIC
Integration Guide Integration APIs
HTTP Method PUT
PATCH
Description Update or create marketing areas.
Add one new marketing area.
Path
https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_CORPO RATE_ACCOUNT_SRV;v=0003/MarketingAr eas(CorporateAccountID='<CorporateAc countID>',CorporateAccountOrigin='<Corpo rateAccountOrigin>',InteractionContactMkt gArea='<InteractionContactMktgArea>')
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CORPORATE_ACCOUNT_SRV;v =0003/ MarketingAreas(CorporateAccount ID='<CorporateAccountID>',Corpo rateAccountOrigin='<CorporateAc countOrigin>',InteractionContac tMktgArea='<InteractionContactM ktgArea>')
MarketingPermissions
Entity Path: /MarketingPermissions
Field Extensibility: The following business context is relevant: Marketing: Marketing Permissions. Custom fields for business object MKT_PERMISSION (Marketing: Permission) are only supported if you use version 2 of the API_MKT_CORPORATE_ACCOUNT service.
Note
For all HTTP operations both $batch requests and single requests can be used. Interactions are assigned when marketing permissions are created or updated to allow for analysis of
corporate accounts.
You can perform the following operations on the MarketingPermissions entity set:
HTTP Method GET
Description
Path
Get a list of marketing permissions by Corporate Account. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
/ MarketingPermis sions?$top=1
Note
A maximum of 5000 marketing permissions can be fetched in a single request
Specification of TOP is mandatory.
Integration Guide Integration APIs
PUBLIC
529
HTTP Method PATCH
PUT
Description Update or create marketing permissions. This creates a marketing per mission if the permission does not exit.
Update or create marketing permissions. This creates a marketing per mission if the permission does not exit. Delta Update of PATCH attributes of the entity MarketingPermission.
Path
/ MarketingPermis sions(Corporate AccountID='<Cor porateAccountID >',CorporateAcc ountOrigin='<Co rporateAccountO rigin>',Corpora teAccountPermis sionID='<Corpor ateAccountPermi ssionID>',Corpo rateAccountOrig in='<CorporateA ccountPermissio nOrigin>',Marke tingArea='<Mark etingArea>',Com municationMediu m='<Communicati onMedium>')
/ MarketingPermis sions(Corporate AccountID='<Cor porateAccountID >',CorporateAcc ountOrigin='<Co rporateAccountO rigin>',Corpora teAccountPermis sionID='<Corpor ateAccountPermi ssionID>',Corpo rateAccountOrig in='<CorporateA ccountPermissio nOrigin>',Marke tingArea='<Mark etingArea>',Com municationMediu m='<Communicati onMedium>')
The table below describes the properties for the entity MarketingPermissions.
530
PUBLIC
Integration Guide Integration APIs
MarketingPermissions Property Names and Descriptions
Property Name
Property Description
Usage
CorporateAccountID
The CorporateAccountID and Corpora teAccountOrigin identify the corporate account uniquely.
Mandatory
Example: a business partner ID from the CRM system.
CorporateAccountUUID
Unique ID of a corporate account in SAP Marketing Cloud .
Read-Only
CorporateAccountOrigin
The CorporateAccountID and Corpora teAccountOrigin identify the contact uniquely.
Mandatory
Example: SAP_CRM_BUPA
CorporateAccountPermissionID
The CorporateAccountPermissionID and CorporateAccountPermissionOri gin store marketing permissions.
Mandatory
Example: first.lastname@company.de
CorpAcctPermissionOrigin
The CorporateAccountPermissionID and CorporateAccountPermissionOri gin store marketing permissions.
Mandatory
CorpAcctPermissionOrigin is the origin of the corporate account ID that stores marketing permissions.
By defining the origin, you determine that a corporate account with an ID as sociated to a source is eligible to be an alyzed.
You can configure origins of contacts IDs in the Configuring Origins configuration app.
Example: EMAIL
CorpAcctPermissionOriginName
Description of property CorpAcctPer missionOrigin
Read-Only
MarketingArea
Identifies an area of responsibility or an organizational unit.
You use a marketing area to restrict ac cess to instances of an object, such as campaign, email message, email tem plate, target group, or permission.
Mandatory
The MarketingArea property field must be passed, but can be left empty.
Integration Guide Integration APIs
PUBLIC
531
Property Name MarketingAreaName CommunicationMedium
CommunicationMediumName PermissionUUID PermissionUTCDateTime
PermissionSourceObject
PermissionSourceObjectType
PermissionSourceSystem PermissionSourceSystemType
Property Description
Usage
Description of property MarketingArea Read-Only
Represents the type of permission, for Mandatory example, EMAIL or PHONE.
You can configure communication me dia in the Managing Interaction Content configuration app.
Description of property Communica tionMedium
Unique ID of a permission in SAP Marketing Cloud .
This is the timestamp for when the per Mandatory mission was given or removed.
Note
The time stamp must not be initial or null.
This field provides information on the source of the permission, that is, where it came from. For example, the ID of a landing page.
If you enter a value for the Permission SourceObject property, you must also specify a value for the PermissionSour ceObjectType.
This field can be filled with freetext.
Both fields must be filled or left empty.
This field provides information on the source of the permission and its type. For example, the business object name of a landing page.
This field can be filled with freetext.
This is the system that stores the per mission. For example, ABD client 100.
This field can be filled with freetext.
If you enter a value for the Permission SourceSystem property, you must also specify a value for the PermissionSour ceSystemType.
This is the type of system where the permission is stored. For example, SAP_CEI.
This field can be filled with freetext.
532
PUBLIC
Integration Guide Integration APIs
Property Name
Property Description
Usage
PermissionSourceCommMedium
Indicates where the permission comes from, such as WEB, EMAIL, or PHONE. In case PermissionSourceCommMedium is not filled, this property is set to WEB.
PermissionSourceCommMediumName Description of property Permission SourceCommMedium
PermissionIsImplicit
If the system sets this field to TRUE, then it is an implicit permission, which is determined by country-specific regu lation.
Read-Only
If the system sets this field to FALSE, the contact has given this permission explicitly.
PermissionNoteText
A text to describe a permission change.
IsConfirmationRequired
This is a boolean parameter. If the pa rameter is set to TRUE, the permission is stored using the double opt-in or optout process.
If the property is not specified in the payload or it is set to FALSE the permis sion is directly stored.
LastChangedByUser
Name of the user who has changed the Read-Only permissions last.
LastChangeDateTime
Date and time of the last permission change.
Read-Only
MarketingSubscriptions
Entity Path: /MarketingSubscriptions Field Extensibility: The following business context is relevant: Marketing: Marketing Permissions. Custom fields for business object MKT_PERMISSION (Marketing: Permission) are only supported if you use version 2 or version 3 of the API_MKT_CONTACT service.
Note
For all HTTP operations both $batch requests and single requests can be used. Interactions are assigned when marketing permissions are created or updated to allow for analysis of
contacts.
Integration Guide Integration APIs
PUBLIC
533
You can perform the following operations on the MarketingSubscriptions entity set:
HTTP Method GET
Description
Path
Get a list of marketing subscriptions by Contact ID and ID Origin. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby
/ MarketingSubscriptio ns?$top=1
Note
A maximum of 5000 marketing subscriptions can be fetched in a single request
Specification of TOP is mandatory.
PATCH PUT
Update or create subscriptions. This creates a subscription if the subscription does not exit.
/ MarketingSubscriptio ns(CorporateAccountI D='<CorporateAccount ID>',CorporateAccoun tOrigin='<ContactOri ginCorporateAccount> 'CorporateAccountPer missionID='<Corporat eAccountPermissionID >',CorporateAccountP ermissionOrigin='<Co rporateAccountPermis sionOrigin>',Communi cationMedium='<Commu nicationMedium>',Sub scriptionTopic='<Sub scriptionTopic>')
Update or create subscriptions. This creates a subscription if the subscription does not exit.
Delta Update of PATCH attributes of the entity MarketingSub scriptions.
/ MarketingSubscriptio ns(CorporateAccountI D='<CorporateAccount ID>',CorporateAccoun tOrigin='<ContactOri ginCorporateAccount> 'CorporateAccountPer missionID='<Corporat eAccountPermissionID >',CorporateAccountP ermissionOrigin='<Co rporateAccountPermis sionOrigin>',Communi cationMedium='<Commu nicationMedium>',Sub scriptionTopic='<Sub scriptionTopic>')
534
PUBLIC
Integration Guide Integration APIs
Marketing Subscription Property Descriptions The table describes the properties for the MarketingSubscription entity.
MarketingSubscription Property Names and Descriptions
Property Name
Property Description
Usage
CorporateAccountID
The CorporateAccountID and Corpora teAccountOrigin identify the contact uniquely.
Example: a business partner ID from the CRM system.
CorporateAccountOrigin
The CorporateAccountID and Corpora teAccountOrigin identify the contact uniquely.
The CorporateAccountID will not be saved to the MarketingSubscription but is only used to derive a uniqueCorpora teAccountUUID. This data will not be re turned in GET requests.
Example: SAP_CRM_BUPA
CorporateAccountSubscriptionID
The InteractionContactPermissionID Mandatory and InteractionContactSubscriptionOri gin store marketing subscription.
CorpAcctSubscriptionOrigin
The CorporateAccountSubscriptionID and CorpAcctSubscriptionOrigin store marketing subscriptions.
Mandatory
CorpAcctSubscriptionOrigin is the ori gin of a corporate account ID that stores marketing subscriptions. The origin indicates the source of an ID. By defining the origin, you determine that a corporate account with an ID associ ated to a source can be analyzed.
Example: EMAIL
You can configure origins of contact IDs in the Configuring Origins configuration app.
CorpAcctSubscriptionOriginName
Description of property CorpAcctSub Read-Only scriptionOriginName
Integration Guide Integration APIs
PUBLIC
535
Property Name CommunicationMedium
CommunicationMediumName CorporateAccountUUID SubscriptionUUID SubscriptionUTCDateTime
SubscriptionSignUpExists SubscriptionTopic
SubscriptionTopicName SubscriptionSourceObject
Property Description
Usage
Represents the type of subscription, for Mandatory example, EMAIL or PHONE.
You can configure communication me dia in the Managing Interaction Content configuration app.
Description of property Communica tionMedium
Read-Only
Unique ID of a corporate account in SAP Marketing Cloud .
Read-Only The field value is returned internally.
Unique ID of a subscription in SAP Marketing Cloud .
This is the timestamp for when the sub Mandatory scription was given or removed.
Note
The time stamp must not be initial or null.
The subscription can be YES (Y) or NO Mandatory (N).
Represents a newsletter in SAP Marketing Cloud .
Mandatory
The SubscriptionTopic property field must be passed, but can be left empty.
If you want to create a newsletter sub scription, you must specify the Sub scriptionTopic.
Name of the subscription topic.
This field provides information on the source of the subscription, that is, where it came from. For example, the ID of a landing page.
This field can be filled with freetext.
536
PUBLIC
Integration Guide Integration APIs
Property Name SubscriptionSourceObjectType
SubscriptionSourceSystem
SubscriptionSourceSystemType
SubscriptionSourceCommMedium
SubscriptionSourceCommMedium Name IsConfirmationRequired
LastChangedByUser LastChangeDateTime SubscriptionNoteText
Property Description
Usage
This field provides information on the source of the subscription and its type. For example, the business object name of a landing page.
This field can be filled with freetext.
This is the system that stores the sub scription. For example, your local sys tem ID.
This field can be filled with freetext.
This is the type of system where the subscription is stored. For example, SAP_CEI.
This field can be filled with freetext.
Indicates where the subscription comes from, such as WEB, EMAIL, or PHONE. In case SubscriptionSourceCommMedium is not filled, this property is set to WEB.
Description of property Subscription SourceCommMedium
This is a boolean parameter. If the pa rameter is set to TRUE, the subscription is stored using the double opt-in or optout process.
If the property is not specified in the payload or it is set to FALSE the sub scription is directly stored.
Name of the user who has changed the Read-Only subscription last.
Date and time of the last permission change.
Read-Only
A text to describe a subscription change.
Parent topic: Corporate Accounts [page 512]
Integration Guide Integration APIs
PUBLIC
537
Related Information
Basic Concepts [page 515] Payload Examples for Corporate Accounts [page 538] Function Imports [page 551]
5.2.3.3 Payload Examples for Corporate Accounts
Payload examples for API_MKT_CORPORATE_ACCOUNT.
Note
Before you start, please read the Processing Info and Best Practices section in Basic Concepts [page 515].
Remember to include at least the mandatory request header fields in each payload.
Available Payload Examples
Corporate Accounts, Marketing Permissions, and Marketing Subscriptions [page 538] GET Requests [page 544] Account Team Members [page 545] Additional IDs [page 546] Corporate Account Origin Data [page 547] Marketing Attributes [page 548] Marketing Areas [page 550]
Corporate Accounts, Marketing Permissions, and Marketing Subscriptions
Create Corporate Accounts with Additional IDs Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT CorporateAccountOriginData(CorporateAccountID='47110815',CorporateAccountOrigi n='SAP_ERP_CUSTOMER') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT
538
PUBLIC
Integration Guide Integration APIs
Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json {
"OriginDataLastChgUTCDateTime" : "2017-10-01T13:13:14Z", "CityName" : "Walldorf", "Country" : "DE", "EmailAddress" : "info.germany@sap.de", "FullName" : "SAP SE", "AddressHouseNumber" : "16", "Language" : "EN", "PhoneNumber" : "+496227747474", "ContactPostalCode" : "69190", "StreetName" : "Dietmar-Hopp-Allee" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(CorporateAccountID='47110815',CorporateAccountOrigin='SAP_ERP_CU STOMER',InteractionContactAdditionalOrigin='EMAIL',InteractionContactAdditiona lExternalID='info2.germany@sap.de') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(CorporateAccountID='47110815',CorporateAccountOrigin='SAP_ERP_CU STOMER',InteractionContactAdditionalOrigin='SAP_CRM_BUPA',InteractionContactAd ditionalExternalID='47110815') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(CorporateAccountID='47110815',CorporateAccountOrigin='SAP_ ERP_CUSTOMER',MarketingAttributeCategory='Company_Size',MarketingAttributeValu e='Big') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(CorporateAccountID='47110815',CorporateAccountOrigin='SAP_ ERP_CUSTOMER',MarketingAttributeCategory='Spoken_Language',MarketingAttributeV alue='English') HTTP/1.1 Content-Length: 1035 Accept: application/json
Integration Guide Integration APIs
PUBLIC
539
Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(CorporateAccountID='47110815',CorporateAccountOrigin='SAP_ ERP_CUSTOMER',MarketingAttributeCategory='Spoken_Language',MarketingAttributeV alue='German') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAttributes(CorporateAccountID='47110815',CorporateAccountOrigin='SAP_ ERP_CUSTOMER',MarketingAttributeCategory='Spoken_Language',MarketingAttributeV alue='French') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Corporate Account Note A PUT request is executed to set the IsEndOfPurposeBlocked flag.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT CorporateAccountOriginData(CorporateAccountID='AB20180612001P',CorporateAccountOrigin='SAP_ERP_BUPA') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-07-23T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { "IsEndOfPurposeBlocked": true, "OriginDataLastChgUTCDateTime":"2018-07-23T12:13:14" }
540
PUBLIC
Integration Guide Integration APIs
--changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Create Corporate Accounts with Marketing Permissions and Marketing Subscriptions Note The batch request is sent via http method POST containing PUT requests to create a new corporate account, marketing permission and marketing subscription. To update single attributes, you must use the PATCH request.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT CorporateAccountOriginData(CorporateAccountID='A98979992',CorporateAccountOrig in='SAP_C4C_BUPA') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-03-27T07:14:34' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 {
"OriginDataLastChgUTCDateTime" : "2019-07-01T13:04:46.000", "CityName" : "Walldorf", "Country" : "DE", "EmailAddress" : "info@company.de", "PhoneNumber" : "+619022580475611", "MobileNumber" : "+622485500519911", "FullName" : "Company GmbH", "AddressHouseNumber" : "99", "Language" : "DE", "ContactPostalCode" : "24105", "StreetName" : "Dietmar-Hopp-Allee" } --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingPermissions(CorporateAccountID='A98979992',CorporateAccountOrigin='SA P_C4C_BUPA',CorporateAccountPermissionID='info@company.de',CorpAcctPermissionO rigin='EMAIL',MarketingArea='',CommunicationMedium='EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.002' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 { "CorporateAccountID" : "A98979992", "CorporateAccountOrigin" : "SAP_C4C_BUPA", "CorporateAccountPermissionID" : "info@company.de", "CorpAcctPermissionOrigin" : "EMAIL", "PermissionUTCDateTime" : "2019-07-01T13:04:46.001", "PermissionGranted" : "Y", "PermissionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false,
Integration Guide Integration APIs
PUBLIC
541
"PermissionNoteText" : "Sample Permission" } --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingSubscriptions(CorporateAccountID='A98979992',CorporateAccountOrigin=' SAP_C4C_BUPA',CorporateAccountSubscriptionID='info@company.de',CorpAcctSubscri ptionOrigin='EMAIL',CommunicationMedium='EMAIL',SubscriptionTopic='1') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021 {
"SubscriptionUTCDateTime" : "2019-07-01T13:04:46.001", "SubscriptionSignUpExists" : "N", "SubscriptionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "SubscriptionNoteText" : "Sample Subscription" } --changeset_01869434-0010-0001---batch--
PATCH: Update Marketing Permissions and Marketing Subscriptions for a Corporate Account
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PATCH MarketingPermissions(CorporateAccountID='A98979992',CorporateAccountOrigin='SA P_C4C_BUPA',CorporateAccountPermissionID='info@company.de',CorpAcctPermissionO rigin='EMAIL',MarketingArea='',CommunicationMedium='EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.002' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "PermissionUTCDateTime" : "2019-07-01T13:04:46.001", "PermissionGranted" : "Y" }
--changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PATCH MarketingSubscriptions(CorporateAccountID='A98979992',CorporateAccountOrigin=' SAP_C4C_BUPA',CorporateAccountSubscriptionID='info@company.de',CorpAcctSubscri ptionOrigin='EMAIL',CommunicationMedium='EMAIL',SubscriptionTopic='1') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json
542
PUBLIC
Integration Guide Integration APIs
Content-Length: 1021 { "SubscriptionUTCDateTime" : "2019-07-01T13:04:46.001", "SubscriptionSignUpExists" : "N" }
--changeset_01869434-0010-0001---batch--
PUT: Update or Create Marketing Permissions and Marketing Subscriptions for a Corporate Account
Note
The sample code has a PUT request that updates marketing permissions and marketing subscriptions, or creates new marketing permissions and marketing subscriptions if they do not exist. To update single attributes, you must use the PATCH request. In addition, if the value of the property IsConfirmationRequired is set to true, a double opt-in is executed.
Sample Code
--batch Content-Type: multipart/mixed; boundary=changeset_01869434-0010-0001 --changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingPermissions(CorporateAccountID='A98979992',CorporateAccountOrigin= 'SAP_C4C_BUPA',CorporateAccountPermissionID='info@company.de',CorpAcctPermi ssionOrigin='EMAIL',MarketingArea='',CommunicationMedium='EMAIL') HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.002' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "PermissionUTCDateTime" : "2019-07-01T13:04:46.201", "PermissionGranted" : "Y", "PermissionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "PermissionNoteText" : "Sample Permission" }
--changeset_01869434-0010-0001 content-type: application/http content-transfer-encoding: binary PUT MarketingSubscriptions(CorporateAccountID='A98979992',CorporateAccountOrigi n='SAP_C4C_BUPA',CorporateAccountSubscriptionID='info@company.de',CorpAcctS ubscriptionOrigin='EMAIL',CommunicationMedium='EMAIL',SubscriptionTopic='1' ) HTTP/1.1 Accept: application/json Sap-Cuan-RequestTimestamp: '2019-07-01T13:04:46.005' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: C4C sap-cuan-referenceid: REQ1 Content-Type: application/json Content-Length: 1021
{ "SubscriptionUTCDateTime" : "2019-07-01T13:04:46.201", "SubscriptionSignUpExists" : "N", "SubscriptionSourceCommMedium" : "WEB", "IsConfirmationRequired" : false, "SubscriptionNoteText" : "Sample Subscription"
Integration Guide Integration APIs
PUBLIC
543
} --changeset_01869434-0010-0001---batch--
GET Requests
Get all explicit marketing permissions for a specific CorporateAccountUUID
/sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/MarketingPermissions? $filter=CorporateAccountUUID eq guid'6c0b84b7-5523-1ed9-a791-f00f93927b51' and PermissionIsImplicit eq false&$top=10
Get all marketing permissions and marketing subscriptions for a corporate account with a certain ID and origin
/sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ CorporateAccountOriginData(CorporateAccountID='A98979992 ',CorporateAccountOrigin='SAP_C4C_BUPA')? $expand=MarketingPermissions,MarketingSubscriptions
Get all marketing permissions and marketing subscriptions for a CorporateAccountUUID
/sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ CorporateAccounts(CorporateAccountUUID=guid'6c0b84b7-5523-1ed9-a791-f00f93927b51')? $expand=MarketingPermissions,MarketingSubscriptions
Get all marketing permissions for a corporate account with a certain ID and origin
/sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ CorporateAccountOriginData(CorporateAccountID='A98979992 ',CorporateAccountOrigin='SAP_C4C_BUPA')/MarketingPermissions
Get corporate account data via ID and origin together with its marketing permissions and marketing subscriptions
/sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/ CorporateAccountOriginData(CorporateAccountID='A98979992 ',CorporateAccountOrigin='SAP_C4C_BUPA')/MarketingSubscriptions
Get a corporate account via CorporateAccountUUID together with its marketing permissions and marketing subscriptions
/sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/MarketingSubscriptions? $filter=CorporateAccountUUID eq guid'6c0b84b7-5523-1ed9-a791-f00f93927b51'&$top=20
Get all marketing permissions for a specific email address of a corporate account
/sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/MarketingPermissions? $filter=CorporateAccountPermissionID eq 'info@company.de' and CorpAcctPermissionOrigin eq 'EMAIL' &$top=20
544
PUBLIC
Integration Guide Integration APIs
Get the first 500 a corporate accounts that subscribed to newsletter Fashion /sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/MarketingSubscriptions?$top=500& $filter=SubscriptionTopicName eq 'Fashion'
Get the first 100 marketing permissions that are newer than a certain date and time /sap/opu/odata/sap/API_MKT_CORPORATE_ACCOUNT_SRV;v=0003/MarketingPermissions? $top=10&$filter=PermissionUTCDateTime gt datetimeoffset'2019-01-01T00:00:00.001'
Account Team Members
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AccountTeamMembers(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',TeamMemberID='<TeamMemberID> ',Role='<Role>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
DELETE Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE AccountTeamMembers(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',TeamMemberID='<TeamMemberID> ',Role='<Role>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
545
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH AccountTeamMembers(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',TeamMemberID='<TeamMemberID> ',Role='<Role>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-10-02T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "CorporateAccountID": "<CorporateAccountID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Additional IDs
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT AdditionalIDs(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',InteractionContactAdditional Origin='<InteractionContactAdditionalOrigin>',InteractionContactAdditionalExte rnalID='<InteractionContactAdditionalExternalID>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
546
PUBLIC
Integration Guide Integration APIs
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH AdditionalIDs(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',InteractionContactAdditional Origin='<InteractionContactAdditionalOrigin>',InteractionContactAdditionalExte rnalID='<InteractionContactAdditionalExternalID>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "CorporateAccountID": "<CorporateAccountID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Corporate Account Origin Data
PUT - Batch Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT CorporateAccountOriginData(CorporateAccountID='<AccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PATCH - Batch Sample Code --batch
Integration Guide Integration APIs
PUBLIC
547
Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH CorporateAccountOriginData(CorporateAccountID='<AccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-28T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "OriginDataLastChgUTCDateTime":"2017-10-01T13:13:14", "StreetName": "<StreetName>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PUT Single Entity (use the same request header attributes as for batch) Note When you import single entities, the response body is empty. You can read the status of the import only in the response header in the attributes Status and Sap-Message.
Sample Code
Request: PUT: /sap/opu/odata/SAP/API_MKT_CONTACT_SRV;v=0003/ CorporateAccountOriginData(CorporateAccountID='C_20180828_00008',CorporateAcco untOrigin='SAP_ERP_CUSTOMER') {
"OriginDataLastChgUTCDateTime" : "2017-10-01T13:13:14Z", "CityName" : "Walldorf", "Country" : "DE", "EmailAddress" : "info.germany@sap.de", "FullName" : "SAP SE", "AddressHouseNumber" : "16", "Language" : "EN", "PhoneNumber" : "+496227747474", "ContactPostalCode" : "69190", "StreetName" : "Dietmar-Hopp-Allee" }
Marketing Attributes
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http
548
PUBLIC
Integration Guide Integration APIs
content-transfer-encoding: binary PUT MarketingAttributes(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',MarketingAttributeCategory=' <MarketingAttributeCategory>',MarketingAttributeValue='<MarketingAttributeValu e>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
DELETE Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE MarketingAttributes(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',MarketingAttributeCategory=' <MarketingAttributeCategory>',MarketingAttributeValue='<MarketingAttributeValu e>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH MarketingAttributes(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',MarketingAttributeCategory=' <MarketingAttributeCategory>',MarketingAttributeValue='<MarketingAttributeValu e>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2017-09-29T12:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json {
Integration Guide Integration APIs
PUBLIC
549
"CorporateAccountID": "<CorporateAccountID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Marketing Areas
PUT Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PUT MarketingAreas(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',InteractionContactMktgArea=' <InteractionContactMktgArea>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp:'2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH MarketingAreas(CorporateAccountID='<CorporateAccountID>', CorporateAccountOrigin='<CorporateAccountOrigin>',InteractionContactMktgArea=' <InteractionContactMktgArea>') HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp:'2017-10-01T13:13:14' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Sap-Cuan-SequenceId: UpdatePatch Content-Type: application/json { "CorporateAccountID": "<CorporateAccountID>" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
550
PUBLIC
Integration Guide Integration APIs
Parent topic: Corporate Accounts [page 512]
Related Information
Basic Concepts [page 515] Structure of API_MKT_CORPORATE_ACCOUNT [page 517] Function Imports [page 551]
5.2.3.4 Function Imports
Function imports are used to perform custom operations on an entity, which are typically not provided by OData operations. This section contains payload examples for the following function imports: Delete Marketing Area [page 551] Delete All Marketing Areas from Origin [page 552] Delete Account Team Members [page 552] Delete Marketing Attribute [page 553] Delete Additional IDs [page 554]
Delete Marketing Area
HTTP Method POST
Function Import CorporateAccountDeleteMarketingArea Deletes all occurrences of a marketing area from a corporate account.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST CorporateAccountDeleteMarketingArea? CorporateAccountID='DEV_TEST'&CorporateAccountOrigin='SAP_ERP_CONTACT'&Interac tionContactMktgArea='GLOBAL' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { }
Integration Guide Integration APIs
PUBLIC
551
--changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete All Marketing Areas from Origin
HTTP Method POST
Function Import CorpAcctOriginDeleteAllMktgAreas Deletes all marketing areas from one origin.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST CorporateAccountOriginDeleteAllMktgAreas? CorporateAccountID='DEV_TEST'&CorporateAccountOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Account Team Members
HTTP Method POST
Function Import CorpAcctDeleteAllAccountTeamMembers Deletes all account team members from one corporate account.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a
552
PUBLIC
Integration Guide Integration APIs
content-type: application/http content-transfer-encoding: binary POST CorporateAccountDeleteAllAccountTeamMembers? CorporateAccountID='DEV_TEST'&CorporateAccountOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Marketing Attribute
HTTP Method POST
Function Import CorpAcctOriginDeleteAllMktgAttributes Deletes all marketing attributes for one origin.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST CorpAcctOriginDeleteAllMktgAttributes? CorporateAccountID='DEV_TEST'&CorporateAccountOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
553
Delete Additional IDs
HTTP Method POST
Function Import
CorpAcctOriginDeleteAdditionalIDs Deletes all additional IDs from one origin except the IDs that come from the ori gin data.
Payload Example Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST CorpAcctOriginDeleteAdditionalIDs? CorporateAccountID='DEV_TEST'&CorporateAccountOrigin='SAP_ERP_CONTACT' HTTP/1.1 Content-Length: 1035 Accept: application/json Sap-Cuan-RequestTimestamp: '2018-11-02T09:19:12' Sap-Cuan-SourceSystemType: EXT Sap-Cuan-SourceSystemId: HYBRIS Content-Type: application/json { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Function Import Parameters
Property
Description
Edm Core Type Max Length
Mandatory
Key
CorporateAccou ID of Corporate Edm. String
255
X
X
ntID
Account
CorporateAccou Origin of Corpo Edm. String
20
X
X
ntOrigin
rate Account
CorporateAccou Marketing Area ntMktgArea
Edm. String
X
X
Parent topic: Corporate Accounts [page 512]
554
PUBLIC
Integration Guide Integration APIs
Related Information
Basic Concepts [page 515] Structure of API_MKT_CORPORATE_ACCOUNT [page 517] Payload Examples for Corporate Accounts [page 538]
5.2.4 Business Partners from SAP Cloud for Customer
Import business partners from SAP Cloud for Customer via CUAN_BUSINESS_PARTNER_IMP_SRV to marketing.
Overview [page 555] Technical Prerequisites [page 556] Basic Concepts [page 556] Structure of OData Service CUAN_BUSINESS_PARTNER_IMP_SRV [page 558] Payload Examples for CUAN_BUSINESS_PARTNER_IMP_SRV [page 566]
This section contains payload examples for replicating business partners from SAP Cloud for Customer to marketing with the OData service CUAN_BUSINESS_PARTNER_IMP_SRV.
5.2.4.1 Overview
OData service CUAN_BUSINESS_PARTNER_IMP_SRV is used for standard SAP Marketing Cloud integration with SAP Cloud for Customer. It is used to replicate SAP Cloud for Customer business partners to SAP Marketing Cloud interaction contacts. For details of standard SAP Marketing Cloud integration with SAP Cloud for Customer see Technical Prerequisites [page 556].
Parent topic: Business Partners from SAP Cloud for Customer [page 555]
Related Information
Technical Prerequisites [page 556] Basic Concepts [page 556] Structure of OData Service CUAN_BUSINESS_PARTNER_IMP_SRV [page 558] Payload Examples for CUAN_BUSINESS_PARTNER_IMP_SRV [page 566]
Integration Guide Integration APIs
PUBLIC
555
5.2.4.2 Technical Prerequisites
OData service CUAN_BUSINESS_PARTNER_IMP_SRV is available as part of standard integration with SAP Cloud for Customer. For the setup you have the following two options: 1. You are guided by the Cloud Integration Automation Service (see the SAP Help Portal at Introduction to
Cloud Integration Automation Service) by making use of the Maintenance Planner. 2. You use the integration setup of SAP Cloud for Customer with SAP Marketing Cloud (see SAP Cloud for
Customer Integration with SAP Marketing , or Setting Up SAP Marketing Cloud Integration with SAP Cloud for Customer (1J9).
Parent topic: Business Partners from SAP Cloud for Customer [page 555]
Related Information
Overview [page 555] Basic Concepts [page 556] Structure of OData Service CUAN_BUSINESS_PARTNER_IMP_SRV [page 558] Payload Examples for CUAN_BUSINESS_PARTNER_IMP_SRV [page 566]
5.2.4.3 Basic Concepts
Calling the OData Service
To import persons, companies, or relationships, a deep insert on entity Import Headers with HTTP method POST has to be performed; other methods like create, update, or delete on any other entity are not supported. You find code snippets under Structure of OData Service CUAN_BUSINESS_PARTNER_IMP_SRV [page 558] and the subordinated chapters.
Note
We recommend that you do not use batch processing ($batch) because error handling is more complex with batch processing. A batch request can return an OK code and still have errors that have to be checked in the response body. It is still possible to send multiple entities in one POST request without using batch processing.
556
PUBLIC
Integration Guide Integration APIs
Id and IdOrigin
The Id and the IdOrigin define the external key of an interaction contact in the source system. The IdOrigin indicates the source origin of the ID. It is either defined and delivered by SAP or can be maintained in the Self-Service Configuration app Define Origins of Contact ID. The attribute InternalId defines the ID of the company or person in SAP Marketing Cloud . The InternalId corresponds to a GUID of IdOrigin SAP_HYBRIS_MKT_IC.
Update Behavior
The source system must always provide a whole snapshot of the object as the system of SAP Marketing Cloud always updates a complete person, company or relationship; partial update of an entity is not supported. This means that it is not possible to update only two attributes of a person, for example, as the empty attributes of the update would overwrite the existing attribute entries.
If a facet or marketing area is not provided anymore in the update case the system sets this facet or marketing area to obsolete.
Sequence Handling with Attribute LastChangeDate
Attribute LastChangeDate of the entities Company, Person, or Relationship defines the last change in the source system. The timestamp is used to ensure that different requests are processed in the correct sequence. An incoming request is always validated against the last saved timestamp for the respective entity and checked, whether the provided LastChangeDate is newer than the saved one. Requests which contain an outdated LastChangeDate are discarded as a more recent snapshot of the entity has already been saved.
Code Values
Attributes based on codes can only process valid code values. If a request provides an invalid code value the request will result in an error. The error can be checked in the Import Monitor app. For more information, see Import Monitor [page 404].
Error Handling
Technical errors are returned to the sender with the corresponding HTTP error code. Application inbound errors are recorded in the system of SAP Marketing Cloud and can be monitored, restarted, and discarded in the Import Monitor app. For more information, see Import Monitor [page 404].
Integration Guide Integration APIs
PUBLIC
557
Note
If you encounter issues with the OData service CUAN_BUSINESS_PARTNER_IMP_SRV, create a support ticket under component CEC-MKT-DM-IC (Interaction Contacts).
The component is not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408].
Extensibility
All custom fields registered with the Custom Fields app will automatically appear in the OData service. It is not necessary to enable the usage for a specific field for that OData service. The entity Company has the following business contexts assigned: Marketing: Corporate Account and Marketing: Contact and Corporate Account. The entity Person has the following business context assigned: Context Marketing: Contact and Marketing: Contact and Corporate Account. The entity Relationship is not extensible.
Parent topic: Business Partners from SAP Cloud for Customer [page 555]
Related Information
Overview [page 555] Technical Prerequisites [page 556] Structure of OData Service CUAN_BUSINESS_PARTNER_IMP_SRV [page 558] Payload Examples for CUAN_BUSINESS_PARTNER_IMP_SRV [page 566]
5.2.4.4 Structure of OData Service CUAN_BUSINESS_PARTNER_IMP_SRV
The CUAN_BUSINESS_PARTNER_IMP_SRV OData service consists of the following entity sets and entity types:
Entity Set ImportHeaders Companies
Entity Type ImportHeader Company
Entity Description Technical Import Message Header Company
558
PUBLIC
Integration Guide Integration APIs
Entity Set Persons Relationships
Facets MarketingAreas
Entity Type Person Relationship
Facet MarketingArea
Entity Description Person Relationship (from contact person to corporate account) Facet Marketing Area
The metadata structure of the service is read by means of the OData call:
Request URI: https://<server>:<port> /sap/opu/odata/sap/ CUAN_BUSINESS_PARTNER_IMP_SRV/$metadata
HTTP Method: GET
Parent topic: Business Partners from SAP Cloud for Customer [page 555]
Related Information
Overview [page 555] Technical Prerequisites [page 556] Basic Concepts [page 556] Payload Examples for CUAN_BUSINESS_PARTNER_IMP_SRV [page 566]
5.2.4.4.1 ImportHeader
The entity type ImportHeader describes the technical header of an import of multiple business partners. The properties Id and Timestamp are used for logging the external data request. If an error occurs during the posting of the business partner, in addition to the import header data the error message and the failed record are saved. This data can be checked with the Import Monitor app. For more information, see Import Monitor [page 404].
For every service request, a new, unique ID is required. If no ID value is provided it is defaulted internally. In the Import Monitor app, the ID is used as search field and the status of the import is shown for the request. If no timestamps is provided it is defaulted to the time of import processing. If the timestamp is provided it is stored at the import header and displayed in the Import Monitor as date/time of the import notification.
The SourceSystemId and SourceSystemType property allows you to distinguish between different source systems. The SourceSystemId and SourceSystemType are mandatory attributes.
Integration Guide Integration APIs
PUBLIC
559
Property
Description
Edm Core Type Max Length
Mandatory
Key
Id
Unique technical Edm.String
32
X
X
identifier of import
run.
Timestamp
Timestamp of the Edm.DateTime
0
run in the format:
number of milli
seconds since
midnight Jan 1,
1970. For exam
ple: /
Date(14060141409
22)/
SourceSystem Type of the source Edm.String
20
X
Type
system, such as
C4C
SourceSystemId Identifier of the
Edm.String
20
X
source system
5.2.4.4.2 Company
The entity type Company contains all attributes that are required to create a corporate account with its main origin data. The ID of the company has to be provided by the external source system to perform later updates.
This entity is used in standard SAP Marketing Cloud integration with SAP Cloud for Customer for replicating accounts.
Property Id
IdOrigin
Description
Edm Core Type Max Length
Mandatory
Key
Id of the Company Edm.String
100
X
X
in the external sys
tem
Origin or source of Edm.String
20
X
X
ID of companies
from external sys
tems
560
PUBLIC
Integration Guide Integration APIs
Property
Description
Edm Core Type Max Length
Mandatory
Key
InternalId
ID of the company Edm.String
100
X
on SAP Marketing
Cloud integration
with SAP Cloud for
Customer
LastChangeDate Timestamp
Edm.DateTime
0
X
Format: number of milliseconds since midnight Jan 1, 1970. For exam ple: / Date(14060141409 22)/
CompanyName Company Name Edm.String
80
CountryCode
Country Code
Edm.String
3
RegionCode
Region Code
Edm.String
3
CityName
City Name as part Edm.String
40
of the postal ad
dress
PostalCode
Postal Code
Edm.String
10
Street
Street as part of Edm.String
60
postal address
HouseNumber
House number as Edm.String
10
part of postal ad
dress
EmailAddress
E-mail Address
Edm.String
241
PhoneNumber
Phone number for Edm.String
30
mobile
Format: +country code region code + phone number, su cha as +49151123456
Integration Guide Integration APIs
PUBLIC
561
Property
Description
Edm Core Type Max Length
Mandatory
Key
FaxNumber
Fax number
Edm.String
30
Format: +country code region code + fax number suuch as +49 6227 123456
WebSite
Web URI
Edm.String
1.000
IndustryCode
Industry Code
Edm.String
4
LanguageCode
Preferred commu Edm.String
2
nication Language
Code
MobileNumber
Mobile Number Edm.String
30
Latitude
Latitude
Edm.Decimal
10
(prec. 20; scale)
Longitude
Longitude
Edm.Decimal
10
(prec. 20; scale)
SpatialReference Spatial Reference Edm.String
30
System
System
5.2.4.4.3 Person
This entity is used in standard SAP Marketing Cloud integration with SAP Cloud for Customer for replicating contacts and individual customers.
Property ID
IdOrigin
Description
Edm Core Type Max Length
Mandatory
Key
ID of the person in Edm.String
100
X
X
the external sys
tem
Origin or source of Edm.String
20
X
X
ID of person from
external systems
562
PUBLIC
Integration Guide Integration APIs
Property
Description
Edm Core Type Max Length
Mandatory
Key
InternalID
ID of the person in Edm.String
100
X
SAP Marketing
Cloud integration
with SAP Cloud for
Customer
LastChangeDate Obsolete must be Edm.DateTime
0
X
filled for compati
bility reasons
FirstName
First Name
Edm.String
40
LastName
Last Name
Edm.String
40
FullName DateOfBirth GenderCode
Full Name Date of Birth Gender Code
Edm.String
80
Edm.DateTime
0
Edm.String
1
MaritalStatusCode Marital Status
Edm.String
1
Code
TitleCode
Title Code
Edm.String
4
WebSite
Web URI
Edm.String
1.000
IsConsumer
Person is Con
Edm.Boolean
0
sumer
IsContact
Person is Contact Edm.Boolean
0
LanguageCode
Preferred Lan
Edm.String
2
guage
PostalCode
Postal Code as
Edm.String
10
part of the ad
dress; only rele
vant for consumer
Street
Street as part of Edm.String
60
the address; only
relevant for con
sumer
HouseNumber
House Number as Edm.String
10
part of the ad
dress; only rele
vant for consumer
Integration Guide Integration APIs
PUBLIC
563
Property
Description
Edm Core Type Max Length
Mandatory
Key
EmailAddress
Email Address;
Edm.String
241
only relevant for
consumer
PhoneNumber
Phone Number; Edm.String
30
only relevant for
consumer
MobilePhoneNum Mobile Phone
Edm.String
30
ber
Number; only rele
vant for consumer
FaxNumber
Fax Number; only Edm.String
30
relevant for con
sumer
MobileNumber
Mobile Number Edm.String
30
Latitude
Latitude
Edm.Decimal
10
(prec. 20; scale)
Longitude
Longitude
Edm.Decimal
10
(prec. 20; scale)
SpatialReference Spatial Reference Edm.String
30
System
System
5.2.4.4.4 Relationship
This entity is used in standard SAP Marketing Cloud integration with SAP Cloud for Customer for replicating Is Contact Person for relationships. The relationship type has to be provided. The relationship is directed from a contact person to a corporate account.
It is possible to create or to delete a relationship by providing the corresponding ActionCode.
Property IdFrom
IdTo
Description
Edm Core Type Max Length
Mandatory
Key
External ID of con Edm.String
100
X
X
tact person
External ID of cor Edm.String
100
X
X
porate account
564
PUBLIC
Integration Guide Integration APIs
Property
Description
Edm Core Type Max Length
Mandatory
Key
IdOrigin
Origin or source of Edm.String
20
X
X
ID of From and To
Business Partner
InternalIdFrom
ID of the contact Edm.String
100
person in SAP
Marketing Cloud
InternalIdTo
ID of the corporate Edm.String
100
account in SAP
Marketing Cloud
RelationType
Type of the rela Edm.String
2
X
tionship
ActionCode
The action code Edm.String
1
X
controls how the
relationship is to
be processed in
the backend:
1. Create/ Change
2. Delete
LastChangeDate Timestamp of the Edm.DateTime
0
external object.
Timestamp is used
to process mes
sages in the right
sequence
EmailAddress
Business Email
Edm.String
241
Address of contact
person
PhoneNumber
Business Phone Edm.String
30
Number
MobilePhoneNum Business Mobile Edm.String
30
ber
Phone Number
FaxNumber
Business Fax
Edm.String
30
Number
DepartmentCode Department
Edm.String
4
FunctionCode
Function
Edm.String
4
Integration Guide Integration APIs
PUBLIC
565
Property IsMain
Description
Edm Core Type Max Length
Mandatory
Key
Is main Contact Edm.Boolean
5.2.4.4.5 Facet
Facets can be used to import additional external IDs of a company or a person.
If the facets are used to import those IDs the additional IDs have to be provided in the entity Relationship for consistency reasons. For more information, see section Update Behavior in Basic Concepts [page 556].
Property Id
Origin
Description
Edm Core Type Max Length
Mandatory
Key
ID from the exter Edm.String
10
X
X
nal system
Origin of ID from Edm.String
30
X
X
external system
5.2.4.4.6 Marketing Area
Entity Marketing Area can be used to import marketing area assignments for a person or a company.
Property
Description
Edm Core Type Max Length
Mandatory
Key
MarketingAreaId ID of the Marketing Edm.String
40
X
X
Area
5.2.4.5 Payload Examples for CUAN_BUSINESS_PARTNER_IMP_SRV
This section contains payload examples for replicating business partners from SAP Cloud for Customer to marketing with the OData service CUAN_BUSINESS_PARTNER_IMP_SRV.
Parent topic: Business Partners from SAP Cloud for Customer [page 555]
566
PUBLIC
Integration Guide Integration APIs
Related Information
Overview [page 555] Technical Prerequisites [page 556] Basic Concepts [page 556] Structure of OData Service CUAN_BUSINESS_PARTNER_IMP_SRV [page 558]
5.2.4.5.1 Importing Company Data
All attributes of entity Company are relevant for updating a company including all extension fields of business context Marketing: Corporate Account and Marketing: Contact and Corporate Account.
The following code snippet shows an example in JSON format of how to import two corporate accounts, one of them with an additional ERP ID: Request URI:
/sap/opu/odata/sap/CUAN_BUSINESS_PARTNER_IMP_SRV/ImportHeaders HTTP Method: POST
Sample Code
{ "Id":"", "Timestamp":"2016-05-04T14:07:21.6779610", "SourceSystemType":"C4C", "SourceSystemId":"CLOUDFORCUSTOMER", "Companies":[ { "Id": "123456789", "IdOrigin": "SAP_C4C_BUPA", "LastChangeDate": "2016-05-04T14:07:21.6779610", "CompanyName": "SAP Deutschland SE & Co. KG", "CountryCode": "DE", "RegionCode": "BW", "CityName": "Walldorf", "PostalCode": "69190", "Street": "Hasso-Plattner-Ring", "HouseNumber": "7", "EmailAddress": "info.germany@sap.com", "PhoneNumber": "+496227747474", "FaxNumber": "+496227757575", "WebSite": "www.sap.com/germany", "IndustryCode": "63", "LanguageCode": "DE", "Facets": [ { "Id": "123456789", "IdOrigin": "SAP_ERP_BUPA" } ] }, { "Id": "923456789", "IdOrigin": "SAP_C4C_BUPA", "LastChangeDate": "2016-05-04T14:07:21.6779610", "CompanyName": "OtherCompany",
Integration Guide Integration APIs
PUBLIC
567
} ] }
"CountryCode": "DE", "RegionCode": "BW"
During the import of companies, the system determines whether there are relationships to that corporate account. If there are contact persons with an Is Contact Person relation to that account the corporate account's postal address (street, house number, postal code, city name, region code, country) is copied to all active contact persons. After the import of the corporate account, all contact persons of that account have the same postal address.
5.2.4.5.2 Importing Person Data
During the import of persons via the OData service CUAN_BUSINESS_PARTNER_IMP_SRV, a person can be either a consumer (B2C process) or a contact person (B2B process).
A consumer is a natural person who generates sales revenue (IS_CONSUMER = X). A contact person is a natural person a company interacts in a B2B process (IS_CONTACT = X) with, and
which usually has an Is Contact Person relationship to a corporate account. A contact person has workplace-related information, such as function, department or workplace communication data (phone, email, fax etc). A contact person's postal address is derived from the related company's postal address.
Dependent on the attribute IsConsumer or IsContact, a different set of attributes is used for updating the interaction contact. A contact person may only have the related company's postal address. That is why importing a postal address for a person marked as IsContact is not possible, and if attributes are provided they are ignored during import.
The following table provides you with attributes that are relevant for updating a consumer or contact person.
568
PUBLIC
Integration Guide Integration APIs
Person (consumer)
Id IdOrigin InternalId LastChangeDate FirstName LastName FullName DateOfBirth GenderCode MaritalStatusCode TitleCode CountryCode RegionCode CityName PostalCode Street HouseNumber EmailAddress PhoneNumber MobilePhoneNumber FaxNumber WebSite IsConsumer LanguageCode Customer extension fields for Business Context
Marketing: Contact and Marketing: Contact and Corporate Account
Integration Guide Integration APIs
PUBLIC
569
Person (Contact Person)
Id IdOrigin InternalId LastChangeDate FirstName LastName FullName DateOfBirth GenderCode MartialStatusCode TitleCode WebSite IsContact LanguageCode Customer extension fields for Business Context
Marketing: Contact and Marketing: Contact and Corporate Account
5.2.4.5.2.1 Consumer
The following code snippet shows an example in JSON format of how to import a consumer with an additional ERP ID:
Request URI: /sap/opu/odata/sap/CUAN_BUSINESS_PARTNER_IMP_SRV/ImportHeaders
HTTP Method: POST
Sample Code
{
"Id":
"",
"Timestamp":
"2016-05-04T14:07:21.6779610",
"SourceSystemType": "C4C",
"SourceSystemId": "CLOUDFORCUSTOMER",
"Persons": [
{
"Id": "223456789",
"IdOrigin": "SAP_C4C_BUPA",
"LastChangeDate": "2016-05-04T14:07:21.6779610",
"FirstName": "Erika",
"LastName": "Mustermann",
"FullName": "Erika Mustermann",
"GenderCode": "2",
"MaritalStatusCode": "1",
"CountryCode": "DE",
"RegionCode": "BW",
"CityName": "Walldorf",
"PostalCode": "69190",
"Street": "Bahnhofstraße",
"HouseNumber": "1",
"EmailAddress": "erika.mustermann@privat.de",
570
PUBLIC
Integration Guide Integration APIs
"LanguageCode": "DE", "MobilePhoneNumber": "49119201412192", "PhoneNumber": "49119201412191", "TitleCode": "0001", "IsConsumer": true, "Facets": [{
"Id": "223456789", "IdOrigin": "SAP_ERP_BUPA" }] } ] } As a result of this sample request, a consumer will be created with the provided attributes.
5.2.4.5.2.2 Contact Person
The following code snippet shows an example in JSON format of how to import a contact person with additional ERP ID:
Request URI: /sap/opu/odata/sap/CUAN_BUSINESS_PARTNER_IMP_SRV/ImportHeaders
HTTP Method: POST
Sample Code
{
"Id":
"",
"Timestamp":
"2016-05-04T14:07:21.6779610",
"SourceSystemType": "C4C",
"SourceSystemId": "CLOUDFORCUSTOMER",
"Persons": [
{
"Id": "323456789",
"IdOrigin": "SAP_C4C_BUPA",
"LastChangeDate": "2016-05-04T14:07:21.6779610",
"FirstName": "Heinz",
"LastName": "Müller",
"FullName": "Heinz Müller",
"GenderCode": "1",
"MaritalStatusCode": "2",
"TitleCode": "0002",
"DateOfBirth": "1978-05-12T00:00:00.0000000",
"IsContact": true,
"LanguageCode": "DE",
"Facets": [{
"Id": "323456789",
"IdOrigin": "SAP_ERP_BUPA"
}]
}
]
}
The result of this sample request depends on the data already in the system.
If the contact person is created with this sample request or if the contact person of the request does not exist in the system, the contact person will be created and the contact person will only contain the attributes listed in the request.
Integration Guide Integration APIs
PUBLIC
571
If the contact person already has a relationship to an account the contact person will additionally have the following attributes: The corporate account's postal address All attributes provided with the relationship request
5.2.4.5.3 Importing Relationship Data
5.2.4.5.3.1 Create or Change Relationship
The following code snippet shows an example in JSON format of how to import a relationship between a company and a contact with an additional ERP ID. The contact person's additional IDs are transferred via the entity FromFacets:
Request URI: /sap/opu/odata/sap/CUAN_BUSINESS_PARTNER_IMP_SRV/ImportHeaders
HTTP Method: POST
Sample Code
{
"Id":
"",
"Timestamp":
"2016-05-04T14:07:21.6779610",
"SourceSystemType": "C4C",
"SourceSystemId": "CLOUDFORCUSTOMER",
"Relationships": [
{
"IdOrigin": "SAP_C4C_BUPA",
"IdFrom": "323456789",
"IdTo": "123456789",
"RelationType": "01",
"ActionCode": "1",
"LastChangeDate": "2016-05-04T14:07:21.6779610",
"FunctionCode": "08",
"DepartmentCode": "0024",
"PhoneNumber": "+496227712345",
"FaxNumber": "+4962277612345",
"EmailAddress": "heinz.mueller@sap.com",
"FunctionCode": "08",
"DepartmentCode": "0025",
"IsMain": false,
"FromFacets": [
{
"Id": "323456789",
"IdOrigin": "SAP_ERP_BUPA"
}
]
}
]
}
572
PUBLIC
Integration Guide Integration APIs
The result of that request depends on the data already in the system:
If the contact person is created with this sample request the contact person will contain only the attributes listed in the request and will have no name, title, date of birth, and so on. If the related company has a postal address the contact person will also have that postal address.
If the company of that sample request does not exist the request will not be saved but forwarded to the Import Monitor app. The request will be automatically reprocessed until the company is successfully imported into the system. Usually, a source system will only allow a relationship to be created if the referenced business partner has been created, so the relationship might reach SAP Marketing Cloud before the corresponding master data requests.
If the contact person is already in the system and a relationship to a company with postal address exists the contact person will have the attributes sent with the relationship request, the company's postal address and the contact person's master data.
5.2.4.5.3.2 Delete Relationship
The following code snippet shows an example in JSON format of how to delete an existing relationship between a company and a contact:
Request URI: /sap/opu/odata/sap/CUAN_BUSINESS_PARTNER_IMP_SRV/ImportHeaders
- HTTP Method: POST
Sample Code
{
"Id":
"",
"Timestamp":
"2017-08-10T14:07:21.6779610",
"SourceSystemType": "C4C",
"SourceSystemId": "CLOUDFORCUSTOMER",
"Relationships": [
{
"IdOrigin" : "SAP_C4C_BUPA",
"IdFrom" : "323456789",
"IdTo" : "123456789",
"RelationType" : "01",
"ActionCode" : "2",
"LastChangeDate" : "2017-08-10T14:07:21.6779610"
}
]
}
As a result of this request, the contact person's relationship to the company is deleted. Along with that, the following business related attributes are cleared:
Postal Address Communication data (phone, email, fax, mobile) Function, department
Integration Guide Integration APIs
PUBLIC
573
5.2.5 Import Business Partners
CUAN_BUSINESS_PARTNER_IMPORT_SRV for importing business partner data from external source systems, like, for example, SAP ERP, SAP CRM, SAP S/4HANA On Premise.
OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV is used for standard SAP Marketing Cloud integration. It is used in marketing-driven and sales-driven processes to replicate data from SAP ERP, SAP CRM, or SAP S/4HANA On Premise to SAP Marketing Cloud interaction contacts.
For more information about the integration scenario, see Integration with SAP ERP [page 349] and Order Management Data Replication to SAP Marketing Cloud [page 348].
For more information about external interfaces that SAP Marketing Cloud provides for creating or updating interaction contacts, interactions, interests, corporate accounts, product categories, and products, see Integration APIs [page 387].
OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV can also be used to create SAP Marketing Cloud interaction contacts from any source system. The OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV supports the change of interaction contacts. Each interaction contact is identified by the key of the business partner in the external system.
Note
If you encounter issues with the OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV, create a support ticket under component CEC-MKT-DM-IC (Interaction Contacts).
The component is not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408].
5.2.5.1 Technical Prerequisites
OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV is available as part of the standard integration with SAP ERP, SAP S/4HANA Cloud, and SAP S/4HANA On Premise.
5.2.5.2 Basic Concepts
OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV supports only batch processing. Within a batch request only the operation PATCH (MERGE) on the entity type InteractionContact, or the operation POST on the entity type MarketingAttribute, or the function import DeleteMarketingAttributes are supported. Other operations, such as update or read are not supported.
Batch requests allow grouping multiple operations into a single HTTP request payload.
Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service as described in OData URI . The batch request must contain a content-type header specifying a content type of multipart/mixed and a boundary specification.
574
PUBLIC
Integration Guide Integration APIs
A PATCH (MERGE) request updates only the properties indicated in the request body and leaves everything untouched that was not mentioned.
All properties that are not to be changed, can be omitted. The transmitted properties are merged with the data already stored in SAP Marketing Cloud.
Any processing errors are recorded in the SAP Marketing Cloud system in the Import Monitor app, where they can be monitored, restarted and discarded.
Note
If you encounter issues with the OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV, create a support ticket under component CEC-MKT-DM-IC (Interaction Contacts).
The component is not to be used for HTTP errors. For example, if the OData service is accepted by the gateway component in the SAP Marketing Cloud system, the HTTP status code 201 or 202 is returned. For more information, see HTTP Response Status Codes [page 408].
5.2.5.3 Structure of OData Service CUAN_BUSINESS_PARTNER_IMPORT_SRV
The CUAN_BUSINESS_PARTNER_IMPORT_SRV OData service consists of the following entity sets and entity types:
Entity Set InteractionContacts
Entity Type InteractionContact
MarketingAttributes MarketingAreas
MarketingAttribute MarketingArea
Entity Type Description
Interaction contacts refer to contacts in SAP Marketing Cloud. Interaction Con tact is a generic term to group all natu ral persons (contacts, consumers, or suspects), companies and "unknowns", who interact with your company. Con tact data is collected and merged from several sources into the master data ta bles within SAP Marketing Cloud. We distinguish between contacts, consum ers and suspects to define the business relationship of a contact to a company.
Marketing attributes are assigned to an interaction contact. The marketing at tribute category can be defined per source of the contact data.
Use marketing areas as organizational units and to determine which interac tion contacts a user can access.
Integration Guide Integration APIs
PUBLIC
575
The OData service CUAN_BUSINESS_PARTNER_IMPORT_SRV supports OData batch processing. Interaction contact data can be transferred by the OData PATCH (MERGE) operation for entity type InteractionContact.
Marketing attributes can be transferred by the OData POST operation on the entity typeInteractionContact via the navigation parameter MarketingAttributes. Any operation on the MarketingAttributes entity set without navigation from the InteractionContact is not supported.
It is expected that all marketing attributes of an interaction contact are transferred via one change set within the batch request. The transmitted marketing attributes overwrite the existing entries imported from the same source.
The deletion of the marketing attributes of an interaction contact can be done via the OData function import DeleteMarketingAttributes.
Marketing areas can be transferred by the OData POST operation on the entity type InteractionContact via the navigation parameter MarketingAreas. The marketing area of the interaction contact can be deleted by the OData DELETE operation on the entity type MarketingArea.
Request Header
The request header contains the following additional header fields:
Header Field
Description
Edm Core Type
Sap-CuanSequenceId
Unique technical iden tifier of the imported data.
Edm.String
Sap-CuanRequestTimestamp
Timestamp of the data Edm.DateTime
Sap-CuanSequenceNumber
Sap-CuanSourceSystemType Sap-CuanSourceSystemId
Sequence number of the request. This num ber is normally incre mented each time a new request for the same sequence id is created.
Edm.Int16
Type of the source sys Edm.String tem
Identifier of the source system. This is a free text field.
Edm.String
Max Length 30 0 0
20 255
Mandatory X * *
X X
576
PUBLIC
Integration Guide Integration APIs
Header Field
Description
Edm Core Type
Sap-CuanExternalReference Id
External reference of the inbound message
Sap-CuanExternalDocumentI d
External identifier of the source document
Edm.String Edm.String
Max Length 32
20
Mandatory
The header fields Sap-Cuan-SequenceId and Sap-Cuan-RequestTimestamp or Sap-CuanSequenceNumber are used to check the sequence of the received data. Data with a timestamp older or sequence number lower than data already imported, is ignored. Data with the same Sap-Cuan SequenceID is also ignored.
The Sap-Cuan-SourceSystemType and Sap-Cuan-SourceSystemId fields allow you to distinguish between different source systems.
*Either Sap-Cuan-RequestTimestamp or Sap-Cuan-SequenceNumber must be provided together with Sap-Cuan-SequenceId.
The Sap-Cuan-ExternalReferenceId and Sap-Cuan-ExternalDocumentId allow better error analysis because they contain external references to a source SOAP message and/or an IDoc.
InteractionContact
Only the properties Id and IdOrigin are mandatory. All properties that are not to be changed can be omitted.
Property
Description
Edm Core Type Max Length
Mandatory
Key
Id
ID of Interaction Edm.String
255
x
x
Contact
IdOrigin
Origin of Interac Edm.String
20
x
x
tion Contact
IsEndOfPurpose End of Purpose
Edm.Boolean
0
Blocked
Reached
Name
Full Name
Edm.String
80
FirstName
First Name
Edm.String
40
LastName
Last Name
Edm.String
40
TitleCode
Title Code
Edm.String
4
CountryCode
Country Code
Edm.String
3
RegionCode
Region Code
Edm.String
3
Integration Guide Integration APIs
PUBLIC
577
Property
Description
Edm Core Type Max Length
Mandatory
Key
City
City
Edm.String
40
PostalCode
Postal Code
Edm.String
10
Street
Street
Edm.String
60
HouseNumber
House Number
Edm.String
10
LanguageCode
Language Code
Edm.String
2
GenderCode
The following fixed Edm.String
1
values are sup
ported:
1 - Male 2 - Female 3 - Non-binary 9 - Not speci
fied
MaritalStatusC Marital Status
Edm.String
1
ode
Code
IndustryCode
Industry Code
Edm.String
4
DepartmentCode Department Code Edm.String
4
FunctionCode
Function Code
Edm.String
4
EmailAddress
E-Mail Address
Edm.String
241
PhoneNumber
Phone Number
Edm.String
30
MobilePhoneNum Mobile Phone
Edm.String
30
ber
Number
FaxNumber
Fax Number
Edm.String
30
DateOfBirth
Date of Birth
Edm.DateTime
0
IsContact
Indicates whether Edm.Boolean
0
person acts as
contact for an ac
count
IsMainContact
Indicates a person Edm.Boolean
0
that acts as a main
contact for an ac
count
578
PUBLIC
Integration Guide Integration APIs
Property
Description
Edm Core Type Max Length
Mandatory
Key
IsConsumer
Indicates whether Edm.Boolean
0
person is a con
sumer
Obsolete
Obsolete
Edm.Boolean
0
WebUri
Web Site
Edm.String
1.000
Latitude
Latitude
Edm.Decimal
0
Longitude
Longitude
Edm.Decimal
0
IcType
Interaction Con Edm.String
2
tact Type: 01 per
son
02 company
CompanyId
ID of Company
Edm.String
255
CompanyIdOrigi Origin of Company Edm.String
20
n
MatchId
ID of matched En Edm.String
255
tity
MatchIdOrigin Origin of matched Edm.String
20
Entity
The property IdOrigin indicates the source of the Id. It is maintained in the Self-Service Configuration app Define Origins of Contact ID. To replicate SAP ERP data to SAP Marketing Cloud, interaction contacts origin SAP_ERP_CONTACT or SAP_ERP_CUSTOMER is used. To replicate SAP S/4HANA data to SAP Marketing Cloud, SAP_S4_BUPA, an additional facet for customer SAP_S4_CUSTOMER, for contact SAP_S4_CONTACT is used.
CompanyId and CompanyIdOrigin are used to create a relationship between a contact and a company.
MatchId and MatchIdOrigin are used to associate an interaction contact to data already created with different Id and IdOrigin in SAP Marketing Cloud, for example data transmitted from a different source system.
An interaction contact can be classified as contact (property: IsContact = true) for persons acting as contact for an account (B2B), and as a consumer (property: IsConsumer = true) that acts as an account (B2C). A person can be both a contact and a consumer at the same time.
Interaction contacts that are marked as Obsolete or IsEndOfPurposeBlocked are not visible and cannot be used in business processes. The Obsolete indicator can be removed. Setting the IsEndOfPurposeBlocked indicator is permanent.
Integration Guide Integration APIs
PUBLIC
579
Marketing Attributes
Marketing attributes can be created only via the navigation property MarketingAttributes of the InteractionContact entity type.
Property
Description
Edm Core Type Max Length
Mandatory
Key
CategoryId
ID of Marketing
Edm.String
75
x
x
Category
Value
Value of Marketing Edm.String
255
x
x
Attribute
Transferring Marketing Attributes
Marketing attributes and their assignments to business partners are transferred from a source system, for example SAP S/4HANA Enterprise, to SAP Marketing Cloud in two steps, as described in the following table:
Transfer of Marketing Attributes
Transfer of
From
To SAP Marketing Cloud
Master Data
Marketing Attribute Sets Marketing Attributes
Marketing Attribute Categories
For more information, see Marketing Attribute Categories [page 735].
Business Partner Assignments
Marketing Attributes Sets, including: Marketing Attribute Values
Marketing Attribute Values Marketing Attribute Value Descrip
tions
Integration
In Marketing, marketing attributes categories and marketing attribute values are visible in Personal Data of contacts, accounts, or individual customers. Marketing attribute categories, and marketing attribute values can be used in segmentation.
Note
Marketing attribute categories always have a text in the system language. If no text is transferred from the source system, the marketing system automatically creates a text in the system language from the ID.
Ensure that all attributes in the source system are named differently. Attributes with the same name cause an error that can be monitored in the Import Monitor [page 404].
To prevent from overwriting attribute values, do not use the same attribute in different attribute sets in the source system.
Changes of master data and business partner assignments in the source system are automatically transferred to Marketing.
580
PUBLIC
Integration Guide Integration APIs
MarketingArea
Marketing areas can be assigned to the interaction contact via the navigation property MarketingAreas of the InteractionContact entity type. The marketing area assigned to the interaction contact can be deleted by the OData DELETE operation on the entity type MarketingArea.
Property
Description
Edm Core Type Max Length
Mandatory
Key
Id
ID of Interaction Edm.String
255
x
x
Contact
IdOrigin
Origin of Interac Edm.String
20
x
x
tion Contact
MarketingAreaId ID of Marketing
Edm.String
40
x
x
Area
Function Imports
Function import DeleteMarketingAttributescan be used to delete all marketing attributes of an interaction contact.
Property Id
IdOrigin
Description
Edm Core Type Max Length
Mandatory
Key
ID of Interaction Edm. String
255
x
x
Contact
Origin of Interac Edm. String
20
x
x
tion Contact
5.2.5.4 Field Extensibility
In addition to the pre-delivered attributes, you can add customer-specific fields using the Custom Fields app. For more information about how to do this, see Custom Fields.
New fields can be added for the following BusinessContexts:
Marketing: Interaction Contact Marketing Attributes for Contacts Marketing: Person Marketing: Company
If the field is added to the BusinessContexts Person or Company, the respective IcType (01 for Person and 02 for Company) must be filled in the payload of new interaction contacts.
Integration Guide Integration APIs
PUBLIC
581
5.2.6 Products
Public OData API (API_MKT_PRODUCT_SRV) for Products.
Overview
The OData service API_MKT_PRODUCT_SRV is used for standard SAP Marketing Cloud integration with other systems. It is used in marketing-driven and sales-driven processes to replicate product data to SAP Marketing Cloud.
For more information about the integration scenario, see SAP Marketing Cloud , Integration with SAP ERP [page 349]
For more information about external interfaces that SAP Marketing Cloud provides for creating or updating interaction contacts, interactions, interests, corporate accounts, product categories, and products, see Integration APIs [page 387].
OData service API_MKT_PRODUCT_SRV can be used to create SAP Marketing Cloud products from any source system. OData service API_MKT_PRODUCT_SRV supports the change of products. Each product is identified by the key of the product in the external system.
Technical Data
OData Version Root URI Service Metadata URI Authorizations
Communication Scenario ID Component for Incidents
Field Extensibility Supported
2.0 https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_PRODUCT_SRV;v=0002 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_PRODUCT_SRV;v=0002/$metadata
The following business catalog is required: SAP_CEC_BC_MKT_API_PRD2_PC SAP_COM_0171 CEC-MKT-DM-PRO (Products and Product Categories)
Note
Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408].
Yes
582
PUBLIC
Integration Guide Integration APIs
Technical Field Documentation
You can access detailed technical documentation for the API fields by downloading a metadata file in one of the following ways:
Access Link
Remarks
https:// <Server>:<Port>/sap/opu/ odata/SAP/API_MKT_PRODUCT_SRV/ $metadata?sapdocumentation=all
Only for internal access. You need to provide the server and port names.
Marketing - Product Details Page
General access to the Details page of the service on SAP API Hub. One-time regis tration is required for first-time users.
1. On the Details page, click Download Specification and download as EDMX. 2. Specify which application you want to use to open the EDMX file type.
Products (Metadata)
General access link takes you directly to the Product metadata file. One-time reg istration or logon is required.
Note
You can convert the XML file to an XML table to make it easier to read.
Please note the meaning of the following values in the file:
Metadata Value in XML sap:updatable sap:creatable nullable
Meaning When FALSE read-only field read-only field mandatory field
Basic Concepts [page 583]
Structure of OData Service API_MKT_PRODUCT_SRV [page 585]
Payload Examples for Products [page 591] Demonstrates creation and merge of products.
Extensibility for Products [page 602]
Function Imports [page 603] Function imports are used to perform custom operations on an entity, which are typically not provided by OData operations.
5.2.6.1 Basic Concepts
OData service API_MKT_PRODUCT_SRV supports only batch processing for updates. Batch requests allow grouping multiple operations into a single HTTP request payload.
Integration Guide Integration APIs
PUBLIC
583
Note
For generally applicable recommendations and best practices, make sure you refer to the section Best Practices and Recommended Package Sizes [page 400].
Within a batch request, the following operations are supported: GET is supported for all entities. PATCH (MERGE) on the entity type ProductOriginData POST on the entity types ProductCategoryAssignment and ProductName DELETE on the entity type ProductCategoryAssignment DELETE on the entity type MarketingArea and the function IMPORT for ProductOriginData Other operations, such as CREATE or UPDATE are not supported. Operation DELETE is only supported for entity type ProductCategoryAssignment. Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service as described in [OData-URI ]. The batch request must contain a content-type header specifying a content type of multipart/mixed and a boundary specification. A PATCH (MERGE) request updates only the properties indicated in the request body and leaves everything untouched thast was not mentioned. All properties that are not to be changed, can be omitted. The transmitted properties are merged with the data already stored in SAP Marketing Cloud. If the OData service is not accessible, for example due to missing authorization, or because the system is not available, a corresponding HTTP status code is returned. If the OData service is accepted by the gateway component in the SAP Marketing Cloud system, the HTTP status code 201 or 204 is returned. Potential processing errors are recorded in the SAP Marketing Cloud system in the Import Monitor app, where they can be monitored, restarted and discarded.
Parent topic: Products [page 582]
Related Information
Structure of OData Service API_MKT_PRODUCT_SRV [page 585] Payload Examples for Products [page 591] Extensibility for Products [page 602] Function Imports [page 603]
584
PUBLIC
Integration Guide Integration APIs
5.2.6.2 Structure of OData Service API_MKT_PRODUCT_SRV
The API_MKT_PRODUCT_SRV OData service consists of the following entity sets and entity types:
Entity Set Products ProductOriginDataSet
ProductCategoryAssignments ProductNames ProductOriginDataNames AdditionalIDs
MarketingAreas
Entity Type
Entity Type Description
Product
The Master Record
ProductOriginData
Product origin data refer to products in SAP Marketing Cloud. Product data is collected and merged from several sources into the master data tables within SAP Marketing Cloud.
ProductCategoryAssignment Product categories are assigned to a product.
ProductName ProductOriginDataName
The product name master record.
Product name and description can be defined per origin of the product data.
AdditionalID
Additional ID of the product from a different prod uct origin.
MarketingArea
Marketing area to which the product is assigned.
The OData service API_MKT_PRODUCT_SRV supports OData batch processing for updates (i.e. insert, change, delete). Product origin data can be transferred by the OData PATCH (MERGE) operation for entity type ProductOriginData.
Product category assignments can be transferred by the OData POST operation on the entity type ProductCategoryAssignment via the navigation parameter ProductCategoryAssignments. A product category assignment can be deleted by the OData DELETE operation on the entity type ProductCategoryAssignment. Any operation on the ProductCategoryAssignments entity set without navigation from the ProductOriginDataSet is not supported. To delete all product category assignments of a special product category hierarchy the function import DeleteProductCategoryAssignments can be used.
Product name and description can be transferred by the OData POST operation on the entity type ProductOriginDataName via the navigation parameter ProductNames. Any operation on the ProductOriginDataNames entity set without navigation from the ProductOriginDataSet is not supported.
Additional ID can be transferred by the OData PATCH (MERGE) operation for the entity type AdditionalID.
The merge of two products from different source systems to one product within yMKT can be done via the OData function import MergeProductOriginData.
The product master record cannot be transferred by the OData POST/PATCH/MERGE operations. The master record is determined automatically based on the product origin data transferred from the source system and can be accessed via the GET operation.
Integration Guide Integration APIs
PUBLIC
585
The product name master record cannot be transferred by the OData POST/PATCH/MERGE operations. The product name master record is determined automatically based on the product origin data names transferred from the source system and can be accessed via the GET operation.
All entities supports the OData GET operation to read the data.
Request Header
The request header contains the following additional header fields:
Header Field
Description
Edm Core Type
Sap-CuanSequenceId
Unique technical iden tifier of the imported data.
Edm.String
Sap-CuanRequestTimestamp
Timestamp of the data Edm.DateTime
Sap-CuanSequenceNumber
Sequence number of the request. This num ber is normally incre mented each time a new request for the same sequence id is created.
Edm.Int16
Sap-CuanSourceSystemType
Type of the source sys Edm.String tem
Sap-CuanSourceSystemId
Identifier of the source system. This is a free text field.
Edm.String
Sap-CuanExternalReference Id
External reference of the inbound message
Edm.String
Sap-CuanExternalDocumentI d
External identifier of the source document
Edm.String
Max Length 30 0 0
20 255 32 20
Mandatory X * *
X X
* Either Sap-Cuan-RequestTimestamp or Sap-Cuan-SequenceNumber must be provided together with Sap-Cuan-SequenceId.
The header fields Sap-Cuan-SequenceId and Sap-Cuan-RequestTimestamp or Sap-CuanSequenceNumber are used to check the sequence of the received data. Data with a timestamp older or sequence number lower than data already imported, is ignored.
The Sap-Cuan-SourceSystemType and Sap-Cuan-SourceSystemId fields allow you to distinguish between different source systems.
586
PUBLIC
Integration Guide Integration APIs
The Sap-Cuan-ExternalReferenceId and Sap-Cuan-ExternalDocumentId allow better error analysis because they contain external references to a source SOAP message and/or an IDoc.
Product
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductUUID
UUID of the Prod Edm.Guid uct
x
x
ProductID
ID of the Product Edm.String
50
ProductOrigin Origin of the Prod Edm.String
30
uct
ProductImageUR Product Image
L
URL
Edm.String
1333
WebsiteURL
Website URL
Edm.String
1333
Brand
Brand ID
Edm.String
50
IsBaseProduct
Indicator: Is Base Product
Edm.Boolean
BaseProductID ID of the Base
Edm.String
50
Product
BaseProductOri Origin of the Base Edm.String
30
gin
Product
ProductValidEn End Date of Prod Edm.DateTime
dDate
uct Validity
ProductOriginData
Only the properties ProductID and ProductOrigin are mandatory. All properties that are not to be changed can be omitted.
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductID
ID of the Product Edm.String
50
x
x
ProductOrigin Origin of the Prod Edm.String
30
x
x
uct
Integration Guide Integration APIs
PUBLIC
587
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductImageUR Product Image
L
URL
Edm.String
1333
WebsiteURL
Website URL
Edm.String
1333
Brand
Brand ID
Edm.String
50
IsBaseProduct
Indicator Is Base Product
Edm.String
BaseProductID ID of the Base
Edm.String
50
Product
BaseProductOri Origin of the Base Edm.String
30
gin
Product
ProductValidEn End Date of Prod Edm.DateTime
dDate
uct Validity
The property ProductOrigin indicates the source of the ProductID. It is maintained in the Self-Service Configuration app Define Origins of ProductID. To replicate SAP ERP data to SAP Marketing Cloud, product origin SAP_ERP_MATNR is used.
The property BaseProductOrigin indicates the source of the BaseProductID. It is maintained in the SelfService Configuration app Define Origins of Product ID .
Only products marked as base product (Indicator IsBaseProduct is True) can be assigned via properties BaseProductID and BaseProductOrigin. This reference can only be provided for products not marked as base product.
Brands can be maintained in the app Brands under Import Data
For the ProductValidEndDate only the date (without time portion) is relevant.
ProductCategoryAssignment
Product category assignment can be created only via the navigation property ProductCategoryAssignments of the ProductOriginData entity type.
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductID
ID of the Product Edm.String
50
x
x
ProductOrigin
Origin of the Prod Edm.String
30
x
x
uct
588
PUBLIC
Integration Guide Integration APIs
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductCategory ID of Product Cat Edm.String
50
x
x
HierarchyID
egory Hierarchy
ProductCategor ID of Product Cat Edm.String
50
x
x
yID
egory
ProductName
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductUUID
UUID of the Prod Edm.Guid uct
x
x
Language
Language code
Edm.String
2
x
x
Name
Product Name
Edm.String
120
ProductDescrip tion
Product Descrit pion
Edm.String
ProductOriginDataName
Product name and description can be created only via the navigation property ProductNames of the ProductOriginData entity type.
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductID
ID of the Product Edm.String
50
x
x
ProductOrigin
Origin of the Prod Edm.String
30
x
x
uct
Language
Language code
Edm.String
2
x
x
Name
Product Name
Edm.String
120
from the source
system
ProductDescrip tion
Product Descrit pion from the source system
Edm.String
Integration Guide Integration APIs
PUBLIC
589
With version 2 ofAPI_MKT_PRODUCT_SRV you can transfer product descriptions that are longer than 512 characters. Only the first 512 characters are considered in the fuzzy search in the "Products Use and Resonance" Fiori App.
AdditionalID
Additional IDs can be attached to the product only via the PATCH/MERGE operation. In case the product with product origin data identified by AdditionalProductOrigin and AdditionalProductID is already known in the system the product will be merged as additional product origin data to the product identified by ProductOrigin and ProductID. The processing is then analogue to the Function Import MergeProductOriginData.
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductOrigin Origin of the Prod Edm.String
30
x
x
uct
ProductID
ID of the Product Edm.String
50
x
x
AdditionalProd Origin of the addi Edm.String
30
x
x
uctOrigin
tional ID of the
Product
AdditionalProd Additional ID of the Edm.String
50
x
x
uctID
Product
MarketingArea
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductOrigin Origin of the Prod Edm.String
30
x
x
uct
ProductID
ID of the Product Edm.String
50
x
x
MktAreaId
Marketing Area of Edm.String
40
x
x
the Product
Parent topic: Products [page 582]
590
PUBLIC
Integration Guide Integration APIs
Related Information
Basic Concepts [page 583] Payload Examples for Products [page 591] Extensibility for Products [page 602] Function Imports [page 603]
5.2.6.3 Payload Examples for Products
Demonstrates creation and merge of products. The following examples show how you can use the products API. Insert your own data to fill the header and the entities.
Create 2 Products: Base Product and Product Variant
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductOriginDataSet(ProductID='CoffeeEspresso',ProductOrigin='SAP_ERP_MATNR')
HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductOrigin":"SAP_ERP_MATNR", "ProductID":"CoffeeEspresso", "WebsiteURL":"https://www.amazon.com/Organic-Espresso-Bean-Coffee-5-Pound/dp/ B002GWHAVM?th=1", "ProductImageURL":"https://images-na.ssl-images-amazon.com/images/I/ 51tbABf6XKL._SX522_.jpg", "Brand":"", "IsBaseProduct":true } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductOriginDataSet(ProductID='CoffeeEspressoDecaf',ProductOrigin='SAP_ERP_MA TNR') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100
Integration Guide Integration APIs
PUBLIC
591
Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductOrigin":"SAP_ERP_MATNR", "ProductID":"CoffeeEspressoDecaf", "WebsiteURL":"https://www.amazon.com/Lavazza-Decaf-Ground-Coffee-Espresso/dp/ B000H6AX0E/ref=pd_sim_325_1? _encoding=UTF8&pd_rd_i=B000H6AX0E&pd_rd_r=JQ5ZE9QB4PEC9J60QHZR&pd_rd_w=QGBTE&p d_rd_wg=uPw2i&refRID=JQ5ZE9QB4PEC9J60QHZR&th=1", "Brand":"", "ProductImageURL":"https://images-na.ssl-images-amazon.com/images/I/91yLlLg %2Be5L._SY679_.jpg", "BaseProductID":"CoffeeEspresso", "BaseProductOrigin":"SAP_ERP_MATNR" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Create Product with 2 Languages
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductOriginDataSet(ProductID='Mocca',ProductOrigin='SAP_ERP_MATNR') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductOrigin":"SAP_ERP_MATNR", "ProductID":"Mocca", "WebsiteURL":"", "ProductImageURL":"", "Brand":"", "ProductValidEndDate":"9999-12-31T00:00:00", "BaseProductID":"", "BaseProductOrigin":"", "ProductValidEndDate":"2029-12-31T00:00:00", "IsBaseProduct":false } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductOriginDataSet(ProductID='Mocca',ProductOrigin='SAP_ERP_MATNR')/ ProductNames HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01
592
PUBLIC
Integration Guide Integration APIs
Sap-Cuan-ExternalReferenceId: 4711 { "Language":"EN", "Name":"Coffee Mocca", "ProductDescription":"Ground Coffee - Caffe Mocca" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductOriginDataSet(ProductID='Mocca',ProductOrigin='SAP_ERP_MATNR')/ ProductNames HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "Language":"DE", "Name":"Kaffee Mokka", "ProductDescription":"Basis Kaffee - Mokka" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Create Product with 2 Product Category Assignments
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductOriginDataSet(ProductID='Mocca',ProductOrigin='SAP_ERP_MATNR') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductOrigin":"SAP_ERP_MATNR", "ProductID":"Mocca", "WebsiteURL":"", "ProductImageURL":"", "Brand":"", "ProductValidEndDate":"9999-12-31T00:00:00", "IsBaseProduct":false } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductOriginDataSet(ProductID='Mocca',ProductOrigin='SAP_ERP_MATNR')/ ProductCategoryAssignments HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100
Integration Guide Integration APIs
PUBLIC
593
Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductCategoryHierarchyID":"Coffee", "ProductCategoryID":"FilterCoffee" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductOriginDataSet(ProductID='Mocca',ProductOrigin='SAP_ERP_MATNR')/ ProductCategoryAssignments HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductCategoryHierarchyID":"Coffee", "ProductCategoryID":"Mocca" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Create 2 Products and Merge into Best Record
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductOriginDataSet(ProductID='Cappuccino',ProductOrigin='SAP_ERP_MATNR') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductOrigin":"SAP_ERP_MATNR", "ProductID":"Cappuccino", "WebsiteURL":"https://www.amazon.com/Organic-Espresso-Bean-Coffee-5-Pound/dp/ B002GWHAVM?th=1", "ProductImageURL":"https://images-na.ssl-images-amazon.com/images/I/ 51tbABf6XKL._SX522_.jpg", "Brand":"", "ProductValidEndDate":"9999-12-31T00:00:00" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductOriginDataSet(ProductID='CoffeeCap1',ProductOrigin='SAP_HYBRIS_PRODUCT' ) HTTP/1.1
594
PUBLIC
Integration Guide Integration APIs
Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductOrigin":"SAP_HYBRIS_PRODUCT", "ProductID":"CoffeeCap1" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST MergeProductOriginData? ProductID='Cappuccino'&ProductOrigin='SAP_ERP_MATNR'&AdditionalProductID='Coff eeCap1'&AdditionalProductOrigin='SAP_HYBRIS_PRODUCT' HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Update Product with Valid End Date
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductOriginDataSet(ProductID='CoffeeEspressoDecaf',ProductOrigin='SAP_ERP_MA TNR') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductOrigin":"SAP_ERP_MATNR", "ProductID":"CoffeeEspressoDecaf", "ProductValidEndDate":"2029-12-31T00:00:00" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
595
Merge 2 Existing Products Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST MergeProductOriginData? ProductID='CoffeeEspresso'&ProductOrigin='SAP_ERP_MATNR'&AdditionalProductID=' 407901109D5FBCF31500B0E4B2FD1696'&AdditionalProductOrigin='SAP_CRM_PRODUCT' HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete Product Category Assignment Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE ProductCategoryAssignments(ProductID='CoffeeEspressoDecaf',ProductOrigin='SAP_ ERP_MATNR',ProductCategoryHierarchyID='Coffee',ProductCategoryID='Espresso') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
596
PUBLIC
Integration Guide Integration APIs
Add Additional ID for Existing Product
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH AdditionalIDs(ProductID='CoffeeEspresso',ProductOrigin='SAP_ERP_MATNR',Additio nalProductOrigin='SAP_C4C_PRODUCT',AdditionalProductID='407901109D5FBCF31500B0 E4B2FD1696') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODUCT Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductOrigin":"SAP_ERP_MATNR", "ProductID":"CoffeeEspresso", "AdditionalProductOrigin":"SAP_C4C_PRODUCT", "AdditionalProductID":"407901109D5FBCF31500B0E4B2FD1696" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete all Product Category Assignments of a Product Category Hierarchy for a Product
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST DeleteProductCategoryAssignments? HierarchyID='Coffee'&ProductID='CoffeeEspressoDecaf'&ProductOrigin='SAP_ERP_MA TNR' HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Integration Guide Integration APIs
PUBLIC
597
Create Products with Marketing Area
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductOriginDataSet(ProductID='JMAT_PROD_API_XX',ProductOrigin='XX')/ MarketingAreaSet HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: JMAT_PRODCATHIER_MASTER_DATA Sap-Cuan-RequestTimestamp: 20210112174358.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320210112174358_01 { "ProductOrigin" : "XX", "ProductId" : "JMAT_PROD_API_XX", "MktAreaId" : "GLOBAL" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Delete a Marketing Area
Sample Code
POST data: --batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE MarketingAreas(ProductOrigin='SAP_ERP_MATNR3',ProductId='XXJMAT_PROD_APIXX',Mk tAreaId='ICMA_DRINK') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: JMAT_XX Sap-Cuan-RequestTimestamp: 20210125110620.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320210125110620_01 { } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
598
PUBLIC
Integration Guide Integration APIs
Post Product Origin Data (Non-Batch) Sample Code
POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_PRODUCT_SRV;v=2/ProductOriginDataSet POST data: { "ProductOrigin":"SAP_ERP_MATNR", "ProductID":"xxx_Product_xxx", "WebsiteURL":"www.test.de", "Brand":"BRAND" }
Post Product Origin Data Name Assignment (Non-Batch) Sample Code
POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_PRODUCT_SRV;v=2/ProductOriginDataNames POST data: { "ProductDescription" : "UI Product", "ProductOrigin" : "SAP_ERP_MATNR", "ProductID" : " xxx_Product_xxx", "Language" : "EN", "Name" : "JMAT_PROD _Name Non Batch Mode" }
Post Product Category Assignment (Non-Batch) Sample Code
POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_PRODUCT_SRV;v=2/MarketingAreas POST data: {"ProductOrigin" : "SAP_ERP_MATNR", "ProductId" : " xxx_Product_xxx", "MktAreaId" : "GLOBAL" }
Delete Product Marketing Area Assignment (Non-Batch) Sample Code
DELETE https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_PRODUCT_SRV;v=2/
Integration Guide Integration APIs
PUBLIC
599
MarketingAreas(ProductOrigin='SAP_ERP_MATNR',ProductId= `xxx_Product_xxx',MktAreaId='GLOBAL')
Delete Product Category Assignment (Non-Batch)
Sample Code
DELETE https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_PRODUCT_SRV;v=2/ ProductCategoryAssignments(ProductID=`xxx_Product_xxx',ProductOrigin='SAP_ERP_ MATNR',ProductCategoryHierarchyID='Prod_Hier_1',ProductCategoryID='Prod_Cat_1' )
GET Requests
Get Product Origin Data Names with specific Product ID and Origin GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV/ ProductOriginDataNames?$filter=ProductOrigin eq 'SAP_ERP_MATNR' and ProductID eq 'JMAT_PROD_API'&$inlinecount=allpages&$top=10&$inlinecount=allpages
Get Product Names of Product Origin Data Set with specific Product ID and Origin GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV/ ProductOriginDataSet(ProductOrigin='SAP_ERP_MATNR',ProductID='JMAT_PROD_API')/ ProductNames?$skip=0&$top=10&$inlinecount=allpages
Get Product with Product UUID GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV/ Products(guid'b5f39901-144d-a679-1700-236c971bc74e')
Get Product with Special Brand ID GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV/ Products?$skip=0&$top=10&$filter=ProductImageURL eq `www.productimage.de'
Get Product with Special Product Image URL GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV/ Products?$skip=0&$top=10&$filter=ProductImageURL eq `www.productimage.de'
Get Product Names of Product with specific Product ID and Origin with ServiceVersion 2; filter on Language GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ Products(guid'14f49901-144d-a679-1700-236c971bc74e')/ProductNames? $inlinecount=allpages
600
PUBLIC
Integration Guide Integration APIs
Get specific Product with Product ID and Origin with ServiceVersion 2
GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ ProductOriginDataSet?$filter=ProductID eq `JMAT_PROD_API' and ProductOrigin eq 'SAP_ERP_MATNR'&$inlinecount=allpages
Get first 10 Products with Service Version 2
GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ ProductOriginDataSet?$skip=0&$top=10&$inlinecount=allpages
Get Product Category Assignments of specific Product with Product ID and Origin with Service Version 2
https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ ProductCategoryAssignments?$filter=ProductID eq 'JMAT_Prod' and ProductOrigin eq 'SAP_ERP_MATNR'&$inlinecount=allpages
Get Product Names of specific Product with Product UUID with Service Version 2
GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ Products(guid'faf49901-144d-a679-1700-236c971bc74e')/ProductNames? $inlinecount=allpages
Get Product Origin Data Set of specific Product with Product UUID with serviceVersion 2
GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ Products(guid'fef49901-144d-a679-1700-236c971bc74e')/ProductOriginDataSet? $inlinecount=allpages
Get ProductNames of specific Product with Product UUID with serviceVersion 2
GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ Products(guid'faf49901-144d-a679-1700-236c971bc74e')/ProductNames? $inlinecount=allpages
Get Product Category Assignments of specific Product Origin Data Set with ID and Origin with ServiceVersion 2
GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ ProductOriginDataSet(ProductID='JMAT_Prod',ProductOrigin='SAP_ERP_MATNR')/ ProductCategoryAssignments?$inlinecount=allpages
Get Product Names of specific Product Origin Data Set with ID and Origin with ServiceVersion 2
GET https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_PRODUCT_SRV;v=2/ ProductOriginDataSet(ProductID='JMAT_Prod',ProductOrigin='SAP_ERP_MATNR')/ ProductNames?$inlinecount=allpages
Parent topic: Products [page 582]
Integration Guide Integration APIs
PUBLIC
601
Related Information
Basic Concepts [page 583] Structure of OData Service API_MKT_PRODUCT_SRV [page 585] Extensibility for Products [page 602] Function Imports [page 603]
5.2.6.4 Extensibility for Products
Extending Attributes
In addition to the pre-delivered attributes, you can add customer-specific fields using the Custom Fields app. For more information about how to do this, see Custom Fields. New fields can be added for the following BusinessContext: Marketing: Product
Create Extensibility Associations
You as an administrator in Marketing can define an association between a business object and the product or product categories to support customer-specific use cases. Exampe: Running a campaign for an event, which is defined as a product. You also want to analyze the campaign performance afterwards. To create an association, proceed as follows: Open the app Custom Fields. Create a new field and enter:
1. Business Context: Marketing Campaign 2. Label: <Name of the Field> 3. Identifier <Technical Name of the Field> 4. Tooltip <Full Name or Help for the Field> 5. Type Association to Business Object 6. Business Object: Marketing Product After you have done this, a reference to the standard product, including a proper value help is available. For reporting purposes, the product or product category is also available as additional dimension in CDS queries which expose the enhanced business object. Extensibility associations can also be used for Custom Business Objects, for example to define productspecific discounts or vouchers.
602
PUBLIC
Integration Guide Integration APIs
Parent topic: Products [page 582]
Related Information
Basic Concepts [page 583] Structure of OData Service API_MKT_PRODUCT_SRV [page 585] Payload Examples for Products [page 591] Function Imports [page 603]
5.2.6.5 Function Imports
Function imports are used to perform custom operations on an entity, which are typically not provided by OData operations.
Function Imports for Products
Function import MergeProductOriginData can be used to merge products with different ProductIDs from different origins into one product in SAP Marketing Cloud. Both products need to be already replicated. The ProductOriginData addressed with AdditionalProductID and AdditionalProductOrigin will then be moved as additional product data to product addressed with ProductID and ProductOrigin.
The product master data is determined from the main product origin data (addressed with ProductID and ProductOrigin). The properties not sent from the main origin are taken from the last updated additional origin. Every Update of the ProductOriginData leads to a redetermination of the product master data (golden record).
It is not possible to merge a product as additional product to two different main products.
Property
Description
Edm Core Type Max Length
Mandatory
Key
AdditionalProd Additional ID of the Edm.String
50
x
x
uctID
Product
AdditionalProd Origin of the addi Edm.String
30
x
x
uctOrigin
tional ID if the
Product
ProductID
ID of the Product Edm.String
50
x
x
ProductOrigin Origin of the Prod Edm.String
30
x
x
uct
Function import DeleteProductCategoryAssignments can be used to delete all product category assignments of a special product category hierarchy for a specified product.
Integration Guide Integration APIs
PUBLIC
603
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductID
ID of the Product Edm.String
50
x
x
ProductOrigin
Origin of the Prod Edm.String
30
x
x
uct
ProductCategory ID of Product Cat Edm.String
50
x
x
HierarchyID
egory Hierarchy
Parent topic: Products [page 582]
Related Information
Basic Concepts [page 583] Structure of OData Service API_MKT_PRODUCT_SRV [page 585] Payload Examples for Products [page 591] Extensibility for Products [page 602]
5.2.7 Product Hierarchies and Categories
Public OData API (API_MKT_PRODCAT_HIERARCHY_SRV) for Product Hierarchies and Categories. The OData service API_MKT_PRODCAT_HIERARCHY_SRV is used for standard SAP Marketing Cloud integration with SAP Commerce Cloud. It is used in commerce marketing to replicate product hierarchies and product categories to SAP Marketing Cloud. For more information about the integration scenario, see SAP Marketing Cloud, Integration with SAP Commerce Cloud [page 62]. OData service API_MKT_PRODCAT_HIERARCHY_SRV can be used to create SAP Marketing Cloud product hierarchies and product categories from any source system.
Note
If you encounter issues with the OData service API_MKT_PRODCAT_HIERARCHY_SRV, create a support ticket under component CEC-MKT-DM-PRO (Products and Product Categories). The component is not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408].
604
PUBLIC
Integration Guide Integration APIs
Technical Field Documentation
You can access detailed technical documentation for the API fields by downloading a metadata file in one of the following ways:
Access Link
Remarks
https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_PRODCAT_HIERARCHY_SRV/ $metadata?sapdocumentation=all
Only for internal access. You need to provide the server and port names.
Marketing - Product Category and Product Hierarchy Details Page
General access to the Details page of the service on SAP API Hub. One-time regis tration is required for first-time users.
1. On the Details page, click Download Specification and download as EDMX. 2. Specify which application you want to use to open the EDMX file type.
Product Category and Product Hierar chy API
General access link takes you directly to the Product Category and Product Hierarchy metadata file. One-time registration or logon is required.
Note
You can convert the XML file to an XML table to make it easier to read.
Please note the meaning of the following values in the file:
Metadata Value in XML sap:updatable sap:creatable nullable
Meaning When FALSE read-only field read-only field mandatory field
Basic Concepts [page 605] Structure of OData Service API_MKT_PRODCAT_HIERARCHY_SRV [page 606] Payload Example for Product Hierarchies [page 611]
Demonstrates creation of product hierarchies and categories. Extensibility for Product Categories [page 614]
5.2.7.1 Basic Concepts
Note
For generally applicable recommendations and best practices, make sure you refer to the section Best Practices and Recommended Package Sizes [page 400].
Integration Guide Integration APIs
PUBLIC
605
OData service API_MKT_PRODCAT_HIERARCHY_SRV supports batch processing. Within a batch request only the operation PATCH (MERGE) on the entity type ProductCategory or the operation POST on the entity types ProductHierarchy, ProductHierarchyName and ProductCategoryName are supported. Other operations, such as create, update or delete are not supported.
Additionally for all entities the GET operation is supported.
Batch requests allow grouping multiple operations into a single HTTP request payload.
Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service as described in [OData-URI ]. The batch request must contain a content-type header specifying a content type of multipart/mixed and a boundary specification.
A PATCH (MERGE) request updates only the properties indicated in the request body and leaves everything untouched that was not mentioned. All properties that are not to be changed, can be omitted. The transmitted properties are merged with the data already stored in SAP Marketing Cloud.
If the OData service is not accessible - for example due to missing authorization, or because the system is not available - a corresponding HTTP status code is returned.
If the OData service is accepted by the gateway component in the SAP Marketing Cloud system, the HTTP status code 201 or 204 is returned. Potential processing errors are recorded in the SAP Marketing Cloud system in the Import Monitor app, where they can be monitored, restarted and discarded.
Parent topic: Product Hierarchies and Categories [page 604]
Related Information
Structure of OData Service API_MKT_PRODCAT_HIERARCHY_SRV [page 606] Payload Example for Product Hierarchies [page 611] Extensibility for Product Categories [page 614]
5.2.7.2 Structure of OData Service API_MKT_PRODCAT_HIERARCHY_SRV
The API_MKT_PRODCAT_HIERARCHY_SRV OData service consists of the following entity sets and entity types:
Entity Set ProductHierarchies
ProductHierarchyNames
Entity Type ProductHierarchy
ProductHierarchyNames
Entity Type Description
Product Hierarchy entity refers to data kept in the master data tables within SAP Marketing Cloud.
Product Hierarchy Names entity has the related name and description fields and can be maintained for several languages.
606
PUBLIC
Integration Guide Integration APIs
Entity Set ProductCategories
Entity Type ProductCategory
ProductCategoryNames
ProductCategoryName
Entity Type Description
Product Category entity refers to data kept in the master data tables within SAP Marketing Cloud. The ID, a parent category ID, the type, and the Hier archy ID are the fields which can be maintained.
Similar to the hierarchy, the entity Product Cate gory has a related Product Category Name entity which holds the Name and Description in several languages.
The OData service API_MKT_PRODCAT_HIERARCHY_SRV supports OData batch processing.
Product hierarchies can be transferred by the OData POST operation for entity type ProductHierarchy.
Product categories can be transferred by the OData PATCH (MERGE) operation on the entity type ProductCategory.
Product hierarchy name and description can be transferred by the OData POST operation on the entity type ProductHierarchyName via the navigation parameter ProductHierarchyNames. Any operation on the ProductHierarchyNames entity set without navigation from the ProductHierarchies is not supported.
Product category name and description can be transferred by the OData POST operation on the entity type ProductCategoryName via the navigation parameter ProductCategoryNames. Any operation on the ProductCategoryNames entity set without navigation from the ProductCategories is not supported.
All entities support the OData GET operation to read the data.
Request Header
The request header contains the following additional header fields:
Header Field
Description
Edm Core Type
Sap-CuanSequenceId
Unique technical iden tifier of the imported data.
Edm.String
Sap-CuanRequestTimestamp
Timestamp of the data Edm.DateTime
Max Length 30
0
Mandatory X
*
Integration Guide Integration APIs
PUBLIC
607
Header Field
Description
Edm Core Type
Sap-CuanSequenceNumber
Sequence number of the request. This num ber is normally incre mented each time a new request for the same sequence id is created.
Edm.Int16
Sap-CuanSourceSystemType
Type of the source sys Edm.String tem
Sap-CuanSourceSystemId
Identifier of the source system. This is a free text field.
Edm.String
Sap-CuanExternalReference Id
External reference of the inbound message
Edm.String
Sap-CuanExternalDocumentI d
External identifier of the source document
Edm.String
Max Length 0
20 255 32 20
Mandatory *
X X
The header fields Sap-Cuan-SequenceId and Sap-Cuan-RequestTimestamp or Sap-CuanSequenceNumber are used to check the sequence of the received data. Data with a timestamp older or sequence number lower than data already imported, is ignored.
The Sap-Cuan-SourceSystemType and Sap-Cuan-SourceSystemId fields allow you to distinguish between different source systems.
* Either Sap-Cuan-RequestTimestamp or Sap-Cuan-SequenceNumber must be provided together with Sap-Cuan-SequenceId.
The Sap-Cuan-ExternalReferenceId and Sap-Cuan-ExternalDocumentId allow better error analysis because they contain external references to a source SOAP message and/or an IDoc.
ProductHierarchy
ProductHierarchy is the root entity and can be created or updated via the POST operation.
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductHierarc ID of the Product Edm.String
50
x
x
hyID
Hierarchy
608
PUBLIC
Integration Guide Integration APIs
Property
Description
Edm Core Type Max Length
Mandatory
Key
SourceSystemTy Type code of the Edm.String
20
pe
source system
ProductHierarc Usage Code of the Edm.String
1
hyUsage
Product Hierarchy
The allowed code values are: Property SourceSystemType
ProductHierarchyUsage
Code Value
CRM C4C YCOM PMR ERP S4
A B
Description undefined SAP CRM System SAP Cloud for Customer System SAP Commerce System SAP Promotion Management for Retail SAP ERP System SAP S4 System
Product Category Hierarchy Service Category Hierarchy
ProductHierarchyName
Product Hierarchy Name can be created only via the navigation property ProductHierarchyNames of the ProductHierarchy entity type.
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductHierarch ID of the Product Edm.String
50
x
x
yID
Hierarchy
Language
Language
Edm.String
2
x
x
Name
Name of the Prod Edm.String
120
uct hierarchy
Description
Description of the Edm.String
512
Product Hierarchy
Integration Guide Integration APIs
PUBLIC
609
ProductCategory
Product Category can be created via the Merge/Patch Operation. The corresponding root entity ProductHierarchy needs to be created before Product Categories can be created.
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductHierarc ID of the Product Edm.String
50
x
x
hyID
Hierarchy
ProductCategor ID of the Product Edm.String
50
x
x
yID
Category
ParentProductC ID of the superor Edm.String
50
ategoryID
dinate Product
Category
ProductCategor Type code of the Edm.String
2
yType
Product Category
The allowed code values for ProductCategoryType are:
Property
Code Value
ProductCategoryType
A
B
C
D
E
Description undefined Process Category Incident Category Object Category Cause Category Solution Category
All properties that are not to be changed can be omitted.
ProductCategoryName
Product Category Name can be created only via the navigation property ProductCategoryNames of the ProductCategory entity type.
Property
Description
Edm Core Type Max Length
Mandatory
Key
ProductHierarc ID of the Product Edm.String
50
x
x
hyID
Hierarchy
ProductCategor ID of the Product Edm.String
50
x
x
yID
Category
610
PUBLIC
Integration Guide Integration APIs
Property
Description
Edm Core Type Max Length
Mandatory
Key
Language
Language
Edm.String
2
x
x
Name
Name of the Prod Edm.String
120
uct Category
Description
Description of the Edm.String
512
Product Category
Property
Description
Edm Core Type Max Length
Mandatory
Key
Language
Language
Edm.String
2
x
x
Name
Name of the prod Edm.String
120
uct hierarchy
Description
Description of the Edm.String
512
product hierarchy
Parent topic: Product Hierarchies and Categories [page 604]
Related Information
Basic Concepts [page 605] Payload Example for Product Hierarchies [page 611] Extensibility for Product Categories [page 614]
5.2.7.3 Payload Example for Product Hierarchies
Demonstrates creation of product hierarchies and categories. The following example shows how you can use the product hierarchies and categories API. Insert your own data to fill the header and the entities.
Create Product Hierarchy and Product Categories
Sample Code
--batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a
Integration Guide Integration APIs
PUBLIC
611
--changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductHierarchies HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711
{ "ProductHierarchyID": "Coffee"
} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductHierarchies(ProductHierarchyID='Coffee')/ProductHierarchyNames HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711
{ "Language": "EN", "Name": "Coffee", "Description": "Coffee"
} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductHierarchies(ProductHierarchyID='Coffee')/ProductHierarchyNames HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711
{ "Language": "DE", "Name": "Kaffee", "Description": "Kaffee"
} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductCategories(ProductHierarchyID='Coffee',ProductCategoryID='Espresso') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711
{ "ProductHierarchyID": "Coffee", "ProductCategoryID": "Espresso",
612
PUBLIC
Integration Guide Integration APIs
"ParentProductCategoryID": "" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductCategories(ProductHierarchyID='Coffee',ProductCategoryID='Espresso')/ ProductCategoryNames HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 {
"Language": "EN", "Name": "Espresso", "Description": "Espresso" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductCategories(ProductHierarchyID='Coffee',ProductCategoryID='FilterCoffee' ) HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: YMQCLNT100 Sap-Cuan-SourceSystemType: SAP_ERP Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "ProductHierarchyID": "Coffee", "ProductCategoryID": "FilterCoffee", "ParentProductCategoryID": "" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductCategories(ProductHierarchyID='Coffee',ProductCategoryID='FilterCoffee' )/ProductCategoryNames HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711 { "Language": "EN", "Name": "Filtered Coffee", "Description": "Filtered Coffee" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH ProductCategories(ProductHierarchyID='Coffee',ProductCategoryID='DecafEspresso ') HTTP/1.1
Integration Guide Integration APIs
PUBLIC
613
Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711
{ "ProductHierarchyID": "Coffee", "ProductCategoryID": "DecafEspresso", "ParentProductCategoryID": "Espresso"
} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST ProductCategories(ProductHierarchyID='Coffee',ProductCategoryID='DecafEspresso ')/ProductCategoryNames HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-SourceSystemId: XXXCLNT100 Sap-Cuan-SourceSystemType: XXX_XXX Sap-Cuan-SequenceId: XXX_PRODHIER Sap-Cuan-RequestTimestamp: 2017-12-06T08:01:01 Sap-Cuan-ExternalReferenceId: 4711
{ "Language": "EN", "Name": "Decaf Espresso", "Description": "Espresso - Coffein free"
} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch--
Parent topic: Product Hierarchies and Categories [page 604]
Related Information
Basic Concepts [page 605] Structure of OData Service API_MKT_PRODCAT_HIERARCHY_SRV [page 606] Extensibility for Product Categories [page 614]
5.2.7.4 Extensibility for Product Categories
Extending Attributes
In addition to the pre-delivered attributes, you can add customer-specific fields using the Custom Fields app. For more information about how to do this, see Custom Fields.
614
PUBLIC
Integration Guide Integration APIs
New fields can be added for the following BusinessContext: Marketing: ProductCategory
Parent topic: Product Hierarchies and Categories [page 604]
Related Information
Basic Concepts [page 605] Structure of OData Service API_MKT_PRODCAT_HIERARCHY_SRV [page 606] Payload Example for Product Hierarchies [page 611]
5.2.8 Interactions
Public OData API (API_MKT_INTERACTION_SRV) for Interactions.
Overview
Note
For business documents (leads, opportunities, sales orders and so on), we recommend that you use the API Service CUAN_BUSINESS_DOCUMENT_IMP_SRV, since it provides an upsert function and updates an already existing entry depending on timestamp information.
OData Version Root URI Service Metadata URI: Authorizations
Communication Scenario ID
2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_SRV/$metadata
SAP delivers the following template role, which you can copy: SAP_CEI_API_INTERACTION .
The following business catalog role is required: SAP_CEC_BC_MKT_API_IA_PC
SAP_COM_0206
Integration Guide Integration APIs
PUBLIC
615
Component for Incidents
CEC-MKT-DM-IA
Note
Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408].
Technical Field Documentation
You can access detailed technical documentation for the API fields by downloading a metadata file in one of the following ways:
Note
You can convert the XML file to an XML table to make it easier to read.
Access Link https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTERACTION_SRV/$metadata?sapdocumentation=all Marketing - Interaction Integration Page
Interactions API
Remarks
Only for internal access. You need to provide the server and port names.
General access to the Interaction Integration page of the service on SAP API Hub. One-time registration is required for first-time users. 1. On the Interaction Integration page, click Download
Specification and download as EDMX. 2. Specify which application you want to use to open the
EDMX file type.
General access to the Interactions metadata file. One-time registration or logon is required.
Basic Concepts [page 617] The public API for Interactions API_MKT_INTERACTION supports operations on the Interaction Business Object. Interactions refer to communication and information exchange of any kind between a user's company and a contact, such as emails to a company, phone calls to a contact, and posts written in social networks about a company or the company's products.
Structure of OData Service API_MKT_INTERACTION [page 621] This document describes the structure of the Public OData API service API_MKT_INTERACTION. Make sure you read the Basic Concepts topic before you start.
Payload Examples for Interactions [page 633] Payload examples for API_MKT_INTERACTION
Error Handling for Interactions [page 647] This section contains some troubleshooting tips for handling common errors involving interaction imports.
616
PUBLIC
Integration Guide Integration APIs
5.2.8.1 Basic Concepts
The public API for Interactions API_MKT_INTERACTION supports operations on the Interaction Business Object. Interactions refer to communication and information exchange of any kind between a user's company and a contact, such as emails to a company, phone calls to a contact, and posts written in social networks about a company or the company's products.
Note
For generally applicable recommendations and best practices, make sure you refer to the section Best Practices and Recommended Package Sizes [page 400].
Prerequisites
Before interaction data can be imported, the following prerequisites must be met:
Upload sequence: Before you upload interactions, you should upload any related products and product hierarchies first.
Interaction type and communication medium have been assigned to a channel in the Self-Service Configuration app Manage Interaction Content.
Interests must be edited or uploaded in Business Administration Manage Interests . The BAdI: Revise Interaction Data Before Import (CUAN_IA_REVISE_FOR_IMPORT) can be used to change
data during import. The BAdI: Process Follow-Up Steps After Successful Import of Interaction Data
(CUAN_IA_IMPORT_FOLLOW_UP) can be used to update your custom business objects (CBOs) based on successfully saved interactions. For example, you can use a custom business object to count a contact's likes.
Structure
The following fields are mandatory for POST operations of interaction data:
Attribute ID_ORIGIN ID IA_TYPE COMM_MEDIUM
Description Qualifier for source system ID of contact of interaction in source system Interaction type Communication medium/place
Integration Guide Integration APIs
PUBLIC
617
Attribute TIMESTAMP
Description
UTC time stamp in long form (YYYYMMDDhhmmsmm muuun)
Note
The timestamp must always be provided as UTC time, so you have to adjust your local time accordingly before import. For example, if the timestamp shows New York local time 14:00:00, you have to adjust this to UTC by adding 5 hours to it: 19:00:00.
Examples for OData Format:
Number of milliseconds since midnight Jan 1, 1970. / Date(1406014140922)/
YY-MM-DDThh:mm:ss
Semantic Keys
Note
This refers to the semantic/external key of an interaction that is not a Business Document, that is where the communication medium is not BUSINESS_DOCUMENT. If the communication medium is BUSINESS_DOCUMENT, then the semantic/external key of a BusinessDocument entity is defined by the unique combination of the fields SourceSystemId, SourceSystemType, ExternalObjectType, ExternalObjectId.
The semantic key for interactions determines the uniqueness of an interaction record. The semantic key is defined by the following 7 fields, 5 mandatory and 2 optional:
These 5 fields are mandatory for POST operations and are checked during import: ID_ORIGIN: Origin of the interaction contact data (except in the case of ANONYMOUS interactions, as described below.) ID: External ID of the interaction contact data (except in the case of ANONYMOUS interactions, as described below.) IA_TYPE: Interaction type COMM_MEDIUM: Communication medium TIMESTAMP: UTC time stamp in long form (YYYYMMDDhhmmss.mmmuuun)
These 2 semantic key fields are optional and are not checked during import: SOURCE_OBJECT_TYPE: Object type of the source object, for example, an opportunity in SAP Cloud for Customer.
618
PUBLIC
Integration Guide Integration APIs
Note
If the communication medium is a Business Document, the SOURCE_OBJECT_TYPE is required. In this case the system checks to see whether the SOURCE_OBJECT_TYPE field is filled and returns an error if the field is empty.
SOURCE_OBJECT_ID: Object ID of the source object, for example, the GUID of the SAP Cloud for Customer opportunity or the original post ID of the respective social media network (such as TW or FB).
Note
One exception to this is in the case of a social posting. For a social posting, a SOURCE_OBJECT_ID is required. In this case the system checks to see whether the SOURCE_OBJECT_ID field is filled and returns an error if the field is empty. The check behavior is described in the table.
If IA_TYPE is SOCIAL_POSTING SHOP_ITEM_VIEW WEBSITE_SEARCH CLICK_THROUGH SALES_ORDER
SOURCE_OBJECT_ID should be fil
led with
Remarks
Original Post ID of the r