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 respective so This is checked during upload. cial media network WEB_SESSION_ID For recommendations only. Not checked during upload. WEB_SESSION_ID For recommendations only. Not checked during upload. WEB_SESSION_ID For recommendations only. Not checked during upload. SALES_ORDER_ID For recommendations only. Not checked during upload. Interaction Types That Cannot Be Imported You cannot import the following interaction types: MKT_PERM_OPTIN MKT_PERM_OPTIN_PRE MKT_PERM_OPTOUT MKT_PERM_OPTOUT_PRE NEWSLETTER_SUBSCR NEWSLETTER_UNSUBSCR NEWSL_SUBSCR_PRE NEWSL_UNSUBSCR_PRE DIG_ACC_SUBSCR Integration Guide Integration APIs PUBLIC 619 DIG_ACC_UNSUBSCR EMAIL_BOUNCE_HARD EMAIL_BOUNCE_SOFT If you want to import Marketing Permissions and Newsletter Subscriptions, you can use one of these services: API_MKT_CONTACT, API_MKT_INTERACTION_CONTACT, or API_MKT_CORPORATE_ACCOUNT. For more information about email bounces, see Email: Get Bounces [page 125]. Anonymous Interactions To import anonymous interactions, activate the IS_ANONYMOUS field. The system does not create a contact for anonymous interactions. The system behavior for anonymous interactions is as follows: Usual Case for Anonymous Interactions: The ID_ORIGIN is anonymous and the IS_ANONYMOUS indicator is set ("X"). The system stores the interaction as an anonymous one. Deviations from Usual Case: Termination of Import if: 1. The ID_ORIGIN is not anonymous and the IS_ANONYMOUS indicator is set ("X"). The system terminates the import with a corresponding notification. 2. The ID_ORIGIN is empty and the IS_ANONYMOUS indicator is not set (" "). The system terminates the import with a corresponding notification. System Correction of Import Data: 1. The ID_ORIGIN is anonymous and the IS_ANONYMOUS indicator is not set (" "). The system sets the IS_ANONYMOUS indicator and stores the interaction as an anonymous one. 2. The ID_ORIGIN is anonymous, the IS_ANONYMOUS indicator is set ("X"), and the ID is empty. The system creates a new GUID for field ID. 3. The ID_ORIGIN is empty (and, in addition, the ID is empty) and the IS_ANONYMOUS indicator is set ("X"). The system sets the ID_ORIGIN to anonymous, stores the interaction as an anonymous one, and creates a new GUID for field ID. Standard Fields and Custom Fields Custom Fields You can add customer-specific fields using the Custom Fields app. For more information, see Custom Fields. Custom fields are then automatically included during the OData uploads. Note You can see the structure of your data in the OData metadata structure that is displayed when you log onto the system as follows: https://<server&port>/sap/opu/odata/sap/cuan_import_srv/ $metadata 620 PUBLIC Integration Guide Integration APIs You can find a full list of all valid values for interaction types in the Configuration activity Manage Interaction Content. For more information, see Managing Interaction Content. Parent topic: Interactions [page 615] Related Information Structure of OData Service API_MKT_INTERACTION [page 621] Payload Examples for Interactions [page 633] Error Handling for Interactions [page 647] 5.2.8.2 Structure of OData Service API_MKT_INTERACTION 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. The Interaction OData API provides the following entity sets: Entity Set Interactions InteractionInterests InteractionProducts InteractionProductCategories InteractionDigitalAssets InteractionOffers InteractionTags InteractionAdditionalObjects Description Path This entity contains the interaction data. /Interactions This entity contains the interests as signed to an interaction. /InteractionInterests This entity contains the products in an /InteractionProducts interaction. This entity contains the product catego /InteractionProductCategories ries in an interaction. This entity contains the digital assets in /InteractionDigitalAssets an interaction. This entity contains the offers in an in /InteractionOffers teraction. This entity contains the tags in an inter /InteractionTags action. This entity contains the additional ob jects referred to by an interaction. /InteractionAdditionalObjects Integration Guide Integration APIs PUBLIC 621 Entity Set Description Path InteractionLoyaltyPrograms This entity contains the Loyalty Pro gram attributes in an interaction. /InteractionLoyaltyPrograms InteractionAdditionalInteractionCon tact This entity contains the additional con /InteractionAdditionalInteractionCon tacts involved in an interaction. tact InteractionEvent This entity contains the event referred to by an interaction. /InteractionEvent Furthermore, the following entity has the dedicated function of enabling high performance to be maintained when importing large amounts of data: Entity Set InteractionsDeepInsert Description This entity is used to import large amounts of Interactions data. Path /InteractionsDeepInsert Entity Sets Note To prevent an ODATA error message (The metadata do not allow a null value.), you must set a fixed initial value 00000000-0000-0000-0000-000000000000 for the UUID of all nodes, both root and subnodes. InteractionsDeepInsert Entity Path:/InteractionsDeepInsert The InteractionsDeepInsert entity enables high performant import of up to 100,00 interaction's data. You can perform the following operations on the InteractionsDeepInsert entity: 622 PUBLIC Integration Guide Integration APIs HTTP Method POST Description Path You can create interactions including one or more of these sub-entities using DEEP INSERT: InteractionInterest InteractionProducts InteractionProductCategories InteractionDigitalAssets InteractionOffers InteractionTags InteractionAdditionalObjects InteractionLoyaltyPrograms InteractionAdditionalContacts InteractionEvents /InteractionsDeepInsert Note This is the recommended method for the mass import of interactions data. Interactions Entity Path: /Interactions You can perform the following operations on the Interactions entity: HTTP Method GET Description Get a list of interactions. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby Get the details of a specific interaction using the Interaction UUID. Path /Interactions?$top=1 / Interactions(guid'<Interact ion UUID>') Integration Guide Integration APIs PUBLIC 623 HTTP Method POST POST Description Path Create an interaction. If the interaction already exists, /Interactions it is not created. An error is returned. Semantic key: (* = mandatory) InteractionContactOrigin * InteractionContactId * CommunicationMedium* InteractionType* InteractionTimeStampUTC* Note The timestamp must always be UTC time. When you import data, the local time stamp plus the difference to UTC is also allowed. For example, for New York local time 14:00:00, which is 5 hours before UTC, you could import the timestamp as: 2017-12-18T14:00:00-05:00 or 2017-12-18T19:00:00. When data is read, the UTC timestamp is always returned. InteractionSourceObjectType InteractionSourceObject Batch mode is also supported. You can create multiple interactions including one or more of these sub-entities using DEEP INSERT: InteractionInterest InteractionProducts InteractionProductCategories InteractionDigitalAssets InteractionOffers InteractionTags InteractionAdditionalObjects InteractionLoyaltyPrograms InteractionEvent Batch mode is also supported. /Interactions 624 PUBLIC Integration Guide Integration APIs HTTP Method PATCH DELETE Description Path Update an interaction. If the interaction does not exist, it is not created. An error is returned (no upsert is supported). / Interactions(guid'<Interact ion UUID>') The interaction key (InteractionUUID) must be provided to check its existence of the interaction. With the exception of the interaction key, all properties can be updated. If semantic key fields (see POST) are updated, a check is carried out to ensure that no duplicate interactions exist after the update. If duplicates exist, an error is re turned. Batch mode is also supported. Deletion of interactions is not supported by this serv For more information, see Interactions. ice. You must use one of the application jobs to delete interactions. InteractionInterests Entity Path: /InteractionInterests You can perform the following operations on the InteractionInterest entity: HTTP Method GET POST PATCH Description Path Get a list of interests assigned to interactions. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby / Interactions(guid'I nteractionUUID')/ InteractionInterest s Create an interest assignment to an interaction. If the inter action interest master data does not already exist, it is not created. An error is returned. / InteractionInterest s Batch mode is also supported. Update the assignment of an interest to an interaction. If the interest assignment does not exist, it is not cre ated. An error is returned (no upsert is supported). The entity key (InteractionInterestUUID) must be pro vided to check whether the interest exists. With the exception of the interaction and the entity key, all properties can be updated. Batch mode is also supported. / InteractionInterest s Integration Guide Integration APIs PUBLIC 625 HTTP Method DELETE Description Path Delete the assignment of an interest to an interaction. If the interest assignment does not exist, it is not deleted. An error is returned / InteractionInterest s Batch mode is also supported. InteractionProducts Entity Path: /InteractionProducts You can perform the following operations on the InteractionProducts entity: HTTP Method GET POST PATCH DELETE Description Path Get a list of products assigned to an interaction. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby / Interactions(guid'Interacti onUUID')/ InteractionProducts Create a product assignment to an interaction. If the product master data does not already exist, it is not created. An error is returned. /InteractionProducts Batch mode is also supported. Update the assignment of a product to an interac tion. If the product assignment does not exist, it is not created. An error is returned (no upsert is supported). The entity key (InteractionProductUUID) must be provided to check its existence. With the exception of the key properties (Inter actionUUID, ProductUUID, and InteractionPro ductUUID),, all properties can be updated. Batch mode is also supported. /InteractionProducts Delete the assignment of a product to an interaction. /InteractionProducts If the product assignment does not exist, it is not de leted. An error is returned. The entity key (InteractionProductUUID) must be provided to check its existence. Batch mode is also supported. InteractionProductCategories Entity Path: /InteractionProductCategories 626 PUBLIC Integration Guide Integration APIs You can perform the following operations on the InteractionProductCategories entity: HTTP Method GET POST PATCH DELETE Description Path Get a list of categories assigned to an interaction. / This method supports standard OData parameters Interactions(guid'Interaction such as $filter, $select, $top, $skip, UUID')/ $count, $inlinecount, and $orderby InteractionProductCategories Create a product category assignment to an inter action. If the product category master data does not already exist, it is not created. An error is re turned. /InteractionProductCategories Batch mode is also supported. Update the assignment of a product category to an /InteractionProductCategories interaction. If the product category assignment does not exist, it is not created. An error is returned (no upsert is supported). The entity key (InteractionProductCategor yUUID) must be provided to check its exis tence. With the exception of the key properties (In teractionUUID, ProductCategoryUUID and In teractionProductCategoryUUID), all proper ties can be updated. Batch mode is also supported. Delete the assignment of a product category to an interaction. If the assignment does not exist, it is not deleted. An error is returned. /InteractionProductCategories The entity key (InteractionProductCategor yUUID) must be provided to check its exis tence. Batch mode is also supported. InteractionDigitalAssets Entity Path: /InteractionDigitalAssets You can perform the following operations on the InteractionDigitalAssets entity: HTTP Method GET Description Get a list of digital assets assigned to an interaction. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby Path / Interactions(guid'Interacti onUUID')/ InteractionDigitalAssets Integration Guide Integration APIs PUBLIC 627 HTTP Method POST PATCH DELETE Description Path Create a digital asset assignment to an interaction. /InteractionDigitalAssest Batch mode is also supported. Update the assignment of a digital asset to an interac /InteractionDigitalAssest tion. If the assignment does not exist, it is not created. An error is returned (no upsert is supported). The entity key (InteractionDigitalAssetUUID) must be provided to check its existence. With the exception of the interaction and the entity key, all properties can be updated. Batch mode is also supported. Delete the assignment of a digital asset to an interac tion. If the assignment does not exist, it is not deleted. An error is returned /InteractionDigitalAssest Batch mode is also supported. InteractionOffers Entity Path: /InteractionOffers You can perform the following operations on the InteractionOffers entity: HTTP Method GET POST PATCH Description Path Get a list of offers assigned to an interaction. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby / Interactions(guid'Interact ionUUID')/ InteractionOffers Create an offer assignment to an interaction. /InteractionOffers Batch mode is also supported. Update the assignment of an offer to an interaction. If the assignment does not exist, it is not created. An error is returned (no upsert is supported). The entity key (InteractionOfferUUID) must be provided to check its existence. With the exception of the interaction and the en tity key, all properties can be updated. Batch mode is also supported. /InteractionOffers 628 PUBLIC Integration Guide Integration APIs HTTP Method DELETE Description Path Delete the assignment of an offer to an interaction. If the assignment does not exist, it is not deleted. An er ror is returned /InteractionOffers Batch mode is also supported. InteractionTags Entity Path: /InteractionTags You can perform the following operations on the InteractionTags entity: HTTP Method GET POST PATCH DELETE Description Path Get a list of tags assigned to an interaction. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby / Interactions(guid'Interact ionUUID')/InteractionTags Create a tag assignment to an interaction. /InteractionTags Batch mode is also supported. Update the assignment of a tag to an interaction. /InteractionTags If the assignment does not exist, it is not created. An error is returned (no upsert is supported). The entity key (InteractionTagUUID) must be pro vided to check its existence. With the exception of the interaction, the entity key, and the TagOrigin, all properties can be up dated. Batch mode is also supported. Delete the assignment of an interest to an interaction. If the interest assignment does not exist, it is not de leted. An error is returned /InteractionTags Batch mode is also supported. InteractionAdditionalObjects Entity Path: /InteractionAdditionalObjects Integration Guide Integration APIs PUBLIC 629 You can perform the following operations on the InteractionAdditionalObjects entity: HTTP Method GET POST PATCH DELETE Description Path Get a list of additional objects referred to by an interac / tion. This method supports standard OData parame ters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby Interactions(guid'Interact ionUUID')/ InteractionAdditionalObjec ts Create an additional object assignment to an interac tion. Batch mode is also supported. / InteractionAdditionalObjec ts Update the assignment of an additional object to an in / teraction. InteractionAdditionalObjec If the assignment does not exist, it is not created. ts An error is returned (no upsert is supported). The entity key (InteractionAdditionalObjUUID) must be provided to check its existence. With the exception of the interaction and the en tity key, all properties can be updated. Batch mode is also supported. Delete the assignment of an additional object to an in teraction. If the assignment does not exist, it is not de leted. An error is returned / InteractionAdditionalObjec ts Batch mode is also supported. InteractionLoyaltyPrograms Entity Path: /InteractionLoyaltyPrograms You can perform the following operations on the InteractionLoyaltyPrograms entity: HTTP Method GET POST PATCH Description Path Get a list of tags referred to by an interaction. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby / Interactions(guid'Interact ionUUID')/ InteractionLoyaltyPrograms Create a loyalty subnode assignment to an interaction. / InteractionLoyaltyPrograms Batch mode is also supported. Update the assignment of loyaly attributes to an inter action. Batch mode is also supported. InteractionLoyaltyProgram s(guid'InteractionLoyaltyU UIDUUID) 630 PUBLIC Integration Guide Integration APIs HTTP Method DELETE Description Path Delete the assigment of a Loyalty Subnode to an inter action. If the assignment does not exist, it is not de leted. An error is returned. Batch mode is also supported. InteractionLoyaltyProgram s(guid'InteractionLoyaltyU UIDUUID) InteractionAdditionalInteractionContacts Entity Path: /InteractionAdditionalInteractionContact Note The AdditionalInteractionContact entity is not visible on the UI, however it can still be used to perform the below operations. You can perform the following operations on the InteractionAdditionalInteractionContact entity: HTTP Method GET POST Description Path Get a list of additional contacts referred to by an inter action. This method supports standard OData param eters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby / Interactions(guid'Interact ionUUID')/ InteractionAddiotnalIntera ctionContact Create an additional contact assignment for an inter action. Note / InteractionAdditionalInter actionContact Unlike on the root entity, if the additional contact does not exist, an error is returned. The contact will not be created. PATCH Batch mode is also supported. Update the assignment of additional Contacts to an in teraction. If the contact does not exist, the interaction is not created. An error is returned (no upsert is sup ported). The entity key (InteractionAdditionalContac tUUID) must be provided to check its existence. With the exception of the interaction and the en tity key, all properties can be updated. Batch mode is also supported. / InteractionAdditionalInter actionContact Integration Guide Integration APIs PUBLIC 631 HTTP Method DELETE Description Path Delete the assignment of an additional contacts to an interaction. If the assignment does not exist, it is not deleted. An error is returned / InteractionAdditionalInter actionContact Batch mode is also supported. InteractionEvents Entity Path: /InteractionEvent Note You can perform the following operations on the InteractionEvent entity: HTTP Method GET POST Description Path Get a list of events referred to by an interaction. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby / Interactions(guid'Interact ionUUID')/InteractionEvent Create an event assignment for an interaction. /InteractionEvent Note Unlike on the root entity, if the event does not ex ist, an error is returned. The event will not be cre ated. PATCH DELETE Batch mode is also supported. Update the assignment of an event to an interaction. If the event does not exist, the interaction is not created. An error is returned (no upsert is sup ported). The entity key (InteractionEventUUID) must be provided to check its existence. With the exception of the interaction and the en tity key, all properties can be updated. Batch mode is also supported. /InteractionEvent Delete the assignment of an event to an interaction. If the assignment does not exist, it is not deleted. An er ror is returned /InteractionEvent Batch mode is also supported. 632 PUBLIC Integration Guide Integration APIs Parent topic: Interactions [page 615] Related Information Basic Concepts [page 617] Payload Examples for Interactions [page 633] Error Handling for Interactions [page 647] 5.2.8.3 Payload Examples for Interactions Payload examples for API_MKT_INTERACTION Note An InteractionUUID value must be included in the payload in cases where the sender checks the metadata (as on SAP Cloud Integration). Otherwise you will get the error message `The metadata do not allow a null value.' JSON version: "InteractionUUID": "00000000-0000-0000-0000-000000000000" XML version: <InteractionUUID>00000000-0000-0000-0000-000000000000</InteractionUUID> Available Payload Examples Entities Import Interactions Using InteractionsDeepInsert General Payload Examples GET Requests Offer Redemption - Interaction Offers Event Subnode Payload Examples Mass Import Using InteractionsDeepInsert [page 633] General Payload Examples [page 636] GET Requests [page 641] Offer Redemption - Entity Set: InteractionOffers [page 642] Event Subnode [page 644] Mass Import Using InteractionsDeepInsert Importing Interactions Using InteractionsDeepInsert InteractionsDeepInsert is used only for the mass import of Interactions. Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/InteractionsDeepInsert POST data: {"Interactions": [ {"InteractionContactOrigin":"EMAIL", Integration Guide Integration APIs PUBLIC 633 "InteractionContactId":"example@email.com", "CommunicationMedium":"EMAIL", "InteractionType":"EMAIL_BOUNCE_SOFT", "InteractionTimeStampUTC":"2019-01-21T09:42:48", "InteractionSourceObjectType":"ERP", "InteractionSourceObject":"12345678", "MarketingArea":"ICMA_DRINK", "CampaignID":"12121212", "InteractionLanguage":"EN", "InteractionAmount":"12.34", "InteractionCurrency":"EUR", "InteractionLatitude":"49.304864", "InteractionLongitude":"8.641526", "InteractionInterests": [ { "ItemOfInterest":"DRINK" } ], "InteractionProductCategories": [ { "ProductCategoryHierarchy":"Prod_Cat_1", "ProductCategory":"Product_CAT1 " } ], "InteractionProducts": [ { "ProductOrigin":"SAP_PRODUCT", "Product":"Product_1", "InteractionProductAmount":"99.99", "InteractionProductQuantity":"1", "InteractionProductUnit":"m" } ] } ], [ {"InteractionContactOrigin":"EMAIL", "InteractionContactId":"example2@email.com", "CommunicationMedium":"EMAIL", "InteractionType":"EMAIL_BOUNCE_SOFT", "InteractionTimeStampUTC":"2019-01-21T09:42:50", "InteractionSourceObjectType":"ERP", "InteractionSourceObject":"12345679", "MarketingArea":"ICMA_FOOD", "CampaignID":"12121212", "InteractionLanguage":"EN", "InteractionAmount":"12.34", "InteractionCurrency":"EUR", "InteractionLatitude":"49.304864", "InteractionLongitude":"8.641526", "InteractionInterests": [ { "ItemOfInterest":"FOOD" } ] } ] } 634 PUBLIC Integration Guide Integration APIs Post Interaction with InteractionAdditionalInteractionContacts Subnodes in Batch 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 POST InteractionsDeepInsert HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"Interactions": [ { "InteractionUUID":"539968d3-6aa5-f08f-a29a-b71ec6632712", "InteractionContactOrigin":"EMAIL", "InteractionContactId":"2020012109125288_apitest@teamwdf02.de", "CommunicationMedium":"EMAIL", "InteractionType":"EMAIL_BOUNCE_SOFT", "InteractionTimeStampUTC":"2020-01-21T09:12:52", "InteractionSourceObjectType":"ERP", "InteractionSourceObject":"12345678", "SourceSystemType":"ERP", "SourceSystem":"ERP001", "InteractionTags": [ { "TagOrigin":"INTERNAL", "TagType":"SEARCHTERM", "TagName":"geocode:49.3,8.65,10km" } ], "InteractionAdditionalInteractionContacts": [ { "InteractionContactOrigin":"SAP_CRM_BUPA", "InteractionContactId":"Contact_NB_1_WDF02_apitest@teamwdf02.de"} ] } , { "InteractionUUID":"ec4d21d9-c42e-2e82-8649-9da266dbafdc", "InteractionContactOrigin":"EMAIL", "InteractionContactId":"_2_88_2020012109125288_apitest@teamwdf02.de", "CommunicationMedium":"FB", "InteractionType":"SOCIAL_POSTING", "InteractionTimeStampUTC":"2020-01-21T06:12:52", "InteractionSourceObjectType":"ERP", "InteractionSourceObject":"12345678", "SourceSystemType":"ERP", "SourceSystem":"ERP001", "InteractionTags": [ { "TagOrigin":"INTERNAL", "TagType":"SEARCHTERM", "TagName":"geocode:49.3,8.65,10km" } ], "InteractionAdditionalInteractionContacts": [ { "InteractionContactOrigin":"SAP_CRM_BUPA", "InteractionContactId":"Contact_NB_2_WDF02_apitest@teamwdf02.de", Integration Guide Integration APIs PUBLIC 635 "InteractionContactUUID":"6c0b84b7-5523-1ee9-96d6-7d9a4ff26047" } , { "InteractionContactUUID":"6c0b84b7-5523-1ee9-96d6-7d9a4ff26047" } ] } ] } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- General Payload Examples Import 2 Interactions with 3 Products and 3 Interests as Sub-Nodes Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/$batch 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 POST Interactions HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "InteractionContactOrigin":"SAP_HYBRIS_CONSUMER", "InteractionContactId":"4711", "CommunicationMedium":"ONLINE_SHOP", "InteractionType":"SHOP_CART_VIEW", "InteractionTimeStampUTC":"2018-04-25T08:16:53", "InteractionSourceObjectType":"COMMERCE_SC", "InteractionSourceObject":"4444", "MarketingArea":"CXXGLOBAL", "CampaignID":"12121212", "MarketingLocationOrigin":"", "MarketingLocation":"", "DigitalAccountType":"", "DigitalAccount":"", "MKT_AgreementOrigin":"", "MKT_AgreementExternalID":"", "InteractionStatus":"", "InteractionReason":"", "InteractionLanguage":"EN", "InteractionAmount":"12.34", "InteractionCurrency":"EUR", "InteractionLatitude":"49.304864", "InteractionLongitude":"8.641526", "SpatialReferenceSystem":"", "DeviceType":"", "InteractionDeviceName":"", "SourceSystemType":"COMMERCE", "SourceSystem":"HC121", "InteractionSourceObjectAddlID":"", 636 PUBLIC Integration Guide Integration APIs "InteractionSourceObjectStatus":"", "InteractionSourceDataURL":"http://www.sap.com/shoppingcartlink", "CampaignContentLinkURL":"", "CampaignContentLinkName":"", "InteractionLastChangedByUser":"", "InteractionContentSubject":"", "InteractionContent":"", "InteractionInterests": [ { "ItemOfInterest":"MarketingCloud", "InteractionIntrstWeightingFctr":1, "InteractionIntrstSentimentVal":1 }, { "ItemOfInterest":"BigData", "InteractionIntrstWeightingFctr":1, "InteractionIntrstSentimentVal":1 }, { "ItemOfInterest":"SAPHana", "InteractionIntrstWeightingFctr":1, "InteractionIntrstSentimentVal":1 } ], "InteractionProducts": [ { "ProductOrigin":"SAP_HYBRIS_PRODUCT", "Product":"PRD-0", "InteractionProdWeightingFactor":1, "InteractionProductSentimentVal":1, "InteractionProductAmount":"12.12", "InteractionProductQuantity":"1", "InteractionProductUnit":"m", "ProductRecommendationModelType":"", "InteractionProductStatus":"", "InteractionProductReason":"" }, { "ProductOrigin":"SAP_HYBRIS_PRODUCT", "Product":"PRD-1", "InteractionProdWeightingFactor":1, "InteractionProductSentimentVal":1, "InteractionProductAmount":"12.12", "InteractionProductQuantity":"1", "InteractionProductUnit":"m", "ProductRecommendationModelType":"", "InteractionProductStatus":"", "InteractionProductReason":"" }, { "ProductOrigin":"SAP_HYBRIS_PRODUCT", "Product":"PRD-2", "InteractionProdWeightingFactor":1, "InteractionProductSentimentVal":1, "InteractionProductAmount":"12.12", "InteractionProductQuantity":"1", "InteractionProductUnit":"m", "ProductRecommendationModelType":"", "InteractionProductStatus":"", "InteractionProductReason":"" } ] } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary Integration Guide Integration APIs PUBLIC 637 POST Interactions HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "InteractionContactOrigin":"SAP_HYBRIS_CONSUMER", "InteractionContactId":"4712", "CommunicationMedium":"ONLINE_SHOP", "InteractionType":"SHOP_ITEM_ADD", "InteractionTimeStampUTC":"2018-04-25T08:16:53", "InteractionSourceObjectType":"COMMERCE_SC", "InteractionSourceObject":"55599", "MarketingArea":"CXXGLOBAL", "CampaignID":"12121212", "MarketingLocationOrigin":"", "MarketingLocation":"", "DigitalAccountType":"", "DigitalAccount":"", "MKT_AgreementOrigin":"", "MKT_AgreementExternalID":"", "InteractionStatus":"", "InteractionReason":"", "InteractionLanguage":"EN", "InteractionAmount":"12.34", "InteractionCurrency":"EUR", "InteractionLatitude":"49.304864", "InteractionLongitude":"8.641526", "SpatialReferenceSystem":"", "DeviceType":"", "InteractionDeviceName":"", "SourceSystemType":"COMMERCE", "SourceSystem":"HC121", "InteractionSourceObjectAddlID":"", "InteractionSourceObjectStatus":"", "InteractionSourceDataURL":"http://www.sap.com/shoppingcartlink", "CampaignContentLinkURL":"", "CampaignContentLinkName":"", "InteractionLastChangedByUser":"", "InteractionContentSubject":"", "InteractionContent":"", "InteractionInterests": [ { "ItemOfInterest":"MarketingCloud", "InteractionIntrstWeightingFctr":1, "InteractionIntrstSentimentVal":1 }, { "ItemOfInterest":"BigData", "InteractionIntrstWeightingFctr":1, "InteractionIntrstSentimentVal":1 }, { "ItemOfInterest":"SAPHana", "InteractionIntrstWeightingFctr":1, "InteractionIntrstSentimentVal":1 } ], "InteractionProducts": [ { "ProductOrigin":"SAP_HYBRIS_PRODUCT", "Product":"PRD-0", "InteractionProdWeightingFactor":1, "InteractionProductSentimentVal":1, "InteractionProductAmount":"12.12", "InteractionProductQuantity":"1", "InteractionProductUnit":"m", 638 PUBLIC Integration Guide Integration APIs "ProductRecommendationModelType":"", "InteractionProductStatus":"", "InteractionProductReason":"" }, { "ProductOrigin":"SAP_HYBRIS_PRODUCT", "Product":" PRD-1", "InteractionProdWeightingFactor":1, "InteractionProductSentimentVal":1, "InteractionProductAmount":"12.12", "InteractionProductQuantity":"1", "InteractionProductUnit":"m", "ProductRecommendationModelType":"", "InteractionProductStatus":"", "InteractionProductReason":"" }, { "ProductOrigin":"SAP_HYBRIS_PRODUCT", "Product":"PRD-2", "InteractionProdWeightingFactor":1, "InteractionProductSentimentVal":1, "InteractionProductAmount":"12.12", "InteractionProductQuantity":"1", "InteractionProductUnit":"m", "ProductRecommendationModelType":"", "InteractionProductStatus":"", "InteractionProductReason":"" } ] } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Update Interaction 1 Root and Sub-Node Product via BATCH Request Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/$batch 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 PATCH Interactions(InteractionUUID=guid'60b1329a-1d04a325-1600-236ca577cc6a') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "InteractionSourceObject":"87654321", "InteractionUUID":"60b1329a-1d04-a325-1600-236ca577cc6a", "InteractionContactId":"4711", "MarketingArea":"CXXGLOBAL", "CampaignID":"986532", "InteractionLatitude":"50.304864", "InteractionLongitude":"5.228967", "InteractionLanguage":"DE", "CommunicationMedium":"WEB", "InteractionType":"WEBSITE_REGISTRATION" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary Integration Guide Integration APIs PUBLIC 639 PATCH InteractionProducts(InteractionProductUUID=guid'63b1329a-1d04a325-1600-236ca577cc6a') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "InteractionUUID":"60b1329a-1d04-a325-1600-236ca577cc6a", "ProductOrigin":"SAP_HYBRIS_PRODUCT", "Product":"PRD-2", "InteractionProdWeightingFactor":2, "InteractionProductSentimentVal":2 } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Post New Sub-Node, Update Root and Sub-Nodes and Delete Sub-Node: Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/$batch 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 POST InteractionInterests HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "InteractionUUID":"60b1329a-1d04-a325-1600-236ca577cc6a", "ItemOfInterest":"HybrisMarketing", "InteractionIntrstWeightingFctr":1, "InteractionIntrstSentimentVal":1 } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH Interactions(InteractionUUID=guid'60b1329a-1d04-a325-1600-236ca577cc6a) HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "InteractionSourceObject":"22222", "InteractionUUID":"60b1329a-1d04-a325-1600-236ca577cc6a", "InteractionContactId":"4711", "MarketingArea":"CXXGLOBAL", "CampaignID":"0000033333", "InteractionLatitude":"70.304864", "InteractionLongitude":"7.228967", "InteractionLanguage":"DE", "CommunicationMedium":"WEB", "InteractionType":"WEBSITE_VISIT" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH InteractionProducts(InteractionProductUUID=guid'63b1329a-1d04a325-1600-236ca577cc6a') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json 640 PUBLIC Integration Guide Integration APIs { "InteractionUUID":"60b1329a-1d04-a325-1600-236ca577cc6a", "ProductOrigin":"SAP_HYBRIS_PRODUCT", "Product":"PRD-2", "InteractionProdWeightingFactor":3, "InteractionProductSentimentVal":3 } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary PATCH InteractionInterests(InteractionInterestUUID=guid'8aac579a-1d04a325-1600-236ca577cc6a') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "InteractionUUID":"60b1329a-1d04-a325-1600-236ca577cc6a", "ItemOfInterest":"BigData", "InteractionIntrstWeightingFctr":1, "InteractionIntrstSentimentVal":2 } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary DELETE InteractionProductCategories(InteractionProductCategoryUUID=guid'63b1329a-1d04 -a325-1600-236ca577cc6a') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "InteractionUUID":"60b1329a-1d04-a325-1600-236ca577cc6a" } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- GET Requests Get the first 10 Interactions sorted by InteractionTimeStamp /sap/opu/odata/sap/API_MKT_INTERACTION_srv/Interactions?$top=10& $orderby=InteractionTimeStampUTC desc Get the first 3 Interactions sorted by InteractionType /sap/opu/odata/sap/API_MKT_INTERACTION_srv/Interactions?$filter=InteractionType eq 'OFFER_CLICK'&$top=3 Get Interaction for specific InteractionUUID Note This returns the interaction with the specified UUID, however there must be a number provided in the TOP Parameter /sap/opu/odata/sap/API_MKT_INTERACTION_srv/Interactions?$filter=(InteractionUUID eq guid'00000063-4657-49c8-1500-8f6c10e2ef5b')&$top=10 Integration Guide Integration APIs PUBLIC 641 Get the first 20 Interactions filtered by multiple entity types You can filter by InteractionType, CommunicationMedium, InteractionSourceObject, InteractionDeviceName, InteractionContactOrigin and InteractionContactId and Interaction. Subnodes such as InteractionInterests, InteractionDigitalAssets, InteractionOffers,InteractionTags and InteractionAdditionalObjects will be expanded. /sap/opu/odata/sap/API_MKT_INTERACTION_SRV/Interactions? $expand=InteractionInterests,InteractionDigitalAssets,InteractionOffers,Interaction Tags,InteractionAdditionalObjects$filter=((InteractionType eq 'EMAIL_OUTBOUND') and (CommunicationMedium eq 'EMAIL') and (InteractionSourceObject eq 'XXX') and (InteractionDeviceName eq 'XXX') and (InteractionContactOrigin eq 'XXX') and (InteractionContactId eq `2612d9ed1631856b'))&$skip=0&$top=20& $orderby=InteractionSourceObject&$inlinecount=allpages Get the first 10 Interactions within a specific time slot filtered by InteractionTimeStampUTC /sap/opu/odata/sap/API_MKT_INTERACTION_srv/Interactions? $filter=((InteractionTimeStampUTC gt datetimeoffset'2010-06-10T22:00:00.165') and (InteractionTimeStampUTC le datetimeoffset'2018-06-10T22:00:00.165'))&$top=10 Offer Redemption - Entity Set: InteractionOffers Note For an interaction of type OFFER_REDEMPTION it is necessary to fill the InteractionOffers entity. At least one of the following property combinations have to be provided: Single coupon codes: MarketingOffer ExternalOffer, ExternalOfferOrigin Coupon - Multi coupon codes: MarketingOffer, Coupon Code MarketingOffer, Serial Number ExternalOffer, ExternalOfferOrigin, CouponCode ExternalOffer, ExternalOfferOrigin, SerialNumber Coupon, CouponCode Coupon, SerialNumber There is no dedicated property for the "SerialNumber"; it is imported using the property "CouponCode" with "CouponCodeType" set to "S"). You can import several redemptions for a dedicated coupon code using the property "NumberOfRedemption". You can also cancel redemptions by setting this property to a negative value. Single Coupon Code, Import with External Offer and External Offer Origin Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/Interactions POST data: { 642 PUBLIC Integration Guide Integration APIs "InteractionTimeStampUTC": "2018-10-10T08:15:54", "InteractionContactId": "john.doe@company.com", "InteractionContactOrigin": "EMAIL", "CommunicationMedium": "ONLINE_SHOP", "InteractionType": "OFFER_REDEMPTION", "InteractionIsAnonymous": false, "InteractionOffers": [{ "ExternalOffer": "offer_3452", "ExternalOfferOrigin": "EXT_SYSTEM" }] } Single Coupon Code, Import with Coupon (Redemption Cancellation) Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/Interactions POST data: { "InteractionTimeStampUTC": "2018-10-10T07:15:54", "InteractionContactId": "john.doe@company.com", "InteractionContactOrigin": "EMAIL", "CommunicationMedium": "ONLINE_SHOP", "InteractionType": "OFFER_REDEMPTION", "InteractionIsAnonymous": false, "InteractionOffers": [{ "Coupon": "single_coupon564", "NumberOfRedemption": -1 }] } Multi Coupon Code, Import with Coupon and Serial Number Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/Interactions POST data: { "InteractionTimeStampUTC": "2018-10-10T08:13:23", "InteractionContactId": "john.doe@company.com", "InteractionContactOrigin": "EMAIL", "CommunicationMedium": "ONLINE_SHOP", "InteractionType": "OFFER_REDEMPTION", "InteractionIsAnonymous": false, "InteractionOffers": [{ "Coupon": "multi_coupon241", "CouponCode": "SN4421", "CouponCodeType": "S", "NumberOfRedemption": 1 }] } Multi Coupon Code, Import with External Offer, External Offer Origin and Coupon Code Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/Interactions Integration Guide Integration APIs PUBLIC 643 POST data: { "InteractionTimeStampUTC": "2018-10-09T09:34:11", "InteractionContactId": "john.doe@company.com", "InteractionContactOrigin": "EMAIL", "CommunicationMedium": "ONLINE_SHOP", "InteractionType": "OFFER_REDEMPTION", "InteractionIsAnonymous": false, "InteractionOffers": [{ "ExternalOffer": "offer_5526", "ExternalOfferOrigin": "EXT_SYSTEM2", "CouponCode": "CODE33511", "CouponCodeType": "" }] } Event Subnode Post Interaction and Event Subnode Non Batch Mode: Sample Code POST: https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_INTERACTION_SRV/ Interactions POST data: {"InteractionContactOrigin":"EMAIL","InteractionContactId":"20190927151824_api test@teamwdf02.de","CommunicationMedium":"EMAIL","InteractionType":"EMAIL_BOUN CE_SOFT","InteractionTimeStampUTC":"2019-09-27T15:18:24","InteractionSourceObj ectType":"ERP","InteractionSourceObject":"12345678","MarketingArea":"ICMA_DRIN K","InteractionEvents":[{"MktgEventExternalId":"WDF02 1E2019-09-27T15:18:16","MktgEventProvider":"ON24_ID","MktgEventProviderAccount ":"123"}]} Post Interaction Event Subnode DeepInsert: Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/InteractionsDeepInsert POST data: {"Interactions": [{"InteractionContactOrigin":"EMAIL","InteractionContactId":"20190927151822_ap itest@teamwdf02.de","CommunicationMedium":"EMAIL","InteractionType":"EMAIL_BOU NCE_SOFT","InteractionTimeStampUTC":"2019-09-27T15:18:22","InteractionSourceOb jectType":"ERP","InteractionSourceObject":"12345678","MarketingArea":"ICMA_DRI NK","InteractionEvents":[{"MktgEventExternalId":"WDF02 2E2019-09-27T15:18:16","MktgEventProvider":"ON24_ID","MktgEventProviderAccount ":"123"}]}]} Post Interaction Event Subnode Batch Mode: Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/$batch 644 PUBLIC Integration Guide Integration APIs 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 POST InteractionEvents HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"InteractionUUID":"d11415a6-e69b-64bbb8d7-1667395b10d6","InteractionEventUUID":"6c0b84b7-5523-1ed9b8a7-40fa9950e7ce","MktgEventExternalId":"WDF02 3E2019-09-27T15:18:16","MktgEventProvider":"ON24_ID","MktgEventProviderAccount ":"123"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- POST Interaction Event Subnode Non Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/InteractionEvents POST data: {"InteractionUUID":"d11415a6-e69b-64bbb8d7-1667395b10d6","InteractionEventUUID":"6c0b84b7-5523-1ed9b8a7-40fa995107ce","MktgEventExternalId":"WDF02 4E2019-09-27T15:18:16","MktgEventProvider":"ON24_ID","MktgEventProviderAccount ":"123"} Update Interaction Event Sub Node Non Batch Mode: Sample Code PATCH https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/ InteractionEvents(InteractionEventUUID=guid'24c63568-4daf-3dd6-1600-236c2e825c e5') PATCH data: {"MktgEventAttendanceType":"01"} Update Interaction Event Subnode Batch Mode: Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/$batch 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 PATCH InteractionEvents(InteractionEventUUID=guid'24c63568-4daf-3dd6-1600-236c2e825c e5') HTTP/1.1 Content-Length: 1035 Integration Guide Integration APIs PUBLIC 645 Accept: application/json Content-Type: application/json {"MktgEventAttendanceType":"02"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Delete Interaction Event Subnode Non Batch Mode: Sample Code DELETE https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/ InteractionEvents(InteractionEventUUID=guid'24c63568-4daf-3dd6-1600-236c2e825c e5') Delete Interaction Event Subnode Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTERACTION_SRV/$batch 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 InteractionEvents(InteractionEventUUID=guid'24c63568-4daf-3dd6-1600-236c2e825c e5') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"InteractionUUID":"d11415a6-e69b-64bb-b8d7-1667395b10d6"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Parent topic: Interactions [page 615] Related Information Basic Concepts [page 617] Structure of OData Service API_MKT_INTERACTION [page 621] Error Handling for Interactions [page 647] 646 PUBLIC Integration Guide Integration APIs 5.2.8.4 Error Handling for Interactions This section contains some troubleshooting tips for handling common errors involving interaction imports. Error / Error Message Invalid entry in column &2: '&1' What It Means What You Can Do Either: Maintain Configuration Configuration is missing Invalid characters have been used The format is incorrect Correct invalid entries: for example Phone numbers have to start with `+' or `00'. Note Refer to the message long text. ODATA error: The metadata do not al low a null value. The value of the UUID cannot be empty. To prevent an ODATA error message, you must set a fixed initial value 00000000-0000-0000-0000-00 0000000000 for the UUID of all no des, both root and subnodes. Timestamp is incorrect Microsoft Excel formats the timestamp Format the value in Microsoft Excel as incorrectly when opening the file. follows: 1. Change the type of the field to number. 2. Remove all decimal places. 3. Remove the separator. 4. Enter a valid time (YYYYMMDDhhmmss). 5. Save Special characters are not imported The data is not loaded in utf-8 encod ing. Send data in utf-8 encoding. Use an edi tor that supports this. Parent topic: Interactions [page 615] Related Information Basic Concepts [page 617] Structure of OData Service API_MKT_INTERACTION [page 621] Payload Examples for Interactions [page 633] HTTP Response Status Codes [page 408] Best Practices and Recommended Package Sizes [page 400] Import Monitor [page 404] Integration Guide Integration APIs PUBLIC 647 5.2.9 Interest Items Public OData API (API_MKT_INTEREST_SRV) for InterestItems. An interest represents the content or subject of a contact's interaction. Overview The public API for InterestItems supports operations on the Business Object CUAN_INTEREST. OData Version Root URI Service Metadata URI: Authorizations Communication Scenario ID Component for Incidents 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTEREST_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/$metadata The following business catalog role is required: SAP_COM_0340 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_Interests_SRV/$metadata?sapdocumentation=all Remarks Only for internal access. You need to provide the server and port name 648 PUBLIC Integration Guide Integration APIs Access Link Remarks https://api.sap.com/api/API_MKT_INTEREST_SRV/overview General access to the Interest Item Integration page of the Marketing - Interest Items Integration Page service on SAP API Hub. One-time registration is required for first-time users. 1. On the Interest Item Integration page, click Download Specification and download as EDMX. 2. Specify which application you want to use to open the EDMX file type. https://api.sap.com/api/API_MKT_INTEREST_SRV/overview General access to the Interest Items metadata file. One-time registration or logon is required. 5.2.9.1 Structure of API_MKT_INTEREST_SRV This document describes the structure of the Public OData API service API_MKT_INTEREST. Make sure you read the Basic Concepts topic before you start. The InterestItem OData API provides the following entity sets: Entity Set InterestItems InterestItemProdCats InterestItemTags InterestItemTexts Description Path This entity contains interest items data. /InterestItems This entity contains the product catego /IinterestItemProdCats ries of interest items. Product catego ries can be assigned to products so re lated products can be grouped to gether. This entity contains the tags assigned /InterestTags to interests. Tags are terms or groups of terms assigned to an entity to help clas sify it's content. This entity contains the language speci /InterestItemTexts fications of an interest item text. Entity Sets InterestItems Entity Path: /InterestItems Integration Guide Integration APIs PUBLIC 649 You can perform the following operations on the InterestItem entity: HTTP Method GET Description Path Return a list of InterestItems. This method supports standard OData pa rameters such as $filter, $select, /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItems Get the top 2 InterestItems /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItems?$top=2 Return specific InterestItem "xxx" /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItems? $filter=ItemOfInterest eq 'xxx' Return a list of InterestItems ommitting /sap/opu/odata/SAP/ the top 2 InterestItems API_MKT_INTEREST_SRV/ InterestItems?$skip=2 Return a list of of InterestItemTexts as signed to the specified InterestItem "xxx" /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItems('xxx')/ InterestItemTexts Return a list of InterestItemTags as signed to the specified InterestItem "xxx" /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItems('xxx')/ InterestItemTags Returns a list of InteresItemProdCats assigned to the specified InterestItem "xxx" /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItems('xxx')/ InterestItemProdCats Return details of a specified InterestI tem "xxx" /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItems('xxx') InterestItemProdCats Entity Path: /InterestItemProdCats 650 PUBLIC Integration Guide Integration APIs You can perform the following operations on the InterestItemProdCat entity: HTTP Method GET Description Path Return a list of InterestItemProdCat. This method supports standard OData parameters such as $filter, $select, $top /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItemProdCats/ InterestItemTexts Entity Path: /InterestItemText You can perform the following operations on the InterestItemText entity: HTTP Method GET Description Path Return a list of InterestItemTextst. This method supports standard OData pa rameters such as $filter, $select, $top /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItemTexts InterestItemTags Entity Path: /InterestItemTags You can perform the following operations on the InterestItemTags entity: HTTP Method GET Description Path Return a list of InterestItemTags. This method supports standard OData pa rameters such as $filter, $select, $top /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItemTags Return a list of InterestItems with the Tag Type field provided /sap/opu/odata/SAP/ API_MKT_INTEREST_SRV/ InterestItemTags? $select=TagType 5.2.9.2 Payload Examples for Interest Items Payload examples for API_MKT_INTEREST. The following examples demonstrate how you can use the Interests API. Integration Guide Integration APIs PUBLIC 651 Method Payload Examples - Batch Mode Payload Examples - Non-Batch Mode Deep Create Interests Create Interest Create Item of Interest Create Text Assignments Assignments Deep Create Interests Batch Mode [page 652] Deep Create Interests Non-Batch Mode [page 654] Create Interests (Non-Deep) BATCH Mode [page 654] Create Interests (Non-Deep) NonBATCH Mode [page 655] Create Interest Item Text Assign ments in Batch Mode [page 655] Create Interest Item Text Assign ments in Non-Batch Mode [page 656] Create Tag Assignments Create Product Category Assignments Delete Item Of Interest Delete Item of Interest Delete Text Assignments Assignments Delete Tag Assignments Delete Product Category Assignments Update Interest Text Assignments Update Interest Text As signments Create Interest Item tag Assign ments in Batch Mode [page 656] Create Interest Item tag Asssign ments in Non-Batch Mode [page 656] Create Interest Item Product Category Assignments in Batch Mode [page 657] Create Interest Item Product Cate gory Assignments in Non-Batch Mode [page 657] Delete Interest items in Batch Mode [page 657] Delete Interest items in Non-Batch Mode [page 658] Delete Interest Items Text As signment in Batch Mode [page 658] Delete Interest Item Text Assign ment in Non-Batch Mode [page 658] Delete Interest Item Tag Assign ments in Batch Mode [page 659] Delete Interest Item tag Assign ments in Non-Batch Mode [page 659] Delete Interest Item Product Cat Delete Interest Item Product Cate egory Assignments in Batch gory Assignments in Non-Batch Mode [page 659] Mode [page 660] Update Interest Text Assign ments in Batch Mode [page 660] Update Interest Text Assignments in Non-Batch Mode [page 660] Deep Create Interests Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 POST InterestItems HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { 652 PUBLIC Integration Guide Integration APIs "ItemOfInterest":"T220190325153232", "InterestItemTexts": [ { "Language":"EN", "ItemOfInterest":"T220190325153232", "ItemOfInterestName":"Test API Interest Srv" }, { "Language":"DE", "ItemOfInterest":"T220190325153232", "ItemOfInterestName":"Deutsch Test" } ], "InterestItemTags": [ { "TagName":"gallo d'oro", "ItemOfInterest":"T220190325153232" } ], "InterestItemProdCats": [ { "ProductCategoryHierarchy":"TEAM_WDF02_JS", "ProductCategory":"IOI_API_CAT_EF20190325153225", "ItemOfInterest":"T220190325153232" } ] } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST InterestItems HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json { "ItemOfInterest":"T320190325153232", "InterestItemTexts": [ { "Language":"EN", "ItemOfInterest":"T320190325153232", "ItemOfInterestName":"Test API Interest Srv" }, { "Language":"DE", "ItemOfInterest":"T320190325153232", "ItemOfInterestName":"Deutsch Test" } ], "InterestItemTags": [ { "TagName":"#taste", "ItemOfInterest":"T320190325153232" } ] } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Integration Guide Integration APIs PUBLIC 653 Deep Create Interests Non-Batch Mode Sample Code POST: https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/InterestItems POST data: { "ItemOfInterest":"T3320190325153242", "InterestItemTexts": [ { "Language":"EN", "ItemOfInterest":"T3320190325153242", "ItemOfInterestName":"Test API Interest Srv" }, { "Language":"DE", "ItemOfInterest":"T3320190325153242", "ItemOfInterestName":"Deutsch Test" } ], "InterestItemTags": [ { "TagName":"best", "ItemOfInterest":"T3320190325153242" }, { "TagName":"gallo d'oro", "ItemOfInterest":"T3320190325153242" } ], "InterestItemProdCats": [ { "ProductCategoryHierarchy":"TEAM_WDF02_JS", "ProductCategory":"IOI_API_CAT_MM20190325153228", "ItemOfInterest":"T3320190325153242" }, { "ProductCategoryHierarchy":"TEAM_WDF02_JS", "ProductCategory":"IOI_API_CAT_oo20190325153229", "ItemOfInterest":"T3320190325153242" } ] } Create Interests (Non-Deep) BATCH Mode Sample Code Post: https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch POST data: --batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a 654 PUBLIC Integration Guide Integration APIs content-type: application/http content-transfer-encoding: binary POST InterestItems HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"ItemOfInterest":"T7720190325153247"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Create Interests (Non-Deep) Non-BATCH Mode POST: https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_INTEREST_SRV/ InterestItems POST data: {"ItemOfInterest":"T9920190325153230"} Create Interest Item Text Assignments in Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 POST InterestItemTexts HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"ItemOfInterest":"T93220190516122937","Language":"EN","ItemOfInterestName":"E nglish Text Assinment"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST InterestItemTexts HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"ItemOfInterest":"T93220190516122937","Language":"CS","ItemOfInterestName":"C zech test"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Integration Guide Integration APIs PUBLIC 655 Create Interest Item Text Assignments in Non-Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/InterestItemTexts POST data: {"ItemOfInterest":"T91720190516123049","Language":"EN","ItemOfInterestName":"E nglish Text Assinment"} Create Interest Item tag Assignments in Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 POST InterestItemTags HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"ItemOfInterest":"T67620190516123147","TagName":"#sapbyd"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http content-transfer-encoding: binary POST InterestItemTags HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"ItemOfInterest":"T67620190516123147","TagName":"hamburg"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Create Interest Item tag Asssignments in Non-Batch Mode POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/API_MKT_INTEREST_SRV/ InterestItemTags POST data: {"ItemOfInterest":"T0020190516123150","TagName":"#sapbyd"} 656 PUBLIC Integration Guide Integration APIs Create Interest Item Product Category Assignments in Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 POST InterestItemProdCats HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"ItemOfInterest":"T60020190516123503","ProductCategoryHierarchy":"TEAM_WDF02_ JS","ProductCategory":"IOI_API_CAT_8820190516123502"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Create Interest Item Product Category Assignments in Non-Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/InterestItemProdCats POST data: {"ItemOfInterest":"T0020190516123506","ProductCategoryHierarchy":"TEAM_WDF02_J S","ProductCategory":"IOI_API_CAT_9920190516123503"} Delete Interest items in Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 InterestItems(ItemOfInterest='T24420190516122658') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a content-type: application/http Integration Guide Integration APIs PUBLIC 657 content-transfer-encoding: binary DELETE InterestItems(ItemOfInterest='T25520190516122658') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Delete Interest items in Non-Batch Mode Sample Code HTTP Method: DELETE http://ldciabd.wdf.sap.corp:50000/sap/opu/odata/SAP/API_MKT_INTEREST_SRV/ InterestItems(ItemOfInterest='T24420190515131554') Delete Interest Items Text Assignment in Batch Mode Sample Code Delete IOI- Text Batch Mode: POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 InterestItemTexts(ItemOfInterest='T93220190927151105',Language='EN') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Delete Interest Item Text Assignment in Non-Batch Mode Sample Code DELETE https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/ InterestItemTexts (ItemOfInterest='T887720190927151109', Language='EN') 658 PUBLIC Integration Guide Integration APIs Delete Interest Item Tag Assignments in Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 InterestItemTags(ItemOfInterest='T11223320190927151108',TagName='tagtodelete') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Delete Interest Item tag Assignments in Non-Batch Mode Sample Code DELETE https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/ InterestItemTags(ItemOfInterest='T887720190927151109',TagName='tagtodelete') Delete Interest Item Product Category Assignments in Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 InterestItemProdCats(ItemOfInterest='T60020190927151058',ProductCategory='IOI_ API_CAT_8820190927151027',ProductCategoryHierarchy='TEAM_WDF02_JS') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a-- Integration Guide Integration APIs PUBLIC 659 --batch-- Delete Interest Item Product Category Assignments in Non-Batch Mode Sample Code DELETE https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/ InterestItemProdCats (ItemOfInterest='T887720190927151109',ProductCategory='IOI_API_CAT_88201909271 51027',ProductCategoryHierarchy='TEAM_WDF02_JS') Update Interest Text Assignments in Batch Mode Sample Code POST https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/$batch 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 PATCH InterestItemTexts(ItemOfInterest='T93220201215103449',Language='AR') HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json {"ItemOfInterestName":"Batch Update AR Text Assinment"} --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- Update Interest Text Assignments in Non-Batch Mode Sample Code PATCH https://wdciwe1.wdf.sap.corp:60100/sap/opu/odata/sap/ API_MKT_INTEREST_SRV/ InterestItemTexts(ItemOfInterest='T93220201215103449',Language='EN') PATCH data: {"ItemOfInterestName":"NonBatch Update English Text Assinment"} 660 PUBLIC Integration Guide Integration APIs 5.2.10 Business Documents 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. Note We recommend using the current version 0003 of this service. If you want to use version 0001 or version 0002, you'll find more information under: Version 0001: Business Documents API, Version 0001 Version 0002: Business Documents API, Version 0002 . Communication Scenarios CUAN_BUSINESS_DOCUMENT_IMP_SRV can be used in the following communication scenarios: Communication Scenario SAP_COM_0017 Marketing SAP_COM_0060 Marketing SAP_COM_0082 Marketing SAP_COM_0329 Marketing Description Presales/Sales Integration ERP Order and Business Partner Integration SAP Commerce Data Integration Business Document Interaction Integration For more information on how to set up the communication scenarios, see Communication Management. 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/ CUAN_BUSINESS_DOCUMENT_IMP_SRV /$metadata?sapdocumentation=all Only for internal access. You need to provide the server and port names. Integration Guide Integration APIs PUBLIC 661 Access Link Remarks Import of Business Documents 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. Business Documents OData API General access link takes you directly to the Business Documents metadata file. One-time registration or logon is required. 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]. 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 Overview [page 662] Import of business documents to marketing using the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV (Version 3). Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV [page 664] Basic Concepts [page 672] Modes [page 674] Specifics for SAP Cloud for Customer Integration [page 677] Payload Examples for Business Documents [page 678] This section contains payload examples for CUAN_BUSINESS_DOCUMENT_IMP_SRV. 5.2.10.1 Overview Import of business documents to marketing using the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV (Version 3). The OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV is used to import business documents from external systems, that is SAP systems or non-SAP systems, into SAP Marketing Cloud . Each business 662 PUBLIC Integration Guide Integration APIs document is represented by an interaction and is identified by the key of the business document in the external system. The OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV supports the change of interactions. Furthermore, the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV is used for standard SAP Marketing Cloud integration with SAP Cloud for Customer. It is used in marketing-driven, and sales-driven processes to replicate SAP Cloud for Customer business documents to SAP Marketing Cloud interactions. Note In standard SAP Marketing Cloud integration with SAP Cloud for Customer OData service CUAN_BUSINESS_PARTNER_IMP_SRV is used to replicate customers of SAP Cloud for Customer to SAP Marketing Cloud contacts. Within marketing-driven processes, SAP Marketing Cloud campaign actions are used to create business documents in SAP Cloud for Customer (leads, appointments, phone calls, and tasks). For each SAP Cloud for Customer business document, an SAP Marketing Cloud interaction is created in the campaign action. The business document of SAP Cloud for Customer is created with reference to the SAP Marketing Cloud interaction, that is, it stores the IDs of the SAP Marketing Cloud interaction and campaign. When an SAP Cloud for Customer business document is created, a confirmation message is returned, mapped to OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV, and the SAP Marketing Cloud interaction is updated with the IDs of the SAP Cloud for Customer business document. Within sales-driven processes, SAP Cloud for Customer business documents (leads, opportunities, appointments, visits, and phone calls) can be replicated to SAP Marketing Cloud to create corresponding interactions. Whenever a business document is created, or changed the Simple Object Access Protocol (SOAP) outbound service request message is triggered containing all business document data and mapped in SAP Cloud Integration middleware to OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV. Request messages are also created in marketing-driven processes whenever the business document created via a campaign action is changed afterwards. Parent topic: Business Documents [page 661] Related Information Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV [page 664] Basic Concepts [page 672] Modes [page 674] Specifics for SAP Cloud for Customer Integration [page 677] Payload Examples for Business Documents [page 678] Integration Guide Integration APIs PUBLIC 663 5.2.10.2 Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV The CUAN_BUSINESS_DOCUMENT_IMP_SRV (Version 3) OData service consists of the following entity sets and entity types: Entity Sets and Entity Types Entity Set Entity Type Entity Type Description ImportHeaders ImportHeader Technical Import Message Header BusinessDocuments BusinessDocument Business Document ProductItems ProductItem Product Items Offers Offer Offers AdditionalObjectReferences AdditionalObjectReferenc Additional object reference of an interaction e ProductCategories ProductCategory Product Category MarketingArea MarketingArea Marketing Area LoyaltyProgram LoyaltyProgram Loayalty Program AdditionalInteractionConta AdditionalInteractionCon Additional Interaction Contact cts tact Note If you use OData in SAP Cloud Integration then fill the key fields with an initial value. This is required since the OData adapter requires that mandatory OData fields are filled. Entity Types ImportHeader The entity type ImportHeader describes the technical header of an import of multiple business documents. The properties ID and Timestamp are used for logging the external data request. If an error occurs during the posting of the business documents, additionally 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]. If no ID or timestamp values are provided, they are defaulted internally. If you do provide an ID, it must be unique. 664 PUBLIC Integration Guide Integration APIs The SourceSystemID and SourceSystemType properties allow you to distinguish between different source systems. The SourceSystemID and SourceSystemType are mandatory attributes. This is the semantic key of an interaction with the communication medium BUSINESS_DOCUMENT. Note The value C4C for the SourceSystemType is exclusively for the integration to SAP Cloud for Customer. Properties of ImportHeader 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 x x run SourceSystemTy Type of the source Edm.String 20 x x pe system, that is ERP SourceSystemId Identifier of the Edm.String 23 x x source system BusinessDocument For each ImportHeader, several business documents can be passed. BusinessDocument is mapped to interactions. Properties of BusinessDocument Property Description Edm Core Type Max Length Mandatory Key ID Key of the interac Edm.Guid 0 x x tion that is up dated. Only man datory when ActionCode = 02 Integration Guide Integration APIs PUBLIC 665 Property Description Edm Core Type Max Length Mandatory Key ContactIDOrigi ID origin of the Edm.String 20 X1 n contact. If the ContactID is fil- led the ID origin from the external system must be set, that is, SAP_C4C_BUPA. Mandatory when ActionCode = 04 ContactId ID of the contact in Edm.String 255 X1 the external sys tem. Mandatory when ActionCode = 04 InternalContac obsolete tID Edm.String 255 InternalObject Interaction type Edm.String 20 X1 Type only mandatory when ActionCode = 04 ExternalObject Type of the exter Edm.String 30 x Type nal object, that is, MARKETING_LEAD ExternalId ID of the external Edm.String 50 x object ExternalStatus Status of the ex Edm.String 2 Code ternal object ExternalTimeSt Timestamp of the Edm.DateTimeOff- 2 x amp external object. set Timestamp is used to process mes sages in the right sequence Content Long description Edm.String 0 of the external ob ject ExpectedRevenu Expected revenue Edm.Decimal 31,2 e of an opportunity 666 PUBLIC Integration Guide Integration APIs Property Description Edm Core Type Max Length Mandatory Key Currency Currency of the Edm.String 5 amount fields. Must be set if ExpectedRevenu e or Amount is fil- led PredecessorId Lead predecessor Edm.String 50 ID can be passed. Campaign is cop ied from predeces sor document. Can only be used on request mode. ActionCode The action code Edm.String 2 x controls how an in teraction is posted. The follow ing values are sup ported: 02 confirmation mode 04 request mode 05 remove ContentTitle Short description Edm.String 255 of the external ob ject EndTimeStamp Reason End Time Stamp Reason Edm.DateTimeOff- 0 set Edm.String 20 ExternalAdditi Additional ID of the Edm.String 50 onalId external object Amount Amount of the ex Edm.Decimal 0 ternal object. Cur rency field must be filled if amount is populated. Integration Guide Integration APIs PUBLIC 667 Property Description Edm Core Type Max Length Mandatory Key StatusCode Timestamp CampaignId Internal status of Edm.String 2 the interaction. The following sta tuses are defined: 00 New 01 In Process 02 Released 03 Completed 04 Canceled 05 Converted 06 Successful 07 Unsuccessful Timestamp of ex Edm.DateTimeOff- 0 ternal object in the source system, set that is, order date. Filled with ExternalTimeSt amp if empty SAP Marketing Edm.String 10 Cloud Campaign ID If a campaign ID is passed the field PredecessorId is not evaluated. For more information, see Modes [page 674], section PredecessorId (Marketing-Driven Process) MarektingAreaI Marketing area ID Edm.String 40 d of the interaction MarketingLocat Marketing location Edm.String 50 ion ID of the interac tion MarketingLocat Origin of market Edm.String 30 ionOrigin ing location ID 668 PUBLIC Integration Guide Integration APIs Property Description Edm Core Type Max Length Mandatory Key MKT_AgreementO Agreement Origin Edm.String 30 rigin MKT_AgreementE Agreement Exter Edm.String 80 xternalID nal ID InteractionProces Processing time in Edm.Int32 0 singDuration seconds InteractionPriority Priority Edm.String 1 Note The value X1 is only mandatory when the field ActionCode has the value 04. ProductItem Several product items can be passed per business document. Properties of Entity Type ProductItem Property Description Edm Core Type Max Length Mandatory Key Id Item number for Edm.String 32 X1 x product item from external system ObjectType Object type from Edm.String 30 x x external system, that is, SAP_C4C_PRODUC T ObjectId Product key from Edm.String 50 x external system Amount Amount of prod Edm.Decimal 31,2 uct. Currency in formation is de rived from as signed interaction- Quantity Quantity of prod uct Edm.Decimal 22,5 Unity of Measure Unit of product Edm.String 3 With version 3 of CUAN_BUSINESS_DOCUMENT_IMP_SRV, a product cannot be created as a master product. The product must exist in the system. It has to be imported beforehand using one of the provided services, for example, API_MKT_PRODUCT. The properties ObjectType and ObjectID refer to the properies ProductType Integration Guide Integration APIs PUBLIC 669 and ProductID of the service API_MKT_PRODUCT. If you upload a product that does not yet exist in the system you will receive an error. X1 initial value can be passed. The value of the field is not persisted. Offer Several Offers can be passed per business document. The system determines the corresponding Offer ID and Coupon ID only when the ExternalObjectType is SALES_ORDER. In the case of all other external object types the data sent is stored unchecked, exactly as it is provided. The system does not determine the Offer ID or the Coupon ID. Properties of Entity Type Offer Property Description Edm Core Type Max Length Mandatory Key ExternalOfferO Origin of the offer Edm.String 30 x x rigin ExternalOffer Identifier of the ex Edm.String 60 x x ternal offer MarketingOffer ID of the market Edm.String 10 ing offer MarketingOffer Content Item Edm.String 5 Content Number Coupon Coupon Edm.String 32 CouponCodeType Coupon Code Type Edm.String 1 CouponCode Coupon Code Edm.String 128 NumberOfRedemp Number of Re tion demption Edm.Int32 Additional Object Reference With entity type AdditionalObjectReference, several additional object references per business document can be passed. Properties of Entity Type AdditionalObjectReference Property Description Edm Core Type Max Length Mandatory Key ObjectType Type of the object Edm.String 30 x x referenced ObjectId ID of the object ref 50 50 x x erenced Product Category With entity type ProductCategory, several product categories per business document can be passed. 670 PUBLIC Integration Guide Integration APIs Properties of Entity Type ProductCategory Property Description Edm Core Type Max Length Mandatory Key Id ID of the product Edm.String 50 x x category Hierarchy ID of product cate 50 50 x x gory hierarchy Before you can upload references of product categories that are assigned to business documents, the master data of the product category and product category hierarchy must be uploaded. Marketing Area This entity can only be used in standard SAP Marketing Cloud integration with SAP Cloud for Customer for replication of leads. For more details see Specifics for SAP Cloud for Customer Integration [page 677] Several marketing areas per business document can be passed. Property Description Edm Core Type Max Length Mandatory Key MarketingAreaI Marketing Area Id Edm.String 40 x x d Before you can upload references of product categories that are assigned to business documents the master data of the product category, and product category hierarchy must be uploaded. Loyalty Program With entity type LoyaltyProgram, several Loyalty Programs can be passed per business document entity. Properties of Entity Type LoyaltyProgram Property Description Edm Core Type Max Length Mandatory Key LoyaltyUUID Loyalty Program Edm.Guid 0 GUID X1 X ActivitySubtyp Loyalty Activity Edm.String 255 e Subtype AccruedPoints Accrued Loyalty Edm.Decimal 31,2 Points RedeemedPoints Redeemeed Loy Edm.Decimal 31,2 alty Points QualifyingPoin Qualifying Loyalty Edm.Decimal 31,2 ts Points X1 Initial GUID must be passed "00000000-0000-0000-0000-000000000000". Additional Interaction Contacts With entity type AdditionalInteractionContact, several additional interaction contact references can be passed per business document entity. So, serveral interaction contacts can be assigned to one interction. The Integration Guide Integration APIs PUBLIC 671 referenced interaction contact must exist. If the contact does not exist message status is set to blocked and the message is reprocessed. A contact might not exists because the master data message for the interaction contact is delayed. Properties of Entity AdditionalObjectReference Property Description Edm Core Type Max Length Mandatory Key InteractionAdd Interaction Addi Edm.Guid 0 itionalIntactn tional Interaction ContactUUID Contact UUID X1 X ActiInteractio Contact Origin Edm.String 20 nContactOrigin vitySubtype InteractionCon Contact Id tactId Edm.Decimal 255 InteractionCon Interaction Con Edm.Guid 0 tactUUID tact UUID X1 Initial GUID must be passed "00000000-0000-0000-0000-000000000000". Parent topic: Business Documents [page 661] Related Information Overview [page 662] Basic Concepts [page 672] Modes [page 674] Specifics for SAP Cloud for Customer Integration [page 677] Payload Examples for Business Documents [page 678] 5.2.10.3 Basic Concepts The OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV (Version 3) supports only the method deep create on the entity type ImportHeader and the dependent entity type BusinessDocument. Other methods, such as create, update or delete are not supported. The field ActionCode controls how a BusinessDocument is processed. For more information, see Modes [page 674]. OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV supports one message of the entity type ImportHeader with multiple lines of the entity type BusinessDocument. Up to 10,000 business documents can be sent at once with the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV. Update Logic 672 PUBLIC Integration Guide Integration APIs You must send a complete snapshot of the data every time. It is not possible to send only data that has changed with respect to a previous state. A new upload always overwrites the existing record. The snapshot must also contain all entries for all sub-entity sets, for example, ProductItems, Offers, and AdditionalObjectReferences. If no entries are provided for a sub-entity set, any existing entries are deleted. Timestamp The Attribute ExternalTimeStamp of entity BusinessDocument defines when the business document was last changed or created. Before updating the record, the system compares the timestamp (TIMESTAMP) of the interaction in SAP Marketing Cloud and the timestamp of the incoming message (ExternalTimeStamp). Outdated messages, where the value of the field ExternalTimeStamp is lower than the field TIMESTAMP of the interaction, are ignored since changes are already stored, and the most recent interaction carries the complete and most recent snapshot data. Error Handling If the OData service is not accessible (for example no authorization, system not available, too many business documents sent) a corresponding HTTP status code is returned. After the OData service has been accepted by the Gateway component in SAP Marketing Cloud , the HTTP status code 201 is always returned. Any processing errors are recorded in the SAP Marketing Cloud system and can be monitored, restarted, or discarded in the Import Monitor app. For more information see, Import Monitor [page 404] and HTTP Response Status Codes [page 408]. Semantic Key This refers to the semantic key of an interaction that has the communication medium BUSINESS_DOCUMENT. The external key of a BusinessDocument entity is defined by unique combination of the fields: SourceSystemId SourceSystemType ExternalObjectType ExternalObjectId Parent topic: Business Documents [page 661] Related Information Overview [page 662] Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV [page 664] Modes [page 674] Specifics for SAP Cloud for Customer Integration [page 677] Payload Examples for Business Documents [page 678] Integration Guide Integration APIs PUBLIC 673 5.2.10.4 Modes As described in the overview chapter, the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV supports confirmation and request messages. In request mode, messages are processed that import (create, update, or delete) interactions. The messages are triggered by changes in the external system. The confirmation mode is used in marketing-driven scenarios to confirm messages that were sent to external systems. The confirmation message mainly contains the key of the business document in the external system. The different modes are defined by attribute ActionCode in entity BusinessDocument. Action code 04 defines creation or update in request mode. Action code 05 defines deletion in request mode. Action code 02 defines the update of an interaction by the external key in confirmation mode. Customer enhancements are only supported when the field ActionCode has the value 04. See the following chapters for more details. Request Mode: Create and Update (ActionCode 04) The external key (see table below) of the business document is used to check the existence of an interaction in SAP Marketing Cloud . If an interaction is found it is updated. If no interaction is found an interaction is created. The Attribute Id is optional, and only relevant for marketing-driven processes. For more information, see Overview [page 662]. If additionally the optional Attribute Id is provided an additional search step is performed in case no interaction with fitting external key was found. The Attribute Id is used to retrieve an interaction by its internal key. If an interaction is found it is updated. If no interaction is found an error is raised and the corresponding message can be found in the Import Monitor app. The following table provides you with an overview of mandatory attributes and the definition of the key of the external business document. Entity Property Description Mandatory Key Import Header Id Unique technical identifier of import x run Timestamp Timestamp of the run SourceSystemType Type of the source system, such as x x ERP SourceSystemId Identifier of the source system x x BusinessDocument Id Key of the interaction that is updated. 674 PUBLIC Integration Guide Integration APIs Entity Property Description Mandatory Key ContactIdOrigin ID origin of the contact. If the Contac x tID is filled the ID Origin from the ex ternal system must be set, such as SAP_C4C_BUPA. ContactId Id of the contact in the external sys x tem. InternalObjectType Interaction type only mandatory for x request mode ExternalObjectType Type of the external object, such as x x MARKETING_LEAD ExternalId ID of the external object x x ExternalTimeStamp Timestamp of the external object. x Timestamp is used to process mes sages in the right sequence ActionCode 04 x The main contact of the business document is defined by attribute pair ContactIDOrigin and ContactId. If no contact with this attribute pair (facet) exists in SAP Marketing Cloud a new contact is created. Contact data itself is replicated separately via, for example, OData service CUAN_BUSINESS_PARTNER_IMP_SRV. PredecessorId (Marketing-Driven Process) The attribute PredecessorId is only relevant for marketing-driven processes. If it is filled a predecessor lead interaction is determined and the ID of the campaign in which the lead predecessor interaction was created is copied to the current interaction to be created or updated. The external key of the predecessor lead interaction is defined by attributes SourceSystemType, SourceSystemId, ExternalObjectType, and ExternalId. SourceSystemType and SourceSystemId are taken from entity ImportHeader, ExternalID is given by value of PredecessorId in entity BusinessDocument and ExternalObjectType is fixed to value "MARKETING_LEAD". If no predecessor lead interaction is found an error is raised which can be seen in the Import Monitor app. Request Mode: Delete (ActionCode 05) If a business document is deleted in external system then action code "05" has to be used. An interaction is determined according to the rules described under Request Mode: Create and Update (ActionCode 04). Integration Guide Integration APIs PUBLIC 675 If an interaction is found the interaction is not removed from database. A so called obsolete flag is set for the interaction. The interaction can then be deleted in a subsequent step by standard deletion reports. Besides ExternalTimeStamp and the obsolete flag no other interaction data is updated. If no interaction is found an error is raised which is logged and can be seen in Import Monitor app. Note A of release 1902, the obsolete flag is not set, but the interaction is deleted physically from the database. Confirmation Mode: Set External Keys (ActionCode 02) If the field action code has the value "02" the OData service is executed in confirmation message mode. The confirmation mode is only relevant for marketing-driven processes. The main purpose of the confirmation message process step is to update existing interaction with the external business document key. Only a small subset of fields contained in table below are taken into account in confirmation message mode. Entity ImporHeader BusinessDocument Property Description Mandatory Id Unique technical iden x tifier of import run TimeStamp Timestamp of the run SourceSystemType Type of the source sys x tem, such as ERP SourceSystemId Identifier of the source x system Id Internal key of the in x teraction that is to be updated ExternalObjectType ExternalId ExternalTimeStamp Type of the external x object, such as MAR KETING_LEAD ID of the external ob x ject Timestamp of the ex x ternal object. Time stamp is used to proc ess messages in the right sequence External Key x x x x 676 PUBLIC Integration Guide Integration APIs Entity Property Description Mandatory External Key ActionCode 02 x The Property Id denoting the internal Id of the interaction is used to retrieve an existing interaction. If the interaction cannot be retrieved an error is raised and logged in the Import Monitor app. If the interaction can be retrieved then the mentioned fields above are updated in the interaction. Parent topic: Business Documents [page 661] Related Information Overview [page 662] Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV [page 664] Basic Concepts [page 672] Specifics for SAP Cloud for Customer Integration [page 677] Payload Examples for Business Documents [page 678] Import Monitor [page 404] 5.2.10.5 Specifics for SAP Cloud for Customer Integration Some specifics have to be considered for SAP Cloud for Customer Integration. SAP Cloud for Customer integration is defined by SourceSystemType C4C. Entity Type ProductItem If the field ObjectId is initial the corresponding product item is neglected and no error is raised. Parent topic: Business Documents [page 661] Related Information Overview [page 662] Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV [page 664] Basic Concepts [page 672] Modes [page 674] Payload Examples for Business Documents [page 678] Integration Guide Integration APIs PUBLIC 677 5.2.10.6 Payload Examples for Business Documents This section contains payload examples for CUAN_BUSINESS_DOCUMENT_IMP_SRV. Sales-Driven Process - Create or Change Business Document Sample Code { "Id": "Timestamp": "2019-08-20T12:36:04.0000000", "SourceSystemType": "SourceSystemId": "BusinessDocuments": [ { "Id": "InternalObjectType": "ExternalObjectType": "ExternalId": "ExternalStatusCode": "ContactIdOrigin": "ActionCode": "ContactId": "ExternalTimeStamp": } ] } "MSG_20190820_I", "C4C", "Z123", "00000000-0000-0000-0000-000000000000", "MARKETING_LEAD", "MARKETING_LEAD", "LEAD_20190820_I", "1", "SAP_C4C_BUPA", "04", "IC_20190820_I ", "2019-08-25T12:55:59.0000000" Sales-Driven Process - Create or Change Business Document with Product Items Sample Code { "Id": "Timestamp": "2019-08-20T12:36:04.0000000", "SourceSystemType": "SourceSystemId": "BusinessDocuments": [ { "Id": "InternalObjectType": "ExternalObjectType": "ExternalId": "ExternalStatusCode": "ContactIdOrigin": "ActionCode": "ContactId": "ExternalTimeStamp": "ProductItems": [ { "MSG_20190820_II", "C4C", "Z123", "00000000-0000-0000-0000-000000000000", "MARKETING_LEAD", "MARKETING_LEAD", "LEAD_20190820_II", "1", "SAP_C4C_BUPA", "04", "IC_20190820_II", "2019-08-25T12:55:59.0000000", 678 PUBLIC Integration Guide Integration APIs } } } "Id" : "10", "ObjectId": "MAT_20180420_II ", "ObjectType": "SAP_C4C_PRODUCT", "ProductName": "Camera", "ProductDesc": "Camera", "Quantity": "5", "UnitOfMeasure": "ST" ] ] Sales-Driven Process Create or Change Business Document with Additonal Interaction Contacts Sample Code { "Id": " MSG_20190820_III ", "Timestamp": "2019-08-20T12:36:04.0000000", "SourceSystemType": "C4C", "SourceSystemId": "Z123", "BusinessDocuments": [ { "Id": "00000000-0000-0000-0000-000000000000", "InternalObjectType": "MARKETING_LEAD", "ExternalObjectType": "MARKETING_LEAD", "ExternalId": " LEAD_20190820_III", "ExternalStatusCode": "1", "ContactIdOrigin": "SAP_C4C_BUPA", "ActionCode": "04", "ContactId": "IC_20190820_III", "ExternalTimeStamp": "2019-08-02T19:38:16.0000000", "TimeStamp": "2019-08-16T16:36:04.0000000", "AdditionalInteractionContacts": [ { "InteractionAdditionalIntactnContactUUID": "00000000-0000-0000-0000-000000000000", "InteractionContactOrigin": "SAP_C4C_BUPA", "InteractionContactId": " IC_20190820_IV " }, { "InteractionAdditionalIntactnContactUUID": "00000000-0000-0000-0000-000000000000", "InteractionContactOrigin": "SAP_C4C_BUPA", "InteractionContactId": " IC_20190820_V " } ] } ] } Integration Guide Integration APIs PUBLIC 679 Create Business Document with an Offer Sample Code POST data: { "Id": " MSG_20201221_II", "Timestamp": "2020-12-21T15:39:36.0000000", "SourceSystemType": "C4C", "SourceSystemId": " Z123", "BusinessDocuments": [ { "Id": "00000000-0000-0000-0000-000000000000", "InternalObjectType": "SALES_ORDER", "ActionCode": "04", "ExternalObjectType": "SALES_ORDER", "ExternalId": "BUS-JMT ", "StatusCode": "06", "ContactIdOrigin": "SAP_C4C_BUPA", "ContactId": "JMT_ContactID", "ExternalTimeStamp": "2020-11-25T09:12:00.0000000", "MarketingAreaId": "MA01", "Currency": "EUR", "Offers": [ { "ExternalOfferOrigin": "GENERIC", "ExternalOffer": " Ext_Offer", "CouponCode": "CpnCode" } ] } ] } Parent topic: Business Documents [page 661] Related Information Overview [page 662] Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV [page 664] Basic Concepts [page 672] Modes [page 674] Specifics for SAP Cloud for Customer Integration [page 677] 680 PUBLIC Integration Guide Integration APIs 5.2.11 Agreements 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. Overview The OData service API_MKT_AGREEMENT_SRV is used to replicate agreement data from different source systems into SAP Marketing Cloud (standard integration with other systems). One agreement instance can only have one origin system for its business data. However, to identify business documents from other systems, you can replicate additional external IDs with different origins of an agreement. OData Version Root URI Service Metadata URI Communication Scenario ID Authorization Component for Incidents 2.0 https://{host}:{port}/sap/opu/odata/sap/API_MKT_AGREE MENT_SRV https://{host}:{port}/sap/opu/odata/sap/API_MKT_AGREE MENT_SRV/$metadata SAP_COM_0175 The following business catalog is required: SAP_CEC_BC_MKT_API_AGR_PC CEC-MKT-DM-AGR (Agreement) Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Field Extensibility Supported Yes Note You must enable the Data Source under UIs and Reports for Data SourceAPI_MKT_AGREEMENT_SRV 0001 (API for Marketing Agreement) and I_MKT_AGREEMENTTP (Marketing: Agreement TP). For more information, seeAgreements. Integration Guide Integration APIs PUBLIC 681 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 https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_AGREEMENT_SRV/ $metadata?sapdocumentation=all Marketing - Agreements Details Page Agreements API Remarks Only for internal access. You need to provide the server and port names. 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. General access link takes you directly to the Agreements 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 5.2.11.1 Basic Concepts This OData API allows updates of agreements from different source systems. OData Operations Supported This OData API supports the following operations: The operation GET is supported for all entities. $batch processing is only supported for updates. Within a batch request, only the following operations are supported: PATCH(MERGE)for the entity types Agreement and AgreementTerms PUT/DELETE for entity type AgrmtAdditionalExtID 682 PUBLIC Integration Guide Integration APIs Batch requests allow multiple operations to be grouped 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 as well as a boundary specification. Important Points to Note About Processing A PATCH (MERGE) request only updates the properties indicated in the request body and leaves everything which was not mentioned untouched. 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 an agreement cannot be found based on its external key (MKT_AgreementOrigin and MKT_AgreementExternalID), the PATCH request creates a new agreement. Create Agreements with Agreement Terms: Although it is technically possible to create a root entry / Agreement without the corresponding entry for the /AgreementTerms, this would be semantically incorrect and these entries would not be usable in the segmentation and should therefore be avoided. A root entry without terms can only exist temporarily in the system due to a time lag between the creation of both entities. Segmentation only checks the timestamp of the Agreement Terms, not of the Agreement. Timestamps must always be loaded in the API service in UTC format, they are not automatically converted to UTC in the service. In Segmentation and Analytics, UTC timestamps are then converted to local time. Contacts are enhanced with the marketing area assignment that is used in the agreement. Checks When an agreement is created or changed, the system performs checks for mandatory fields, field values and the existence of referenced entities. Failing checks results in an error and the incorrect data sets are displayed in the import monitor. For detailed information, refer to the details of each entity type in the section Structure of OData Service API_MKT_AGREEMENT_SRV [page 684]. Agreement Bundles You can implement the hierarchical relationships of agreements as bundles. An agreement may have a relation to a bundle (=related bundle). The bundle is an agreement itself. An agreement with such a relation is called a bundle member. For more information, see Agreements There are no checks between the agreement bundle and the members of the agreement bundle. The source system needs to synchronize the data between the agreement bundle and its members if needed. For example, if a reference to a bundle product is replicated via the terms of the members of the agreement bundle, the source system should replicate any change of the product in the agreement bundle and update the terms of the corresponding members of the agreement bundle. Update Logic for Agreement Terms When an agreement terms record is uploaded, it is compared to the relevant existing agreement terms records on the database. If the imported agreement terms record has the same start and end date as the existing agreement terms record, then the existing record is updated by the new record. Otherwise a new agreement terms record is created. Inactive Terms: Any existing agreement terms record that overlaps with the new record is given the status Inactive = I. Inactive agreement terms are filtered out by default in the standard Analytics and Segmentation delivered, so that they do not clutter up the display. So, if you create custom Analytics or Segmentation, you should make sure to select Agreement Terms with the status Active = A only. Inactive agreement terms cannot be reactivated. Although they are not deleted in the database, they are excluded from usage. Integration Guide Integration APIs PUBLIC 683 Note The PATCH request updates only the properties transmitted in the request body. All properties that are not to be changed can be omitted. The transmitted properties are merged with the data already stored. The following examples illustrate the update logic when a new Agreement Term is uploaded for an Agreement for which there are existing Agreement Terms: Examples of Update Logic Validities of Existing Terms New Term with New Validity Update Logic 01.01.2016 to 31.12.2016 01.01.2017 to 31.12.2017 01.01.2018 to 31.12.2018 01.07.2016 to 31.07.2018 1. A new term is created. 2. All existing terms with overlapping validities are set to inactive. Note If you want the agreement term to remain valid in the Marketing sys tem for the periods 01.01.2016 to 31.06.2016 and 01.08.2018 to 31.12.2018, then you have to upload new agreement terms for these two periods to the Marketing system. 01.01.2016 to 31.12.2016 01.01.2017 to 31.12.2017 01.07.2016 to 31.07.2017 This new term invalidates both of the existing terms. The old terms are set to inactive. Note If you want the agreement term to remain valid in the Marketing sys tem for the periods 01.01.2016 to 31.06.2016 and 01.08.2017 to 31.12.2017, then you have to upload new agreement terms for these two periods to the Marketing system. 5.2.11.2 Structure of OData Service API_MKT_AGREEMENT_SRV This document describes the structure of the Public OData API service API_MKT_AGREEMENTS. Make sure you read the information in the topic Basic Concepts [page 682] before you start. 684 PUBLIC Integration Guide Integration APIs 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. Header Field Description Edm Core Type Sap-CuanSequenceId Sap-CuanRequestTimestamp Unique technical iden tifier of the imported data Edm.String OData service Edm.DateTime Timestamp of the data 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 data received. Data with the same Sap-cuanSequenceID and 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. The Sap-Cuan-ExternalReferenceId and Sap-Cuan-ExternalDocumentId allow better error analysis because they contain external references to a source SOAP message or an IDoc. Integration Guide Integration APIs PUBLIC 685 Entity Sets and Entity Types in API MKT_Agreement_SRV The API MKT_AGREEMENT_SRV OData service consists of the following entity sets and entity types: Entity Set Agreements AgreementTerms AgrmtAdditionalExtIDs Description Path Agreement time independent attributes /Agreements refer to agreements in SAP Marketing Cloud. Agreement data is collected and merged from several sources into the master data tables within SAP Marketing Cloud. Agreement time-dependent attributes representing agreement terms (condi tions) for a particular time slice of an agreement. /AgreementTerms Additional external ID of the agreement /AgrmtAdditionalExtIDs from a different agreement origin. Agreement additional external IDs are optional. They are used in a scenario, when interactions are linked to agree ments by using an alternative key (e.g. the agreement additional external ID is stored in the interaction). In this case the mapping of the alternative agree ment key to the primary agreement key is done here. Agreement You can perform the following operations on the Agreement entity set: GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_AGREEMENT_SRV/Agreement PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_AGREEMENT_SRV/ $batch HTTP Method GET Description Get a list of agreements. This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby Path /Agreements?$top=1 686 PUBLIC Integration Guide Integration APIs HTTP Method POST (Batch) Description Path Get a single agreement. / Agreements(MKT_AgreementOrigin= '<Agreement Origin>',MKT_AgreementExternalI D='<Agreement ID>') Update or create an Agreement in batch mode. (Full Update) See payload example: Payload Examples for Agreements [page 693] https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_AGREEMENT_SRV/$batch Agreement Property Description Edm. Core Type Max Length MKT_AgreementOrigin Agreement Origin. Edm.String 30 MKT_AgreementExternal Agreement External ID. ID Edm.String 80 MKT_AgrmtCancellation The customer or provider rea Edm.String 10 Reason son for canceling the agree ment. The reason also encodes which party triggered the can cellation. ContactID External ID of Interaction Con Edm.String 255 tact Data. ContactOrigin Origin of Interaction Contact Edm.String 20 Data. MKT_AgreementIsBundle The agreement represents an Edm.Boolean 0 agreement bundle. An agree ment bundle groups multiple agreements. An agreement bundle may con tain additional terms and itself have associated interactions. MKT_AgreementIsBundle Specifies whether this agree Edm.Boolean 0 Member ment is part of an agreement . MKT_AgreementType Used to categorize an agree Edm.String 10 ment. Example agreement types: loan, car insurance, life insurance, mobile phone, elec tricity supply. Mandatory Key x x x x x* x* x* Integration Guide Integration APIs PUBLIC 687 Property Description Edm. Core Type Max Length Mandatory Key MKT_MarketingArea Marketing Area of the Agree Edm.String 40 ment , may be used to restrict the access to agreements. MKT_AgreementStartDat The initial start date of the first Edm.DateTi 0 x* eTime version of the agreement. An meOffset agreement renewal, for exam ple, does not change this date. MKT_AgreementEndDateT Date at which the agreement Edm.DateTi 0 x* ime ends. If the contract is open meOffset ended, then the date shall be 31.12.9999. MKT_AgreementIsCancel The agreement is canceled. ed Edm.Boolean 0 OriginDataLastChgUTCD Last Change Timestamp of the Edm.DateTi ateTime source system. meOffset MKT_AgreementBundleOr Origin of the Agreement Bun Edm.String 30 igin dle. MKT_AgreementBundleEx External ID of the Agreement Edm.String 80 ternalID Bundle. MKT_AgrmtBundleStartD The start date and time of the Edm.DateTi 0 ateTime agreement bundle. meOffset MarketingLocationOrig Origin of Marketing Location Edm.String 30 in MarketingLocationExte ID of Marketing Location rnalID Edm.String 50 *If you update an existing agreement term with the same key, you can omit the properties ContactID, ContactOrigin, MKT_AgreementType, MKT_AgreementStartDateTime, and MKT_AgreementEndDateTime. In this case, the missing properties will be taken from the existing record. If you create a new agreement you must provide all mandatory properties. When a new agreement is created, the system checks whether this agreement already exists based on its external keys (MKT_AgreementOrigin and MKT_AgreementExternalID), for example, it checks whether the agreement is already referenced via an additional external ID in another agreement instance (MKT_AgrmtAddlExternalOrigin and MKT_AgreementAddlExternalID). If you want to control access to agreement information, you must ensure that marketing area information is part of the agreements payload. Field Value Checks in Agreement are performed for the following attributes: MKT_AgreementOrigin. MKT_AgreementBundleOrigin for Customizing values. 688 PUBLIC Integration Guide Integration APIs MKT_AgrmtCancellationReason for Customizing values. MKT_AgreementType for Customizing values. MKT_MarketingArea for Customizing values. MKT_AgreementStartDateTime before MKT_AgreementEndDateTime. The following dependencies are verified: The referenced marketing location has to exist. The referenced interaction contact has to exist. Note The contact is enhanced with the assignment to the marketing area that is used in the agreement. AgreementTerms You can perform the following operations on the AgreementTerms entity set: GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_AGREEMENT_SRV/ AgreementTerms PATCH in batch: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_AGREEMENT_SRV/ $batch HTTP Method GET POST (Batch) Description Path Get a list of Agreement Terms. /AgreementTerms?$top=1 This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby Get one single Agreement Term. Update or create Agreement Terms in batch mode. (Full Update) See payload example: Payload Examples for Agreements [page 693] / AgreementTerms(MKT_AgreementOri gin='<Agreement Origin>',MKT_AgreementExternalI D='<Agreement ID>',MKT_AgrmtTermsStartDateTim e=datetimeoffset'<Agreement Term Start DateTime>',MKT_AgrmtTermsEndDat eTime=datetimeoffset'<Agreement Term End DateTime>') https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_AGREEMENT_SRV/$batch Integration Guide Integration APIs PUBLIC 689 Agreement Terms Property Description EDM Core Type Max Length Mandatory Key MKT_AgreementOrigin Agreement Origin. Edm.String 30 x x MKT_AgreementExternalID Agreement External ID. Edm.String 80 x x MKT_AgrmtTermsStartDateTime The Start DateTime to End Edm.String 0 x x DateTime specify the period MKT_AgrmtTermsEndDateTime of which an agreement terms Edm.String 0 x x record is valid (agreement terms are time dependent). MKT_AgreementStatus The status of the agreement Edm.String 1 x* terms. ProductOrigin Product Origin. Edm.String 30 ProductID External ID of the Product. Edm.String 50 MKT_AgrmtCanclnConditions Code describing what condi Edm.String 10 tions must be met to cancel the agreement. MKT_AgrmtCanclnDcsnToDateTim The Customer must notify the Edm.DateTi 0 e provider about the cancella meOffset tion before this date.Other wise the contract will auto matically renew when the AgreementtEndDateTime is reached. MKT_AgreementRenewalType Agreement renewal type. Edm.String 0 MKT_AgrmtProlngnDcsnFromDteT The customer may request a Edm.DateTi 0 me prolongation of their agree meOffset ment between the dates AgreementProlongationDe cisionFromDateTime and AgreementEndDateTime. This is relevant for agree ments that do not automati cally renew. Mkt_AgrmtPaymentIsInAdvance Indicates that the customer Edm.Boolean 0 makes his payments in ad vance of the period of service. 690 PUBLIC Integration Guide Integration APIs Property Description EDM Core Type Max Length Mandatory Key MKT_AgreementPaymentFrequenc Code describing how often the Edm.String 4 y customer makes payments to the provider. Examples: Yearly, Monthly. MKT_AgrmtBundleProductOrigin Reference to the Product of an Edm.String 30 Mkt MKT_AgrmtBundleProductID Agreement Bundle. Edm.String 50 OriginDataLastChgUTCDateTime Last Change Timestamp of the source system in UTC. Edm.DateTi 0 meOffset * You can omit the property MKT_AgreementStatus if you update an existing agreement term with the same key. Then the status will be taken from the existing record. If you create a new agreement term you have to provide the agreement status. When a new agreement term is created, the system checks whether this agreement already exists using its external keys (MKT_AgreementOrigin and MKT_AgreementExternalID) . You need to create /Agreement (root entry) before you can create /AgreementTerms. Checks Performed Field Value checks in AgreementTerms are performed for the following attributes: MKT_AgrmtTermsStartDateTime before MKT_AgrmtTermsEndDateTime MKT_AgreementStatus for valid values: "A" - Active "S" - Suspended "Q" - Quote "P" - Application MKT_AgreementRenewalType for valid values: "" - Unknown "1" - No renewal possible "2" - Customer must request "3" - Automatic MKT_AgrmtCanclnConditons for Customizing values MKT_AgreementPaymentFrequency for Customizing values MKT_AgrmtCorrespondenceMedium for valid values: "EMAIL" - Email "FAX" - Fax "PAPER" - Postal Mail "SMS" - Text Message "WEB" - Online Account MKT_AgreementPaymentMethod for valid values: "DD" - Direct Debit "CC" - Credit Card Integration Guide Integration APIs PUBLIC 691 "BC" - Bank Collection "BT" - Bank Transfer The following dependencies are verified: The referenced product has to exist. The referenced bundle product has to exist. A bundle product can be referenced only if the agreement is a member of an agreement bundle. AgrmtAdditionalExtIDs You can perform the following operations on the AgrmtAdditionalExtIDs entity set: GET: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_AGREEMENT_SRV/ AgrmtAdditionalExtIDs PUT, PATCH, or DELETE in batch: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_AGREEMENT_SRV/$batch HTTP Method GET POST (Batch) Description Path Get a list of External Additional IDs. /AgrmtAdditionalExtIDs?$top=3 This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby Update or create an Agreement Additional Ex ternal ID with PATCH in batch mode. (Full Up date) https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_AGREEMENT_SRV/$batch Delete an Agreement Additional External ID with DELETE in batch mode. See payload ex ample: Payload Examples for Agreements [page 693] https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_AGREEMENT_SRV/$batch Add one new Agreement Additional External ID via PUT in batch mode. See payload exam ple: Payload Examples for Agreements [page 693] https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_AGREEMENT_SRV/$batch Property Description Edm Core Type Max Length Mandatory Key MKT_AgreementO Agreement Origin. Edm.String 30 x x rigin MKT_AgreementE Agreement Exter Edm.String 80 x x xternalID nal ID. 692 PUBLIC Integration Guide Integration APIs Property Description Edm Core Type Max Length Mandatory Key MKT_AgrmtAddlE Additional Agree Edm.String 30 x x xternalOrigin ment Origin. MKT_AgreementA Agreement Exter Edm.String 80 x x ddlExternalID nal ID from an Ad ditional Agree ment Origin. When a new additional external ID is created, the system checks based on its agreement external keys (MKT_AgreementOrigin and MKT_AgreementExternalID) whether this agreement already exists. You need to create /Agreement (root entry) before you can create /AgrmtAdditionalExtIDs. When a new additional external ID is created, the system checks based on its additional external keys (MKT_AgrmtAddlExternalOrigin and MKT_AgreementAddlExternalID) whether this agreement instance exists (MKT_AgreementOrigin and MKT_AgreementExternalID) or is referenced already in any other agreement as additional external key (MKT_AgrmtAddlExternalOrigin and MKT_AgreementAddlExternalID). 5.2.11.3 Payload Examples for Agreements Demonstrates creation and change of agreements. The following examples show how you can use the agreements API. Insert your own data to fill the header and the entities. Create Agreement with 1 Term Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41aca9f8-9357efbbd621 --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH Agreements(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='20180410 -165542-917') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementOrigin":"TEST_ORIGIN","MKT_AgreementIsCanceled":true, "MKT_AgreementBundleOrigin":"","MKT_AgreementBundleExternalID":"", "MKT_AgrmtBundleStartDateTime":null, Integration Guide Integration APIs PUBLIC 693 "MKT_AgreementExternalID":"20180410-165542-917", "MKT_AgrmtCancellationReason":"", "ContactID":"20180410-165542-277","ContactOrigin":"SAP_C4C_BUPA", "MKT_AgreementIsBundle":false, "MKT_AgreementIsBundleMember":true, "MKT_AgreementType":"1", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/", "MKT_AgreementStartDateTime":"/ Date(1325376000000+0000)/","MKT_AgreementEndDateTime":"/ Date(1640995200000+0000)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH AgreementTerms(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='2018 0410-165542-917',MKT_AgrmtTermsStartDateTime=datetimeoffset'2012-01-01T00%3A00 %3A00Z',MKT_AgrmtTermsEndDateTime=datetimeoffset'2013-12-31T00%3A00%3A00Z') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementStatus":"A", "MKT_AgreementRenewalType":"1", "ProductOrigin":"SAP_CRM_PRODUCT", "ProductID":"SP_CS_CASH", "MKT_AgrmtCanclnConditions":"1", "MKT_AgrmtCanclnDcsnToDateTime":"2018-01-01T00:00:00Z", "MKT_AgrmtProlngnDcsnFromDteTme":"2019-01-01T00:00:00Z", "MKT_AgreementPaymentFrequency":"6", "MKT_AgrmtPaymentIsInAdvance":true, "MKT_AgrmtBundleProductOrigin":"TEST_ORIGIN", "MKT_AgrmtBundleProductID":"TEST_BUNDLE", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621---batch-- Create Agreement with 2 Terms Sample Code --batch content-type:multipart/mixed; boundary=changeset_761e49b6-3146-4a57-8d10-15816fb9c75a --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH Agreements(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='20180410 -165542-917') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 694 PUBLIC Integration Guide Integration APIs {"MKT_AgreementOrigin":"TEST_ORIGIN","MKT_AgreementIsCanceled":true, "MKT_AgreementBundleOrigin":"","MKT_AgreementBundleExternalID":"", "MKT_AgrmtBundleStartDateTime":null, "MKT_AgreementExternalID":"20180410-165542-917", "MKT_AgrmtCancellationReason":"", "ContactID":"20180410-165542-277","ContactOrigin":"SAP_C4C_BUPA", "MKT_AgreementIsBundle":false, "MKT_AgreementIsBundleMember":true, "MKT_AgreementType":"1", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/", "MKT_AgreementStartDateTime":"/ Date(1325376000000+0000)/","MKT_AgreementEndDateTime":"/ Date(1640995200000+0000)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH AgreementTerms(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='2018 0410-165542-917',MKT_AgrmtTermsStartDateTime=datetimeoffset'2012-01-01T00%3A00 %3A00Z',MKT_AgrmtTermsEndDateTime=datetimeoffset'2013-12-31T00%3A00%3A00Z') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementStatus":"A", "MKT_AgreementRenewalType":"1", "ProductOrigin":"SAP_CRM_PRODUCT", "ProductID":"CURRACCNTONLINE", "MKT_AgrmtCanclnConditions":"1", "MKT_AgrmtCanclnDcsnToDateTime":"2018-01-01T00:00:00Z", "MKT_AgrmtProlngnDcsnFromDteTme":"2019-01-01T00:00:00Z", "MKT_AgreementPaymentFrequency":"6", "MKT_AgrmtPaymentIsInAdvance":true, "MKT_AgrmtBundleProductOrigin":"TEST_ORIGIN", "MKT_AgrmtBundleProductID":"TEST_BUNDLE", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH AgreementTerms(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='2018 0410-165542-917',MKT_AgrmtTermsStartDateTime=datetimeoffset'2014-01-01T00%3A00 %3A00Z',MKT_AgrmtTermsEndDateTime=datetimeoffset'2024-01-01T00%3A00%3A00Z') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementStatus":"S", "MKT_AgreementRenewalType":"2", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621---batch-- Integration Guide Integration APIs PUBLIC 695 Change Agreement Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41aca9f8-9357efbbd622 --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd622 Content-Type: application/http Content-Transfer-Encoding: binary PATCH Agreements(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='20180410 -165542-917') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgrmtCancellationReason":"0000001001", "MKT_AgreementIsCanceled":false, "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd622 Content-Type: application/http Content-Transfer-Encoding: binary PATCH AgreementTerms(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='2018 0410-165542-917',MKT_AgrmtTermsStartDateTime=datetimeoffset'2012-01-01T00%3A00 %3A00Z',MKT_AgrmtTermsEndDateTime=datetimeoffset'2014-12-31T00%3A00%3A00Z') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementStatus":"S", "MKT_AgreementRenewalType":"2", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd622---batch-- Create an Additional External Agreement ID Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41aca9f8-9357efbbd621 --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PUT AgrmtAdditionalExtIDs(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalI 696 PUBLIC Integration Guide Integration APIs D='20180410-165542-917',MKT_AgrmtAddlExternalOrigin='EXTERN_ORIGIN',MKT_Agreem entAddlExternalID='AGR_ADDL_EXT_ID') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementOrigin":"EXTERN_ORIGIN", "MKT_AgreementExternalID":"20180410-165542-917", "MKT_AgrmtAddlExternalOrigin":"EXTERN_ORIGIN", "MKT_AgreementAddlExternalID":"AGR_ADDL_EXT_ID" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621---batch-- Delete an Additional External Agreement ID Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41aca9f8-9357efbbd621 --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary DELETE AgrmtAdditionalExtIDs(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID=' 20180410-165542-917',MKT_AgrmtAddlExternalOrigin='EXTERN_ORIGIN',MKT_AgreementAdd lExternalID='AGR_ADDL_EXT_ID') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20170508141617.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementOrigin":"EXTERN_ORIGIN", "MKT_AgreementExternalID":"20180410-165542-917", "MKT_AgrmtAddlExternalOrigin":"EXTERN_ORIGIN", "MKT_AgreementAddlExternalID":"AGR_ADDL_EXT_ID" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621---batch-- Create Agreement Bundle with 2 Bundle Members --batch Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41aca9f8-9357efbbd621 --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary Integration Guide Integration APIs PUBLIC 697 PATCH Agreements(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='BUNDLE_EXAM PLE') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20201217112001.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementOrigin":"TEST_ORIGIN", "MKT_AgreementExternalID":"BUNDLE_EXAMPLE", "MKT_AgreementIsCanceled":false, "MKT_AgreementBundleOrigin":"", "MKT_AgreementBundleExternalID":"", "MKT_AgrmtBundleStartDateTime":null, "ContactID":"20180410-165542-277", "ContactOrigin":"SAP_C4C_BUPA", "MKT_AgreementIsBundle":true, "MKT_AgreementIsBundleMember":false, "MKT_AgreementType":"1", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/", "MKT_AgreementStartDateTime":"/Date(1590969600000+0000)/", "MKT_AgreementEndDateTime":"/Date(1609372800000+0000)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH AgreementTerms(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='BUNDLE_ EXAMPLE',MKT_AgrmtTermsStartDateTime=datetimeoffset'2020-01-01T12%3A00%3A00Z',MKT _AgrmtTermsEndDateTime=datetimeoffset'2025-12-31T12%3A00%3A00Z') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20201217114000.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementStatus":"A", "MKT_AgreementRenewalType":"1", "ProductOrigin":"TEST_ORIGIN", "ProductID":"TEST_BUNDLE", "MKT_AgrmtCanclnConditions":"1", "MKT_AgrmtCanclnDcsnToDateTime":"2020-06-30T12:00:00Z", "MKT_AgrmtProlngnDcsnFromDteTme":"2020-06-01T00:00:00Z", "MKT_AgreementPaymentFrequency":"6", "MKT_AgrmtPaymentIsInAdvance":true, "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH Agreements(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='BUNDLE_MEMB ER01') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20201217112001.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementOrigin":"TEST_ORIGIN", "MKT_AgreementExternalID":"BUNDLE_MEMBER01", "MKT_AgreementIsCanceled":false, "MKT_AgreementBundleOrigin":"TEST_ORIGIN", "MKT_AgreementBundleExternalID":"BUNDLE_EXAMPLE", 698 PUBLIC Integration Guide Integration APIs "MKT_AgrmtBundleStartDateTime":"/Date(1590969600000+0000)/", "ContactID":"20180410-165542-277", "ContactOrigin":"SAP_C4C_BUPA", "MKT_AgreementIsBundle":false, "MKT_AgreementIsBundleMember":true, "MKT_AgreementType":"1", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/", "MKT_AgreementStartDateTime":"/Date(1590969600000+0000)/", "MKT_AgreementEndDateTime":"/Date(1609372800000+0000)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH AgreementTerms(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='BUNDLE_ MEMBER01',MKT_AgrmtTermsStartDateTime=datetimeoffset'2020-06-01T12%3A00%3A00Z',MK T_AgrmtTermsEndDateTime=datetimeoffset'2021-12-31T12%3A00%3A00Z') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20201217114001.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementStatus":"A", "MKT_AgreementRenewalType":"1", "ProductOrigin":"SAP_CRM_PRODUCT", "ProductID":"CURRACCNTONLINE", "MKT_AgrmtCanclnConditions":"1", "MKT_AgrmtCanclnDcsnToDateTime":"2020-06-30T12:00:00Z", "MKT_AgrmtProlngnDcsnFromDteTme":"2020-06-01T00:00:00Z", "MKT_AgreementPaymentFrequency":"6", "MKT_AgrmtPaymentIsInAdvance":true, "MKT_AgrmtBundleProductOrigin":"TEST_ORIGIN", "MKT_AgrmtBundleProductID":"TEST_BUNDLE", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Content-Transfer-Encoding: binary PATCH Agreements(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='BUNDLE_MEMB ER02') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20201217112001.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementOrigin":"TEST_ORIGIN", "MKT_AgreementExternalID":"BUNDLE_MEMBER02", "MKT_AgreementIsCanceled":false, "MKT_AgreementBundleOrigin":"TEST_ORIGIN", "MKT_AgreementBundleExternalID":"BUNDLE_EXAMPLE", "MKT_AgrmtBundleStartDateTime":"/Date(1590969600000+0000)/", "MKT_AgrmtCancellationReason":"", "ContactID":"20180410-165542-277", "ContactOrigin":"SAP_C4C_BUPA", "MKT_AgreementIsBundle":false, "MKT_AgreementIsBundleMember":true, "MKT_AgreementType":"1", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/", "MKT_AgreementStartDateTime":"/Date(1590969600000+0000)/", "MKT_AgreementEndDateTime":"/Date(1609372800000+0000)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 Content-Type: application/http Integration Guide Integration APIs PUBLIC 699 Content-Transfer-Encoding: binary PATCH AgreementTerms(MKT_AgreementOrigin='TEST_ORIGIN',MKT_AgreementExternalID='BUNDLE_ MEMBER02',MKT_AgrmtTermsStartDateTime=datetimeoffset'2020-12-01T12%3A00%3A00Z',MK T_AgrmtTermsEndDateTime=datetimeoffset'2021-12-31T12%3A00%3A00Z') HTTP/1.1 Content-Type: application/json Content-Length: 1024 Sap-Cuan-SourceSystemId: XXXCLN123 Sap-Cuan-SourceSystemType: Sap-Cuan-SequenceId: AGREEMENT_MASTER_DATA Sap-Cuan-RequestTimestamp: 20201217114002.0000001 Sap-Cuan-ExternalReferenceId: XXXCLN12320170508141617_01 {"MKT_AgreementStatus":"A", "MKT_AgreementRenewalType":"1", "ProductOrigin":"SAP_CRM_PRODUCT", "ProductID":"SP_CS_CASH", "MKT_AgrmtCanclnConditions":"1", "MKT_AgrmtCanclnDcsnToDateTime":"2020-06-30T12:00:00Z", "MKT_AgrmtProlngnDcsnFromDteTme":"2020-06-01T00:00:00Z", "MKT_AgreementPaymentFrequency":"6", "MKT_AgrmtPaymentIsInAdvance":true, "MKT_AgrmtBundleProductOrigin":"TEST_ORIGIN", "MKT_AgrmtBundleProductID":"TEST_BUNDLE", "OriginDataLastChgUTCDateTime":"/Date(1523372142917)/" } --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621---batch-- 5.2.12 Scores Public OData API (API_MKT_SCORE_SRV) for Scores Entity Data Model Service Metadata URI: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_SCORE_SRV;/ $metadata Technical Data OData Version Root URI Service Metadata URI: Authorizations 2.0 https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_SCORE_SRV https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_SCORE_SRV/$metadata The following business catalog role is required: SAP_CEC_BC_MKT_API_IC2_PC 700 PUBLIC Integration Guide Integration APIs Communication Scenario ID Component for Incidents Field Extensibility SAP_COM_0307 CEC-MKT-ML-PRE Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. No 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_SCORE_SRV;v=0003/$metadata?sapdocumentation=all Marketing - Scores Details Page Scores API Remarks Only for internal access. You need to provide the server and port names. General access to the Details page of the service on SAP API Hub. One-time registration 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. General access to the Scores metadata file. One-time regis tration or logon is required. Related Information https://api.sap.com Integration Guide Integration APIs PUBLIC 701 5.2.12.1 Basic Concepts The public API for Scores API_MKT_SCORE_SRV supports operations on the Scores Business Object. Note Please note that score saving must be enabled if you want to use this API. For more information, see Saving Scores for a Predictive Model. Score Versioning The score values for a contact are stored in a version together with the timestamp of their calculation. Every time scores or predictive models are calculated in the background, the calculated score values are saved under a new version. This version corresponds to the current UTC timestamp. A nightly report deletes all outdated versions. However, at least one version is kept, even if the version is outdated. When you use scores or predictive models in Segmentation or Customer Profile, the latest version of the score is used. If no version exists for a score, the score values are calculated on the fly. If a large number of score values for contacts are calculated on the fly, this can lead to performance issues in the system. In the Scores API, MarketingScoreDateTime corresponds to the timestamp which is used as version. If several score values are uploaded at once, all score values need to have the same timestamp. If different uploads use the same version, meaning the same timestap, the upload will add score values for new contacts and it will overwrite score values of contacts which were already uploaded with this version. If a contact is included in an older version, but not in the latest version, their score value will be 0 or No Valuation, depending on the application in which the score value is displayed in. The timestamp must not be in the future. The timestamp must not be older than an already existing timestamp of this score. Processing Info 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. The operation header must include the Sap-Cuan-SequenceId. 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 record to be updated is not found, then it is simply created. 702 PUBLIC Integration Guide Integration APIs Best Practices The ContactOrigin cannot be shareable. If the 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 . The ContactOrigin cannot be updated. It's a key field together with the Interaction Contact ID. 5.2.12.2 Structure of OData Service API_MKT_SCORE_SRV This document describes the structure of the Public OData API service API_MKT_SCORE_SRV. Make sure you read the Basic Concepts topic before you start. Entities The Scores OData API provides the following entities: Entity Scores ScoreModels ScoreValues ScoreTargetObjects Description Path This entity contains a per sisted score scenario. A persisted score scenario is a scenario for which scores are saved. /Scores(MarketingScore=<score id>) This entity contains the score model associated with a particular score sce nario. /ScoreModels(MarketingScore=<score id>,MarketingScoreModel=<model id>) This entity contains the score value for a score sce nario, score model, and in teraction contact. /ScoreValues(MarketingScore=<score id>,MarketingScoreModel=<model id>,MarketingScoreDateTime=<date>,MarketingSc oredObjectUUID=<contact uuid> ) This entity contains the target object for a score scenario. /ScoreTargetObjects(MarketingScore=<score id>,MarketingScoreModel=<model id>,MtkgScoreTargetObjectType=<target object>) You can view sample payloads and test the API at https://api.sap.com . Integration Guide Integration APIs PUBLIC 703 Entity Sets The Scores OData API provides the following entity sets: Entity Set Scores ScoreModels ScoreValues Description Path This entity contains the persisted type of score scenarios. A persisted score scenario is a sce nario for which scores are saved. /Scores This entity contains the score models associated with a particular score sce nario. /ScoreModels This entity contains the score value for a score sce nario, score model, and in teraction contact. /ScoreValues You can view sample payloads and test the API at https://api.sap.com . Scores You can perform the following operations on the Scores entity set: HTTP Method GET Path /Scores /Scores(<Marketing Score>) Note Only persisted scores can be summoned using the Scores API. Comments The options $inlinecount and $expand are supported. 704 PUBLIC Integration Guide Integration APIs ScoreModels You can perform the following operations on the ScoreModels entity set: HTTP Method GET POST Path Comments /ScoreModels / ScoreModels(MarketingScore ='{MarketingScore}',Market ingScoreModel='{MarketingS coreModel}') The options $top and $filter on MarketingScore and MarketingScoreModel are sup ported. /ScoreModels ScoreValues You can perform the following operations on the ScoreValues entity set: HTTP Method GET Path /ScoreValues Comments The option $top is mandatory with maximal 5000. The option $inlinecount is sup ported. The option $filter is valid only for the fields MarketingScore, MarketingScoreModel, MarketingScoreValue, MarketingScoreDateTime and MarketingScoredObjectUUID and ID/Origin combined . At least MarketingScore or MarketingScoreModel should be referenced in the filter option. If the MarketingScoreModel is not specified in the filter, the result will cover all the models related to this score. The filtering on MarketingScoreDateTime gives only the latest version. If the filter is used with MarketingScoredObjectUUID or MarketingScoredID/ Integration Guide Integration APIs PUBLIC 705 HTTP Method POST Path Comments / ScoreValues(MarketingScore ='<Marketing Score>',MarketingScoreMode l='<Marketing Score Model>',MarketingScoredObj ectUUID=guid'<UUID>',Marke tingScoreDateTime=datetime offset'<Timestamp>' Origin , the result is the latest score value assigned to this UUID or ID/Origin. · Only the operation EQ or = is supported when filtering on MarketingScore, MarketingScoreModel, MarketingScoreDateTime and MarketingScoredObjectUUID or MarkeringScoredID/Origin. / Scores(MarketingScore='<Ma rketing Score>')/ ScoreModels You can only post score values from ex ternally created scores. For best performance, deep insert is supported as illustrated in the payload examples. ScoreTargetObjects You can perform the following operations on the ScoreTargetObjects entity set: HTTP Method GET Path Comments /ScoreTargetObjects / ScoreTargetObjects(Marketi ngScore='{MarketingScore}' ,MarketingScoreModel='{Mar ketingScoreModel}',MtkgSco reTargetObjectType='{MtkgS coreTargetObjectType}') Note Score values can only be imported in models which have an assigned implementation method dedicated for external score values. This is always the case for score models created via this OData. 5.2.12.3 Payload Examples for Scores The following examples show how you can use the Scores API. 706 PUBLIC Integration Guide Integration APIs Scores GET all scores Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/Scores Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/Scores?$inlinecount=allpages& $expand=ScoreModels Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/Scores?$select=MarketingScore GET one score Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/Scores('CHURN_SCORE) Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/Scores('CHURN_SCORE)?$expand=ScoreModels Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/Scores('CHURN_SCORE)? $select=MarketingScore,MarketingScoreName,MarketingScorePurpose Score Models GET all Score Models Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreModels?$top=10& $filter=(MarketingScoreModel eq '555') and (MarketingScore eq 'CHURN_SCORE') /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreModels?$top=10& $filter=(MarketingScoreModel eq '555') /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreModels?$top=10& $filter=(MarketingScore eq 'CHURN_SCORE') Integration Guide Integration APIs PUBLIC 707 GET one Score Model Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ ScoreModels(MarketingScore='CHURN_SCORE,MarketingScoreModel='555') Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ ScoreModels(MarketingScore='CHURN_SCORE,MarketingScoreModel='555')? $select=MarketingScoreModelUUID POST Score Model Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreModels Sample Code { "MarketingScore":"ChurnScore", "MarketingScoreModelName":"<model name>" } Score Values GET all Score Values Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreValues?$top=20& $filter=MarketingScore eq 'CHURN_SCORE Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreValues?$top=20& $filter=MarketingScore eq 'CHURN_SCORE and MarketingScoredObjectUUID eq guid'00163e34-bda6-1ed7-bf8e-ff79868c52ea' Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreValues?$top=3000& $filter=MarketingScore eq 'ChurnScore' and MarketingScoreDateTime gt datetimeoffset'2019-07-12T07%3A58%3A00.4030000Z' 708 PUBLIC Integration Guide Integration APIs Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreValues?$top=3000& $filter=MarketingScore eq 'ChurnScore' and MarketingScoreDateTime eq datetimeoffset'2019-07-12T07%3A58%3A00.4030000Z' Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreValues?$top=3000& $filter=MarketingScore eq 'ChurnScore' and MarketingScoreValue gt 0.33 Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreValues?$top=3000& $filter=MarketingScore eq 'CHURN_SCORE' and MarketingScoreValue le 0.33 Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreValues?$skip=2&$top=3000& $filter=MarketingScore eq 'CHIRN_SCORE' and MarketingScoreValue le 0.33& $orderby=MarketingScoreValue desc GET one Score Value Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ ScoreValues(MarketingScore='CHURN_SCORE',MarketingScoreModel='555',MarketingSc oreDateTime=datetimeoffset'2019-07-12T07%3A58%3A00.4030000Z',MarketingScoredOb jectUUID=guid'ffffffff-ffff-ffff-ffff-ffffffffffff') Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ ScoreValues(MarketingScore='CHURN_SCORE',MarketingScoreModel='555',MarketingSc oreDateTime=datetimeoffset'2019-07-12T07%3A58%3A00.4030000Z',MarketingScoredOb jectUUID=guid'ffffffff-ffff-ffff-ffff-ffffffffffff')? $select=MarketingScoreValue POST Score Values Sample Code sap/opu/odata/sap/API_MKT_SCORE_SRV/Scores(MarketingScore=<score id >)/ ScoreModels Sample Code { "MarketingScore":"ChurnScore", ; "MarketingScoreModel":"555", "ScoreValues": [ { "MarketingScoreDateTime":"2017-12-02T14:26:00.9824060", Integration Guide Integration APIs PUBLIC 709 "MarketingScoredObjectUUID":"ffffffff-ffff-ffff-ffff-ffffffffffff", "MarketingScoreValue":"0.60" } ] } Score Target Objects GET all Target Objects Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ScoreTargetObjects? $filter=MarketingScore eq 'CHURN_SCORE' GET one Target Object Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ ScoreTargetObjects(MarketingScore='CHURN_SCORE',MarketingScoreModel='555',Mtkg ScoreTargetObjectType='IP_TARGETPRODUCT') Sample Code /sap/opu/odata/sap/API_MKT_SCORE_SRV/ ScoreTargetObjects(MarketingScore='CHURN_SCORE',MarketingScoreModel='555',Mtkg ScoreTargetObjectType='IP_TARGETPRODUCT')?$select=MarketingScore 5.2.13 Marketing Locations 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. The following diagrams illustrate the business process model for the marketing location API: 710 PUBLIC Integration Guide Integration APIs Integration Guide Integration APIs PUBLIC 711 Technical Data Name of the Service Underlying BO Package OData Version Root URI Service Metadata URI Authorizations Communication Scenario ID Component for Incidents Field Extensibility Supported API_MKT_LOCATION BO_MARKETING_LOCATION CUAN_BO_MARKETING_LOCATION 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_LOCATION_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_LOCATION_SRV/$metadata The following business catalog role is required: SAP_CEC_BC_MKT_API_LOC_PC SAP_COM_0305 CEC-MKT-DM-LOC (Marketing Location) Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Yes Technical Field Documentation You can access 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_LOCATION_SRV;v=0002/$metadata?sapdocumentation=all Remarks Only for internal access. You need to provide the server and port names. 712 PUBLIC Integration Guide Integration APIs Access Link Marketing - Marketing Locations Details Page Marketing Locations API Remarks General access to the Details page of the service on SAP API Hub. One-time registration is required for first-time users. 1. On the Details page, click Download Specification and download as EDMX. 2. Sepecify which application you want to use to open the EDMX file type. General access to the Marketing Locations metadata file. One-time registraton or logon is required. 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 5.2.13.1 Basic Concepts The Marketing Location API supports CRUD operations on the Marketing Location Business Object. Best Practices You can view sample payloads and test the API at https://api.sap.com . Field Extensibility In addition to the predelivered attributes, you can add customer-specific fields using the Custom Fields app. For more information, see Custom Fields. Integration Guide Integration APIs PUBLIC 713 5.2.13.2 Structure of API_MKT_LOCATION This document describes the structure of the Public OData API service API_MKT_LOCATION. Make sure you read the Basic Concepts topic before you start. Entity Sets The Marketing Location OData API provides the following entity sets: Entity Location LocationInfo LocationOriginData LocationOriginDataInfo Description Path This entity contains the list of market ing locations. /Locations This entity contains the list of market ing locations information. /LocationsInfo This entity contains the list of origin data for marketing locations. /LocationsOriginData This entity contains the list of origin data information for marketing loca tions. /LocationsOriginDataInfo Location Resource Path: /Location You can perform the following operations on the Location entity: Operations on the Location entity HTTP Method Description Path GET Get the list of marketing locations. GET /Locations Get the details of a marketing location. GET /Locations(`Marketing Location UUID') LocationsInfo Resource Path: /LocationsInfo 714 PUBLIC Integration Guide Integration APIs You can perform the following operations on the LocationsInfo entity: Operations on the LocationInfo entity HTTP Method Description Path GET Get the list of marketing locations Infor GET /LocationsInfo mation. Get the details of a marketing location Information. GET / LocationsInfo(`Marketing Location UUID') LocationsOriginData Resource Path: /LocationOriginData You can perform the following operations on the LocationOriginData entity: Operations on the LocationOriginData entity HTTP Method Description Path GET Get the list of marketing locations origin GET /LocationsOriginData data. POST Get the details of a marketing location origin. Create a marketing location origin. GET / LocationsOriginData(`Marke ting Location ID','Marketing Location Origin') POST /LocationsOriginData PATCH PUT Update a marketing location origin. Update a marketing location origin. PATCH /LocationsOriginData PUT /LocationsOriginData DELETE Delete the marketing location. DELETE / LocationsOriginData(`Marke ting Location ID','Marketing Location Origin') LocationsOriginDataInfo Resource Path: /LocationOriginDataInfo Integration Guide Integration APIs PUBLIC 715 You can perform the following operations on the LocationOriginDataInfo entity: Operations on the LocationOriginDataInfo entity HTTP Method Description Path GET POST PATCH Get the details of a marketing location origin information. GET / LocationsOriginDataInfo(`M arketing Location ID','Marketing Location Origin') Create a marketing location origin infor POST / mation. LocationsOriginDataInfo Update a marketing location origin in formation. PATCH / LocationsOriginDataInfo PUT Update a marketing location origin in PUT / formation LocationsOriginDataInfo 5.2.13.3 Payload Examples The following examples show how you can use the Marketing Locations API. Create Marketing Locations POST Sample Code --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST LocationsOriginData HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingLocationID>RDLOC1309</d:MarketingLocationID> <d:MarketingLocationOrigin>WECHAT_POI</d:MarketingLocationOrigin> <d:MarketingLocationName>Location Name for LOC1409</d:MarketingLocationName> <d:CompanyName>CompanyName for RDLOC1409</d:CompanyName> <d:MarketingLocationMallName>MallName for LOC1309</ d:MarketingLocationMallName> <d:MarketingArea>GERMANY</d:MarketingArea> <d:MarketingAreaName>GERMANY</d:MarketingAreaName> 716 PUBLIC Integration Guide Integration APIs <d:MarketingLocationType>MALL</d:MarketingLocationType> <d:MarketingLocationTypeName>MALL</d:MarketingLocationTypeName> <d:Country>CA</d:Country> <d:CountryName>Canada</d:CountryName> <d:CityName>Montreal</d:CityName> <d:AddressRegion>QC</d:AddressRegion> <d:RegionName>QC</d:RegionName> <d:PostalCode>H9X2R2</d:PostalCode> <d:AddressStreetName>ROBERT BOURASSA</d:AddressStreetName> <d:AddressHouseNumber>111</d:AddressHouseNumber> <d:Building>Building1309</d:Building> <d:Floor>FOURTH</d:Floor> <d:RoomNumber>LAGRANGE</d:RoomNumber> <d:PhoneNumber>5149999999</d:PhoneNumber> <d:FaxNumber>5149999999</d:FaxNumber> <d:EmailAddress>LOC1509@example.com</d:EmailAddress> <d:WebsiteURL>example.com</d:WebsiteURL> <d:ImageURL>example.com</d:ImageURL> <d:Longitude>1010</d:Longitude> <d:Latitude>1020</d:Latitude> <d:SpatialReferenceSystem>Ref070903</d:SpatialReferenceSystem> <d:ValidityStartDate>2016-09-13T08:01</d:ValidityStartDate> <d:ValidityEndDate>2016-09-13T08:01</d:ValidityEndDate> </m:properties> </atom:content> </atom:entry> --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST LocationsOriginData HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingLocationID>RDLOC1509</d:MarketingLocationID> <d:MarketingLocationOrigin>WECHAT_POI</d:MarketingLocationOrigin> <d:MarketingLocationName>Location Name for LOC1509</d:MarketingLocationName> <d:CompanyName>CompanyName for RDLOC1309</d:CompanyName> <d:MarketingLocationMallName>MallName for LOC1309</ d:MarketingLocationMallName> <d:MarketingArea>GERMANY</d:MarketingArea> <d:MarketingAreaName>GERMANY</d:MarketingAreaName> <d:MarketingLocationType>MALL</d:MarketingLocationType> <d:MarketingLocationTypeName>MALL</d:MarketingLocationTypeName> <d:Country>CA</d:Country> <d:CountryName>Canada</d:CountryName> <d:CityName>Montreal</d:CityName> <d:AddressRegion>QC</d:AddressRegion> <d:RegionName>QC</d:RegionName> <d:PostalCode>H9X2R2</d:PostalCode> <d:AddressStreetName>DUKE</d:AddressStreetName> <d:AddressHouseNumber>111</d:AddressHouseNumber> <d:Building>Building1309</d:Building> <d:Floor>FOURTH</d:Floor> <d:RoomNumber>LAGRANGE</d:RoomNumber> <d:PhoneNumber>5149999999</d:PhoneNumber> <d:FaxNumber>5149999999</d:FaxNumber> <d:EmailAddress>LOC1509@example.com</d:EmailAddress> <d:WebsiteURL>example.com</d:WebsiteURL> <d:ImageURL>example.com</d:ImageURL> <d:Longitude>1010</d:Longitude> <d:Latitude>1020</d:Latitude> <d:SpatialReferenceSystem>Ref070903</d:SpatialReferenceSystem> <d:ValidityStartDate>2016-09-13T08:01</d:ValidityStartDate> Integration Guide Integration APIs PUBLIC 717 <d:ValidityEndDate>2016-09-13T08:01</d:ValidityEndDate> </m:properties> </atom:content> </atom:entry> --changeset---batch-- Create a Marketing Location Sample Code <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingLocationID>RDLOC13095</d:MarketingLocationID> <d:MarketingLocationOrigin>WECHAT_POI</d:MarketingLocationOrigin> <d:MarketingLocationName>Location Name for LOC1409</d:MarketingLocationName> <d:CompanyName>CompanyName for RDLOC1409</d:CompanyName> <d:MarketingLocationMallName>MallName for LOC1309</ d:MarketingLocationMallName> <d:MarketingArea>GERMANY</d:MarketingArea> <d:MarketingAreaName>GERMANY</d:MarketingAreaName> <d:MarketingLocationType>MALL</d:MarketingLocationType> <d:MarketingLocationTypeName>MALL</d:MarketingLocationTypeName> <d:Country>CA</d:Country> <d:CountryName>Canada</d:CountryName> <d:CityName>Montreal</d:CityName> <d:AddressRegion>QC</d:AddressRegion> <d:RegionName>QC</d:RegionName> <d:PostalCode>H9X2R2</d:PostalCode> <d:AddressStreetName>ROBERT BOURASSA</d:AddressStreetName> <d:AddressHouseNumber>111</d:AddressHouseNumber> <d:Building>Building1309</d:Building> <d:Floor>FOURTH</d:Floor> <d:RoomNumber>LAGRANGE</d:RoomNumber> <d:PhoneNumber>5149999999</d:PhoneNumber> <d:FaxNumber>5149999999</d:FaxNumber> <d:EmailAddress>LOC1509@example.com</d:EmailAddress> <d:WebsiteURL>example.com</d:WebsiteURL> <d:ImageURL>example.com</d:ImageURL> <d:Longitude>1010</d:Longitude> <d:Latitude>1020</d:Latitude> <d:SpatialReferenceSystem>Ref070903</d:SpatialReferenceSystem> <d:ValidityStartDate>2016-09-13T08:01</d:ValidityStartDate> <d:ValidityEndDate>2016-09-13T08:01</d:ValidityEndDate> </m:properties> </atom:content> </atom:entry> 718 PUBLIC Integration Guide Integration APIs Delete a Marketing Location DELETE Sample Code --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary DELETE LocationsOriginData(MarketingLocationID='RDLOC1309',MarketingLocationOrigin='W ECHAT_POI') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 --changeset---batch-- Get a List of all Marketing Locations GET Sample Code --batch Content-Type: application/http Content-Transfer-Encoding: binary GET LocationsOriginData HTTP/1.1 --batch-- Get a List of One Marketing Location GET Sample Code --batch Content-Type: application/http Content-Transfer-Encoding: binary GET LocationsOriginData(MarketingLocationID='RDLOC1309',MarketingLocationOrigin='W ECHAT_POI') HTTP/1.1 --batch Content-Type: application/http Content-Transfer-Encoding: binary GET LocationsOriginData(MarketingLocationID='RDLOC1509',MarketingLocationOrigin='W ECHAT_POI') HTTP/1.1 --batch-- Integration Guide Integration APIs PUBLIC 719 Update Several Marketing Locations PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary PATCH LocationsOriginData(MarketingLocationID='RDLOC1309',MarketingLocationOrigin='W ECHAT_POI') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingLocationID>RDLOC1309</d:MarketingLocationID> <d:MarketingLocationOrigin>WECHAT_POI</d:MarketingLocationOrigin> <d:MarketingLocationName>Location Name for LOC1409 Updated</ d:MarketingLocationName> <d:CompanyName>CompanyName for RDLOC1409 Updated</d:CompanyName> <d:MarketingLocationMallName>MallName for LOC1309 Updated</ d:MarketingLocationMallName> <d:MarketingArea>GERMANY</d:MarketingArea> <d:MarketingAreaName>GERMANY</d:MarketingAreaName> <d:MarketingLocationType>MALL</d:MarketingLocationType> <d:MarketingLocationTypeName>MALL</d:MarketingLocationTypeName> <d:Country>CA</d:Country> <d:CountryName>Canada</d:CountryName> <d:CityName>Montreal</d:CityName> <d:AddressRegion>QC</d:AddressRegion> <d:RegionName>QC</d:RegionName> <d:PostalCode>H9X2R2</d:PostalCode> <d:AddressStreetName>ROBERT BOURASSA</d:AddressStreetName> <d:AddressHouseNumber>111</d:AddressHouseNumber> <d:Building>Building1309</d:Building> <d:Floor>FOURTH</d:Floor> <d:RoomNumber>LAGRANGE</d:RoomNumber> <d:PhoneNumber>5149999999</d:PhoneNumber> <d:FaxNumber>5149999999</d:FaxNumber> <d:EmailAddress>LOC1509@example.com</d:EmailAddress> <d:WebsiteURL>example.com</d:WebsiteURL> <d:ImageURL>example.com</d:ImageURL> <d:Longitude>1010</d:Longitude> <d:Latitude>1020</d:Latitude> <d:SpatialReferenceSystem>Ref070903</d:SpatialReferenceSystem> <d:ValidityStartDate>2016-09-13T08:01</d:ValidityStartDate> <d:ValidityEndDate>2016-09-13T08:01</d:ValidityEndDate> </m:properties> </atom:content> </atom:entry> --changeset Content-Type: application/http Content-Transfer-Encoding: binary PATCH LocationsOriginData(MarketingLocationID='RDLOC1509',MarketingLocationOrigin='W ECHAT_POI') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 <?xml version="1.0" encoding="utf-8" standalone="yes"?> 720 PUBLIC Integration Guide Integration APIs <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary PATCH LocationsOriginData(MarketingLocationID='RDLOC1309',MarketingLocationOrigin='W ECHAT_POI') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingLocationID>RDLOC1309</d:MarketingLocationID> <d:MarketingLocationOrigin>WECHAT_POI</d:MarketingLocationOrigin> <d:MarketingLocationName>Location Name for LOC1409 Updated</ d:MarketingLocationName> <d:CompanyName>CompanyName for RDLOC1409 Updated</d:CompanyName> <d:MarketingLocationMallName>MallName for LOC1309 Updated</ d:MarketingLocationMallName> <d:MarketingArea>GERMANY</d:MarketingArea> <d:MarketingAreaName>GERMANY</d:MarketingAreaName> <d:MarketingLocationType>MALL</d:MarketingLocationType> <d:MarketingLocationTypeName>MALL</d:MarketingLocationTypeName> <d:Country>CA</d:Country> <d:CountryName>Canada</d:CountryName> <d:CityName>Montreal</d:CityName> <d:AddressRegion>QC</d:AddressRegion> <d:RegionName>QC</d:RegionName> <d:PostalCode>H9X2R2</d:PostalCode> <d:AddressStreetName>ROBERT BOURASSA</d:AddressStreetName> <d:AddressHouseNumber>111</d:AddressHouseNumber> <d:Building>Building1309</d:Building> <d:Floor>FOURTH</d:Floor> <d:RoomNumber>LAGRANGE</d:RoomNumber> <d:PhoneNumber>5149999999</d:PhoneNumber> <d:FaxNumber>5149999999</d:FaxNumber> <d:EmailAddress>LOC1509@example.com</d:EmailAddress> <d:WebsiteURL>example.com</d:WebsiteURL> <d:ImageURL>example.com</d:ImageURL> <d:Longitude>1010</d:Longitude> <d:Latitude>1020</d:Latitude> <d:SpatialReferenceSystem>Ref070903</d:SpatialReferenceSystem> <d:ValidityStartDate>2016-09-13T08:01</d:ValidityStartDate> <d:ValidityEndDate>2016-09-13T08:01</d:ValidityEndDate> </m:properties> </atom:content> </atom:entry> --changeset Content-Type: application/http Content-Transfer-Encoding: binary PATCH LocationsOriginData(MarketingLocationID='RDLOC1509',MarketingLocationOrigin='W ECHAT_POI') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingLocationID>RDLOC1509</d:MarketingLocationID> Integration Guide Integration APIs PUBLIC 721 <d:MarketingLocationOrigin>WECHAT_POI</d:MarketingLocationOrigin> <d:MarketingLocationName>Location Name for LOC1509 Updated</ d:MarketingLocationName> <d:CompanyName>CompanyName for RDLOC1309 Updated3</d:CompanyName> <d:MarketingLocationMallName>MallName for LOC1309 Updated</ d:MarketingLocationMallName> <d:MarketingArea>GERMANY</d:MarketingArea> <d:MarketingAreaName>GERMANY</d:MarketingAreaName> <d:MarketingLocationType>MALL</d:MarketingLocationType> <d:MarketingLocationTypeName>MALL</d:MarketingLocationTypeName> <d:Country>CA</d:Country> <d:CountryName>Canada</d:CountryName> <d:CityName>Montreal</d:CityName> <d:AddressRegion>QC</d:AddressRegion> <d:RegionName>QC</d:RegionName> <d:PostalCode>H9X2R2</d:PostalCode> <d:AddressStreetName>DUKE</d:AddressStreetName> <d:AddressHouseNumber>111</d:AddressHouseNumber> <d:Building>Building1309</d:Building> <d:Floor>FOURTH</d:Floor> <d:RoomNumber>LAGRANGE</d:RoomNumber> <d:PhoneNumber>5149999999</d:PhoneNumber> <d:FaxNumber>5149999999</d:FaxNumber> <d:EmailAddress>LOC1509@example.com</d:EmailAddress> <d:WebsiteURL>example.com</d:WebsiteURL> <d:ImageURL>example.com</d:ImageURL> <d:Longitude>1010</d:Longitude> <d:Latitude>1020</d:Latitude> <d:SpatialReferenceSystem>Ref070903</d:SpatialReferenceSystem> <d:ValidityStartDate>2016-09-13T08:01</d:ValidityStartDate> <d:ValidityEndDate>2016-09-13T08:01</d:ValidityEndDate> </m:properties> </atom:content> </atom:entry> --changeset---batch-- 5.2.14 Classifications (Deprecated) 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. Entity Data Model Service Metadata URI: https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_ML_CLASSIFICATION_SRV;v=0002/$metadata Technical Data 722 PUBLIC Integration Guide Integration APIs OData Version Root URI Service Metadata URI: Authorizations Communication Scenario ID Component for Incidents Field Extensibility 2.0 https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_ML_CLASSIFICATION_SRV;v=0002 https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_ML_CLASSIFICATION_SRV;v=0002/$me tadata The following business catalog role is required: SAP_CEC_BC_MKT_API_IC2_PC SAP_COM_0245 CEC-MKT-ML-CLS Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. No 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 Remarks https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_ML_CLASSIFICATION_SRV;v=0003/$metadat a?sap-documentation=all Only for internal access. You need to provide the server and port names. Marketing - Classifications Page General access to the Details page of the service on SAP API Hub. One-time registration 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. Classifications API General access to the Contacts metadata file. One-time reg istration or logon is required. Integration Guide Integration APIs PUBLIC 723 5.2.14.1 Basic Concepts (Deprecated) The public API for Classifications API_MKT_ML_CLASSIFICATION_SRV supports operations on the Classification Business Object. Processing Info 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. The operation header must include the Sap-Cuan-SequenceId. 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 record to be updated is not found, then it is simply created. Best Practices For classifications, batch requests are only supported for GET and PATCH operations. We recommend to use a batch request to update classification values for one classification only and we recommend to restict a batch request to one predictive scenario only. The batch request is limited to 100.000 classification values. For GET, the batch request is limited to 5000 classifications. For deep create, the request is limited to 50.000 classification values. The ContactOrigin cannot be shareable. If the 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 . The ContactOrigin cannot be updated. It's a key field together with the Interaction Contact ID. 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. Potential processing errors are recorded in the SAP Marketing Cloud system in the Import Monitor app, where they can be monitored, restarted and discarded. Data processing for classifications is mostly synchronous. 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. 724 PUBLIC Integration Guide Integration APIs Note Data processing for Deep Create and Bacth requests is asynchronous. The data you upload lands in a staging area, where it is then further processed. In the response you will get a Reference Message ID. To view the processing status and to check for errors or success messages, you must launch the Import Monitor app and search for the Reference Message ID. Messages for classifications in this app are displayed under the API for classifications. In the event of errors, you can restart or discard the import in the Import Monitor. 5.2.14.2 Structure of OData Service API_MKT_ML_CLASSIFICATION_SVR (Deprecated) This document describes the structure of the Public OData API service API_MKT_ML_CLASSIFICATION. Make sure you read the Basic Concepts topic before you start. Entity Sets The Classification OData API provides the following entity sets: Entity Set ClassificationsType ClassificationsValuesType MchnLrngScenarios Description Path This entity contains information about /ClassificationsType the version, target object and predictive scenario of a classification. This entity contains information about a /ClassificationsValuesType contact and their classification value. This entity contains information about the custom predictive scenarios of the type External Score. /MchnLrngScenarios ClassificationsType The table below describes the properties for the entity ClassificationsType. Integration Guide Integration APIs PUBLIC 725 ClassificationsType Property Names and Descriptions Property Name Property Description Usage MchnLrngClassificationVersion Contains the version of the classification. Note A classification can only have one version. Different classifications can have different versions. Mandatory MchnLrngClassificationVersText MchnLrngTargetObject PredictiveScenario Contains the freetext name, which you can give to the classification version. Contains the target object for which the Mandatory classification is calculated. Contains the custom predictive sce nario that is used for storing the classi fication. Mandatory Note The predictive scenario must exist in the Predictive Scenarios app. You can perform the following operations on the ClassificationsType entity set: HTTP Method GET POST PUT Description Path Read header information for a classification, which in / cludes classification key, predictive scenario, classification version and optionally classification version text. Classifications('<Predictiv eScenario>,<MchnLrngTargetO bject>, <MchnLrngClassificationVers ion>') Read all classifications /Classifications Create a new classification with header information about the classification key, predictive scenario, tar get object and classification version. /Classifications The classification version text is optional. Update an existing classification with additional infor mation, namely the classification version text. The PUT request replaces the existing entry, so all property values in the entry either take the values in dicated in the request body, or are reset to their de fault value if not mentioned in the request. / Classifications('<Predictiv eScenario>,<MchnLrngTargetO bject>,<MchnLrngClassificat ionVersion>') 726 PUBLIC Integration Guide Integration APIs HTTP Method PATCH PATCH (Batch) DELETE Description Path Update an existing classification with additional infor mation, namely the classification version text. The PATCH request updates only the properties indi cated in the request body, and leaves untouched any thing not mentioned in its current state. / Classifications('<Predictiv eScenario>,<MchnLrngTargetO bject>,<MchnLrngClassificat ionVersion>') In your batch request, you can update both different classifications and different classification values. For batch requests, you can only update classification values for one classification. The batch request is lim ited to 100,000 classification values. https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CONTACT_SRV;v=0002/ $batch Add to the batch request header: Content-Type: multipart/mixed; boundary=batch; Add to the operation header: Sap-CuanSequenceId: CLASSIFICATION_BATCH_SINGLE Delete an existing classification and all its classification values. / Classifications('<Predictiv eScenario>,<MchnLrngTargetO bject>,<MchnLrngClassificat ionVersion>') ClassificationsValuesType The table below describes the properties for the entity ClassificationsValuesType. ClassificationsValuesType Property Names and Descriptions Property Name Property Description Usage InteractionContactId Contains the ID of the interaction con tact. Note The ID for the interaction contact must exist in the system. InteractionContactOrigin Contains the origin of the contact. Note The origin cannot be shareable. Integration Guide Integration APIs PUBLIC 727 Property Name InteractionContactUUID MchnLrngClassificationValue MchnLrngClassificationVersion Property Description Usage Contains the internal ID of an interac tion contact in SAP Marketing Cloud. The ID must exist in the system. Mandatory Contains the classification value for the contact. The classification value can only be 0 or 1. Contains the version of the classification. Mandatory Note A classification can only have one version. Different classifications can have different versions. MchnLrngClfnEndDateTime Contains the end date of the analysis period. Note The end date time of a classification value must be later than the start date time of the same classification value. MchnLrngClfnStartDateTime Contains the start data of the analysis period. Mandatory Note The start date time of a classification value must be earlier than the end date time of the same classification value. MchnLrngTargetObject PredictiveScenario Contains the target object for which the Mandatory classification is calculated. Contains the custom predictive sce nario that is used for storing the classi fications. Mandatory The predictive scenario must exist in the Predictive Scenarios app. You can perform the following operations on the ClassificationValuesTypeentity set: 728 PUBLIC Integration Guide Integration APIs HTTP Method GET POST POST (Deep Create) Description Path Read information for a specific classification value, which includes the interaction contact UUID, predic tive scenario, target object, start date time and the optional atributes contact ID, ID origin, end date time and a classification value. / ClassificationValues('<Pred ictiveScenario,<MchnLrngTar getObject>,<MchnLrngClassif icationVersion>,<Interactio nContactUUID=guid>,<MchnLrn gClfnStartDateTime>') Get a list of classification values. You can read the classificatoin values for one classification or for sev eral different classifications. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby /ClassificationValues Note A maximum of 5,000 machine learning sce narios can be fetched in a single request. Specification of TOP is mandatory. Batch requests are also supported for GET. Create a single classification value, give its five keys, interaction contact UUID, predictive scenario, start date time, Season Ticket, and classification version. Additional atributes are contact ID and ID origin, end date time and a classification value. https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_ML_CLASSIFICATION_S RV/ClassificationValues Instead of the contact UUID, you can also give the contact ID and ID origin. Upload mutiple classification values belonging to only one classification. Note If the classification for which you want to upload values does not exist yet, it is also created with the deep create. A deep create is only possible for the initial load. https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_ML_CLASSIFICATION_S RV/Classifications A maximum of 50,000 classification values can be uploaded in one request. Integration Guide Integration APIs PUBLIC 729 HTTP Method PUT PATCH PATCH (Batch) DELETE Description Path Update an existing classification value with additional information about end date time and a classification value. The PUT request replaces the existing entry, so all property values in the entry either take the values in dicated in the request body, or are reset to their de fault value if not mentioned in the request. / ClassificationValues('<Pred ictiveScenario>,<MchnLrngTa rgetObject>,<MchnLrngClassi ficationVersion>,<Interacti onContactUUID=guid>,<MchnLr ngClfnStartDateTime>') Update an existing classification value with additional information about end date time and a classification value. The PATCH request updates only the properties indi cated in the request body, and leaves untouched any thing not mentioned in its current state. / ClassificationValues('<Pred ictiveScenario>,<MchnLrngTa rgetObject>,<MchnLrngClassi ficationVersion>,<Interacti onContactUUID=guid>,<MchnLr ngClfnStartDateTime>') In your batch request, you can update both different https:// classifications and different classification values. <Server>:<Port>/sap/opu/ We recommend to use a batch request to update odata/SAP/ classification values for one classification only and we API_MKT_ML_CLASSIFICATION_S recommend to restict a batch request to one predic RV/$batch tive scenario only. The batch request is limited to 100,000 classification values. Add to the batch request header: Content-Type: multipart/mixed; boundary=batch; Add to the operation header: Sap-CuanSequenceId: CLASSIFICATION_BATCH_SINGLE Delete an existing classification value. Note The corresponding classification entity is not de leted, only the specified classification value. / ClassificationValues('<Pred ictiveScenario>,<MchnLrngTa rgetObject>,<MchnLrngClassi ficationVersion>,<Interacti onContactUUID=guid>,<MchnLr ngClfnStartDateTime>') MchnLrngScenarios Property Names and Descriptions The table below describes the properties for the entity MchnLrngScenarios. Property Name MachineLearningScenario Property Description Usage Contains the ID of the machine learning scenario. 730 PUBLIC Integration Guide Integration APIs Property Name MachineLearningScenarioText Property Description Contains the name of the machine learning scenario as it was defined in Predictive Studio. Usage You can perform the following operations on the MchnLrngScenarios entity set: HTTP Method GET Description Path Get a list of machine learning scenarios. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby /MchnLrngScenarios 5.2.14.3 Payload Examples (Deprecated) The following examples show how you can use the Classifications API. Classifications GET All Classifications Sample Code /sap/opu/odata/SAP/API_MKT_ML_CLASSIFICATION_SRV/Classifications GET one Classification Sample Code / Classifications(PredictiveScenario='CHURN_RENEWAL_SEASON_TICKET',MchnLrngTarge tObject='Season%20Ticket',MchnLrngClassificationVersion=1) POST one Classification Sample Code { "PredictiveScenario": "CHURN_RENEWAL_SEASON_TICKET", "MchnLrngTargetObject":"Season Ticket", "MchnLrngClassificationVersion": 1, "MchnLrngClassificationVersText": "Version 1.0" } Integration Guide Integration APIs PUBLIC 731 PUT one Classification Sample Code { "MchnLrngClassificationVersText": "Version 2.0" } PATCH one Classification Sample Code { "MchnLrngClassificationVersText": "Version 3.0" } PATCH Several Classifications in a Batch Request Sample Code --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary PATCH Classifications(PredictiveScenario='CHURN_RENEWAL_SEASON_TICKET',MchnLrngTarge tObject='Cloud',MchnLrngClassificationVersion=1) HTTP/1.1 Content-Type: application/json Content-Length: ### Sap-Cuan-SequenceId: CLASSIFICATION_BATCH_SINGLE { "MchnLrngClassificationVersText" : "Version 4.0" } --changeset---batch-- DELETE one Classification Sample Code / Classifications(PredictiveScenario='CHURN_RENEWAL_SEASON_TICKET',MchnLrngTarge tObject='Season%20Ticket',MchnLrngClassificationVersion=1) Classification Values GET All Classification Values Sample Code sap/opu/odata/SAP/API_MKT_ML_CLASSIFICATION_SRV/ClassificationValues?$top=50 732 PUBLIC Integration Guide Integration APIs Or: Sample Code --batch Content-Type: application/http Content-Transfer-Encoding: binary GET ClassificationValues?$top=50 HTTP/1.1 --batch-- GET one Classification Value Sample Code /sap/opu/odata/SAP/API_MKT_ML_CLASSIFICATION_SRV/ ClassificationValues(PredictiveScenario='CHURN_RENEWAL_SEASON_TICKET',MchnLrng TargetObject='Season %20Ticket',MchnLrngClassificationVersion=1,InteractionContactUUID=guid'0000c9e 9-49b6-1ed3-b3ddffffffffffff',MchnLrngClfnStartDateTime=datetimeoffset'2017-04-01T00%3A00%3A00 Z') Or: --batch Content-Type: application/http Content-Transfer-Encoding: binary GET ClassificationValues(PredictiveScenario='CHURN_RENEWAL_SEASON_TICKET',MchnLrng TargetObject='Season %20Ticket',MchnLrngClassificationVersion=1,InteractionContactUUID=guid'0000c9e 9-49b6-1ed3-b3ddffffffffffff',MchnLrngClfnStartDateTime=datetimeoffset'2017-04-01T00%3A00%3A00 Z') HTTP/1.1 --batch-- Sample Code POST Several Classification Values with Deep Create Sample Code { "PredictiveScenario": "CHURN_RENEWAL_SEASON_TICKET", "MchnLrngTargetObject":"Season Ticket", "MchnLrngClassificationVersion": 1, "MchnLrngClassificationVersText": "Version 1" "to_ClassificationValue": [ { "InteractionContactUUID": "00000000-49b6-1ed3-b48c-ffffffffffff", "PredictiveScenario": "CHURN_RENEWAL_SEASON_TICKET", "MchnLrngClfnStartDateTime": "2016-04-01T00:00:00", "MchnLrngTargetObject":"Season Ticket", "MchnLrngClassificationVersion": 1, "MchnLrngClfnEndDateTime": "2017-03-31T23:59:59", "MchnLrngClassificationValue": "1" }, Integration Guide Integration APIs PUBLIC 733 { "InteractionContactUUID":"0000c9e9-49b6-1ed3-b48c-ffffffffffff", "PredictiveScenario": "CHURN_RENEWAL_SEASON_TICKET", "MchnLrngClfnStartDateTime": "2016-04-01T00:00:00", "MchnLrngTargetObject":"Season Ticket", "MchnLrngClassificationVersion":1, "MchnLrngClfnEndDateTime": "2017-03-31T23:59:59", "MchnLrngClassificationValue": "0" } ] } POST one Classification Value Sample Code { "InteractionContactUUID": "00000000-49b6-1ed3-cccc-ffffffffffff", "PredictiveScenario": "CHURN_RENEWAL_SEASON_TICKET", "MchnLrngClfnStartDateTime": "2018-04-01T00:00:00", "MchnLrngTargetObject":"Season Ticket", "MchnLrngClassificationVersion": 1, "MchnLrngClfnEndDateTime": "2019-03-31T23:59:59", "MchnLrngClassificationValue": "0" } PUT one Classification Value Sample Code { "MchnLrngClfnEndDateTime": "2019-03-31T00:00:00", "MchnLrngClassificationValue" : "1" } PATCH one Classification Value Sample Code {"MchnLrngClfnEndDateTime": "2019-03-31T00:00:00", "MchnLrngClassificationValue" : "1" } PATCH Several Classification Values in a Batch Request You can use a batch request to update classification values that are related to one classification only. Sample Code --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary PATCH ClassificationValues(PredictiveScenario='CHURN_RENEWAL_SEASON_TICKET',MchnLrng TargetObject='Season 734 PUBLIC Integration Guide Integration APIs %20Ticket',MchnLrngClassificationVersion=1,InteractionContactUUID=guid'0000c9e 9-49b6-1ed3-b48cffffffffffff',MchnLrngClfnStartDateTime=datetimeoffset'2016-04-01T00%3A00%3A00 Z') HTTP/1.1 Content-Type: application/json Content-Length: ### Sap-Cuan-SequenceId: CLASSIFICATION_BATCH_SINGLE { "MchnLrngClassificationValue" : "1" } --changeset---batch-- DELETE one Classification Value Sample Code / ClassificationValues(PredictiveScenario='CHURN_RENEWAL_SEASON_TICKET',MchnLrng TargetObject='Season %20Ticket',MchnLrngClassificationVersion=1,InteractionContactUUID=guid'0000c9e 9-49b6-1ed3-b48cffffffffffff',MchnLrngClfnStartDateTime=datetimeoffset'2016-04-01T00%3A00%3A00 Z') Machine Learning Scenarios GET All Machine Learning Scenarios Sample Code /sap/opu/odata/SAP/API_MKT_ML_CLASSIFICATION_SRV/MchnLrngScenarios 5.2.15 Marketing Attribute Categories 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. Technical Data Name of the Service Communication Scenario IDs API_MKT_ATTRIBUTE_CATEGORY SAP_COM_0207 and SAP_COM_0017 Integration Guide Integration APIs PUBLIC 735 OData Version Root URI Service Metadata URI: Field Extensibility Supported 1.0 https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_ATTRIBUTE_CATEGORY_SRV https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_ATTRIBUTE_CATEGORY_SRV/$metadata No 5.2.15.1 Basic Concepts Creating and Updating Marketing Attribute Categories 1. Use the API_MKT_ATTRIBUTE_CATEGORY service to initially create the categories your require. With this service you can also load multiple language translations of the categories. 2. When you want to load individual marketing attribute values for your contacts, for example, to store their hobbies or the languages they speak, use the MarketingAttribute entity in the API_MKT_CONTACT service. Note The entity MarketingAttributeCategoryName is an alternative key for a marketing attribute category that can replace the entity MarketingAttributeCategory. In other words, we accept either MarketingAttributeCategory or MarketingAttributeCategoryName. If you send both, the MarketingAttributeCategoryName is ignored. This means: If you send only the MarketingAttributeCategoryName, a marketing attribute category is created with a technical key and a description is provided in MarketingAttributeCategoryName. If you send the MarketingAttributeCategory, a marketing attribute category is created with a generated description (a timestamp is added to the name). You can change this name in the app Marketing Attribute Categories. 3. Use the app Marketing Attribute Categories to translate existing marketing attribute categories into different languages. With the app, you can also delete categories. Note If multiple origins provide the same marketing attribute categories, these cannot be merged. Separate categories are created for each origin. 736 PUBLIC Integration Guide Integration APIs Full Update Blank entries overwrite existing entries. For example, if a marketing attribute category in the marketing system is stored with descriptions in the languages EN, DE, IT, and ES and a subsequent import only contains descriptions in the languages EN, DE, and IT, but not ES, the descriptions in language ES will be deleted. Consistency Checks The ODATA Service performs the following consistencies checks: Unknown language codes Description with language code missing Language code sent without a description No description sent at all Category sent more than once with different timestamps - the data set with the most recent timestamp is taken. Enty without an ID Enty without an ID Origin Error Message Handling 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. By default, data processing 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. To view the processing status and to check for errors or success messages, you must launch the Import Monitor app. In the event of errors, you can restart or discard the import in the Import Monitor. Integration Guide Integration APIs PUBLIC 737 5.2.15.2 Structure of API_MKT_ATTRIBUTE_CATEGORY This document describes the structure of the OData API service API_MKT_ATTRIBUTE_CATEGORY. Make sure you read the Basic Concepts topic before you start. Request Header The request header contains the following additional header fields: Property Sap-CuanRequestTimestamp Sap-CuanReferenceMessage Example '2017-09-28T12:13:14' 345g67980907 Description Edm Core Max.Le Man Type ngth datory Timestamp of the import run Edm.Date X in the format: number of mil Time liseconds since midnight Jan 1, 1970. For example: "/ Date(1406014140922)/" External reference of the in bound message Edm.Strin 32 g Entity Sets The MarketingAttributeCategory OData API provides the following entity sets: Entity Set MarketingAttributeCategories Description Path This entity contains the ID and the Ori /MarketingAttributeCategories gin of ID. Note If the same ID comes from multiple different origins, separate IDs are created. MarketingAttributeCategoryNames This entity contains the semantic name of the marketing attribute category in the relevant language. /MarketingAttributeCategoryNames 738 PUBLIC Integration Guide Integration APIs MarketingAttributeCategories POST: https://<Server>:<Port> /sap/opu/odata/SAP/API_MKT_ATTRIBUTE_CATEGORY_SRV/$batch. You can perform the following operation on the MarketingAttributeCategories entity set: HTTP Method POST Description Post a list of marketing attribute categories. Path / MarketingAttributeCategorie s?$top=1 MarketingAttributeCategoryNames POST: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_ATTRIBUTE_CATEGORY_SRV;v=0002/ MarketingAttributeCategoryNames You can perform the following operation on the MarketingAttributeCategoryName entity set: HTTP Method POST Description Post a list of marketing attribute category names. Path / MarketingAttributeCategoryNames ?$top=1 5.2.15.3 Payload Examples POST Marketing Attribute Categories 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 MarketingAttributeCategories HTTP/1.1 Content-Length: 1035 Accept: application/json Content-Type: application/json Sap-Cuan-RequestTimestamp: '2018-08-14T12:13:14' sap-Cuan-ReferenceMessage: '12345678' { "Id":"SH_20181029_001", "IdOrigin":"SAP_C4C_BUPA", Integration Guide Integration APIs PUBLIC 739 "MarketingAttributeCategoryNames": [ { "LanguageCode":"E", "Name":"FavouriteBook" } ] } --changeset_761e49b6-3146-4a57-8d10-15816fb9c75a---batch-- 5.2.16 Import Monitoring 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. Technical Data Name of the Service Authorizations Communication Scenario IDs OData Version Root URI Service Metadata URI Field Extensibility Supported API_MKT_IMPORT_MONITORING The following business catalog is required: SAP_CEC_BC_MKT_API_IC2_PC SAP_COM_0003, SAP_COM_0206, SAP_COM_0207, SAP_COM_0264. These are just some of the communication scenarios that implement this service. There may be others. 2.0 https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_IMPORT_MONITORING_SRV https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_IMPORT_MONITORING_SRV/ $metadata No Technical Field Documentation You can access detailed technical documentation for the API fields by downloading a metadata file in one of the following ways: 740 PUBLIC Integration Guide Integration APIs Access Link Remarks https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_IMPORT_MONITORING_SRV/ $metadata?sapdocumentation=all Only for internal access. You need to provide the server and port names. Marketing - Import Monitoring 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. Import Monitoring API General access link takes you directly to the Import Monitoring 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 5.2.16.1 Basic Concepts Use this API Service to read the specific messages that are triggered in the staging area when you call other API services. This service returns the notifications that are also output in the Import Monitor app. Use When you send data to the marketing system using a public API service, the import data can sometimes be processed in the staging area. The staging area returns a success message that the imported data is being processed. Using this service, you can query the status of the import, that is, whether import processing has been completed, as well as the status messages that are output, so that you can take prompt action where necessary. This is a read-only service. You can only perform GET operations with it. With authorization for this service, you have access to all import header messages. Integration Guide Integration APIs PUBLIC 741 5.2.16.2 Structure of OData Service API_MKT_IMPORT_MONITORING This document describes the structure of the Public OData API service API_MKT_IMPORT_MONITORING. Entities GET: Entity Path: /ImportHeaders You can perform the following operations on the ImportHeader entity set: HTTP Method GET Description Path Get a list of messages output for import headers. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby /ImportHeaders?$top=1 Note A maximum of 5000 import headers can be fetched in a single request. Specification of TOP is mandatory. Get the details of a specific import header using the / ImportHeader UUID. ImportHeaders(guid'<Import Header UUID>') Entity Path: /ImportAggregatedMessage You cannot perform GET operations on the ImportAggregatedMessage entity, but you can expand from a given import header. 5.2.16.3 Payload Examples for Import Monitoring The following examples show how you can use the Import Monitoring API service. GET Requests Get all messages for a single import header (XXXX = enter the respective GUID) /sap/opu/odata/SAP/API_MKT_IMPORT_MONITORING_SRV/ImportHeaders(guid'xxxxx')? $expand=HeaderToMessage 742 PUBLIC Integration Guide Integration APIs Get import headers with error messages /sap/opu/odata/SAP/API_MKT_IMPORT_MONITORING_SRV/ImportHeaders? $expand=HeaderToMessage&$top=2&$filter=Status eq '2' Get all messages for the top 2 import headers /sap/opu/odata/SAP/API_MKT_IMPORT_MONITORING_SRV/ImportHeaders? $expand=HeaderToMessage&$top=2 5.3 Landing Pages The following integration APIs are available for landing pages: External Landing Pages [page 743] External Landing Page Value Help [page 749] 5.3.1 External Landing Pages Public OData API (API_MKT_LANDING_PAGE) for writing external landing pages to the SAP Marketing Cloud system. The API service is part of communication scenario SAP_COM_0342. Caution It's possible to maintain two different target objects in the SAP Marketing Cloud system - Forms and Landing Pages. Depending on the target, you have the following options: To provide your external landing pages as forms, use https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_LANDING_PAGE_SRV/. This is the default. To provide your external landing pages as landing pages, use https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_LANDING_PAGE_SRV;v=0002/. Processing Information Requests can be submitted in batch mode or in non-batch mode. Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service as described in https://www.odata.org/ documentation/odata-version-2-0/uri-conventions/ . The batch request must contain a header parameter content-type, specifying the value multipart/mixed and boundary=batch. Root URI: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_LANDING_PAGE_SRV/ Integration Guide Integration APIs PUBLIC 743 Technical Data Technical Data of Service Name of Service OData Version Service Metadata URI Service Metadata UI for Documentation of Properties Communication Scenario ID Component for Incidents API_MKT_LANDING_PAGE 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_LANDING_PAGE_SRV/$metadata https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_LANDING_PAGE_SRV/$metadata?sap-documen tation=all SAP_COM_0342 CEC-MKT-LPC Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Field Extensibility Supported No 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 Target Object: Forms https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_LANDING_PAGE_SRV/ $metadata?sapdocumentation=all Only for internal access. You need to provide the server and port names. Target Object: Landing Pages https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_LANDING_PAGE_SRV;v=000 2/$metadata?sapdocumentation=all 744 PUBLIC Integration Guide Integration APIs Access Link External Landing Page Metadata (Forms) External Landing Page Metadata (Landing Pages)Version 2 External Landing Page Metadata (Forms) API External Landing Page Metadata (Landing Pages) Version 2 API Remarks 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. General access link takes you directly to the External Landing Pages metadata files. 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 Related Information Structure of OData Service API_MKT_LANDING_PAGE [page 746] Payload Examples [page 747] Integration Guide Integration APIs PUBLIC 745 5.3.1.1 Structure of OData Service API_MKT_LANDING_PAGE Complete list of entity sets for API_MKT_LANDING_PAGE. Structure of OData Service API_MKT_LANDING_PAGE OData Service Structure Entity LandingPage Publication LandingPages LandingPages Entity HTTP Method GET POST PATCH PUT Publications Publications Entity HTTP Method GET POST Description Path This entity contains the list of landing pages. /LandingPages This entity contains the list of publica tions for a landing page. /Publications Description Path Get the list of landing pages Get the details for a landing page GET /LandingPages GET /LandingPages(`Origin','External ID') Create a landing page POST /LandingPages Create or delta update of a landing page. This creates a landing page if it does not exist. PATCH /LandingPages(`Origin','External ID') Update a landing page PUT /LandingPages(`Origin','External ID') Description Get the list of publications Get the details for a publication Create a publication Path GET /Publications GET /Publications (`Key') POST /Publications 746 PUBLIC Integration Guide Integration APIs 5.3.1.2 Payload Examples The following examples show how you can use the External Landing Pages API. GET: Get a Landing Page and its Publications /sap/opu/odata/SAP/API_MKT_LANDING_PAGE_SRV/LandingPages?$filter=LandingPageOrigin eq 'origin' and LandingPageExternalId eq 'id'&$top=100&$expand=Publications& $select=Publications/LandingPagePublishedURL,Publications/ LandingPagePublicationUUID,Publications/LandingPageUUID POST: Landing Page Example 1 Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_1 --changeset_1 content-type: application/http content-transfer-encoding: binary POST LandingPages HTTP/1.1 Accept: application/json Content-Type: application/json { "LandingPageName" : "Landing Page Name", "LandingPageOrigin" : "Z_ORIGIN", "LandingPageExternalId" : "12345" } --changeset_1 content-type: application/http content-transfer-encoding: binary POST Publications HTTP/1.1 Accept: application/json Content-Type: application/json { "LandingPageOrigin" : "origin", "LandingPageExternalId" : "id", "LandingPagePublishedURL" : "http://www.<yourdomain>.com" } --changeset_1---batch-- Example 2 Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_1 --changeset_1 content-type: application/http Integration Guide Integration APIs PUBLIC 747 content-transfer-encoding: binary POST LandingPages HTTP/1.1 Accept: application/json Content-Type: application/json { "LandingPageName" : "Landing Page Name", "LandingPageOrigin" : "origin", "LandingPageExternalId" : "id", "Publications" : [ { "LandingPageOrigin" : "origin", "LandingPageExternalId" : "id", "LandingPagePublishedURL" : "http://www.<yourdomain>.com" } ] } --changeset_1---batch-- PATCH Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_1 --changeset_1 content-type: application/http content-transfer-encoding: binary PATCH LandingPages(LandingPageOrigin='origin',LandingPageExternalId='id') HTTP/1.1 Accept: application/json Content-Type: application/json { "LandingPageName" : "Landing Page Name", "LandingPageOrigin" : "origin", "LandingPageExternalId" : "id" } --changeset_1 content-type: application/http content-transfer-encoding: binary POST Publications HTTP/1.1 Accept: application/json Content-Type: application/json { "LandingPageOrigin" : "origin", "LandingPageExternalId" : "id", "LandingPagePublishedURL" : "http://www.<yourdomain>.com" } --changeset_1---batch-- 748 PUBLIC Integration Guide Integration APIs 5.3.2 External Landing Page Value Help Public OData API (API_MKT_LANDING_PAGE_VALUEHELP) for retrieving attribute values used in landing pages. The API supports 14 attributes, such as Countries, Communication Categories, Marketing Areas, and Forms of Address. The API service is part of communication scenario SAP_COM_0342. Processing Information For a complete list of all entity sets, see Structure of OData Service API_MKT_LANDING_PAGE_VALUEHELP [page 752]. Technical Data Technical Data of Service Name of Service OData Version Service Metadata URI Service Metadata UI for Documentation of Properties Communication Scenario ID Component for Incidents API_MKT_LANDING_PAGE_VALUEHELP 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_LANDING_PAGE_VALUEHELP_SRV/$metadata https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_LANDING_PAGE_VALUEHELP_SRV/$metadata? sap-documentation=all SAP_COM_0342 CEC-MKT-LPC Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Field Extensibility Supported No 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 749 Access Link Remarks https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_LANDING_PAGE_VALUEHELP _SRV/$metadata?sapdocumentation=all Only for internal access. You need to provide the server and port names. Marketing - Landing Page Value Help 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. External Landing Page Value Help API General access link takes you directly to the External Landing Page Value Help 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 Overview 11 of the 14 attributes consist of 3 properties. They follow the pattern: Code, Name/Description, and Language. Key fields are Code and Language. For example, the attribute Industries has a two-digit code for Industry and a name/description for IndustryName. The language in which an entry is returned is always called Language. The following are examples for the Industries attribute: Industry = 02 IndustryName = Financial Services Note Name properties always end with Name. Language = EN Or an entry as follows: Industry = 41 750 PUBLIC Integration Guide Integration APIs IndustryName = Iron and Steel Language = EN You can use a GET request with a filter in order to get a list of all Industry codes in English: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_LANDING_PAGE_VALUEHELP_SRV/ Industries?$filter=Language eq 'EN' 3 of the 14 attributes supported consist of 4 properties. The following table gives you an overview: Attributes and Properties Attribute Properties Description CommunicationCategory CommunicationCategory CommunicationCategoryName IsNewsletter Marketing Area The attribute does not have a Language property. The only key field is the code field CommunicationCategory. To retrieve only communication categories that can be subscribed to, you must set the filter IsNewsletter eq X. Marketing Area is also one of the properties, and there is also an attribute for Marketing Areas. The attribute is used to retrieve all active marketing areas. Interaction Types InteractionType InteractionTypeName CommunicationMedium Language Interaction Types is an attribute that has three key fields. In addition to the code of the interaction and the lan guage, the CommunicationMedium is needed to retrieve a unique interaction type. The communication medium must be set to WEB. Regions Region RegionName Country Language The attribute for Regions has an addi tional key field for the country code (two-letter). Root URI: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_LANDING_PAGE_VALUEHELP_SRV. Related Information Structure of OData Service API_MKT_LANDING_PAGE_VALUEHELP [page 752] Payload Examples [page 754] Integration Guide Integration APIs PUBLIC 751 5.3.2.1 Structure of OData Service API_MKT_LANDING_PAGE_VALUEHELP Complete list of entity sets for API_MKT_LANDING_PAGE_VALUEHELP. OData Service Structure Complete List of Entity Sets Entity Communication Category Country Department Function Gender Industry Interest Language Marital Status Marketing Area Region Description Path Contains all communication categories. Newsletters can be retrieved with filter IsNewsletter equal to `X'. /CommunicationCategories Contains all countries in all available /Countries languages. Uses two-digit country code. Contains company departments, for ex /Departments ample Human Resources. Contains professional functions, for ex /Functions ample Marketing Manager. Contains the values Gender not known, /Genders Female, and Male. Contains lines of business, for example /Industries Financial Services. Contains all interests that can be found /ItemsOfInterest in the system. Contains ISO Code, descriptions in all available languages, and the language of the description. /Languages A marital status can be Single or Mar ried, for example. /MaritalStatuses Delivers all active marketing areas. /MarketingAreas Contains all regions of countries in all available languages. Due to the large re sponse body, it is recommended to use a filter, for example Language equals EN. /Regions 752 PUBLIC Integration Guide Integration APIs Entity Form of Address Origin of ID Interaction Type Description Path Contains the salutation, for example Mr. /FormsOfAddress and Mrs. or Company. Contains the ID origin, for example, Phone Number or Email Address. /Origins Contains interaction types such as OptOut for Marketing Permission. It must be filtered by CommunicationMedium equals WEB. /InteractionTypes Only the HTTP method GET is supported. All properties of all entity types can be filtered. The filter for Language works with every attribute except Communication Categories as it is not translated. You should use the two-letter ISO code for the Language field. Key Fields List of Key Fields Entity Set Communication Category Country Department Function Gender Industry Interest Language Marital Status Marketing Area Region Form of Address Origin of ID Integration Guide Integration APIs Key Properties CommunicationCategory Country, Language Department, Language InteractionContactFunction, Language GenderCode, Language Industry, Language ItemOfInterest, Language LanguageISOCode, Language MaritalStatus, Language MarketingArea, Language Region, Country, Language FormOfAddress, Language InteractionContactOrigin, Language PUBLIC 753 Entity Set Interaction Type Key Properties InteractionType, CommunicationMedium, Language 5.3.2.2 Payload Examples The following examples show how you can use the External Landing Page Value Help API. Example 1 https://<Server>:<Port>/sap/opu/odata/sap/API_MKT_LANDING_PAGE_VALUEHELP_SRV/ Countries(Country='FR',Language='EN') Example 2 https://<Server>:<Port>/sap/opu/odata/sap/API_MKT_LANDING_PAGE_VALUEHELP_SRV/ Functions?$filter=InteractionContactFunctionName eq 'Marketing Manager' Example 3 https://<Server>:<Port>/sap/opu/odata/sap/API_MKT_LANDING_PAGE_VALUEHELP_SRV/ Regions(Region='BE',Country='DE',Language='EN') Example 4 https://<Server>:<Port>/sap/opu/odata/sap/api_mkt_landing_page_valuehelp_srv/ Departments?$filter=Language eq 'EN' 5.4 Segmentation 754 PUBLIC Integration Guide Integration APIs 5.4.1 Target Groups Public OData API (API_MKT_TARGET_GROUP_SRV) for Target Groups Overview [page 755] Overview The public API for Target Groups supports operations on the Target Group Business Object. OData Version Root URI Service Metadata URI Authorizations Component for Incidents 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_TARGET_GROUP_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_TARGET_GROUP_SRV/$metadata The following authorizations are required: Business Role: SAP_BCR_CEC_MKT_API_TGP_PC Business Catalog: SAP_CEC_BC_MKT_API_TGP_PC CEC-MKT-TG Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Communication Scenario ID Field Extensibility Supported SAP_COM_0205 No 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 https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_TARGET_GROUP_SRV/ $metadata?sapdocumentation=all Remarks Only for internal access. You need to provide the server and port names. Integration Guide Integration APIs PUBLIC 755 Access Link Marketing - Target Group Details Page Remarks 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. Target Groups API General access link takes you directly to the Target Groups metadata file. Onetime 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 Related Information https://api.sap.com 5.4.1.1 Structure of OData Service API_MKT_TARGET_GROUP_SRV This document describes the Public OData API serviceAPI_MKT_TARGET_GROUP_SRV for Target Groups. Entity Sets The Target Groups OData API provides the following entities: Entity Set TargetGroups Description Path This entity contains target /TargetGroups group data 756 PUBLIC Integration Guide Integration APIs Entity Set Description Path TargetGroupInteraction This entity contains the in Contacts teraction contacts of the target group /TargetGroups(guid`<Target Group UUID>`)/ TargetGroupInteractionContacts You can view sample payloads and test the API at https://api.sap.com . TargetGroups Resource Path: /TargetGroups You can perform the following operations on the TargetGroups entity set: Operations on TargetGroups entity set HTTP Method Description Path GET Get a list of Static, Dynamic, and Live target groups. This /TargetGroups?$top=<Number of method supports standard OData parameters such as target groups> $filter, $select, $top, $orderby and $skip. Note The $top parameter is mandatory. The $expand parameter is not supported. You can get only 100 target groups with each re quest. You can get only the Member Type 03 (Contacts) from a Target Group. POST Get the details of a specific target group using the Target Group UUID Create a Static target group /TargetGroups(guid`<Target Group UUID>`) /TargetGroups Custom operations on TargetGroups entity set HTTP Method Description Path POST Rebuild a Dynamic target group using the Target Group UUID /RebuildTargetGroup? TargetGroupUUID=guid'<Target Group UUID>' TargetGroupInteractionContacts Resource Path: /TargetGroups(guid`<Target Group UUID>`)/TargetGroupInteractionContacts You can perform the following operations on the TargetGroupInteractionContacts entity set: Integration Guide Integration APIs PUBLIC 757 Operations on TargetGroupInteractionContacts entity set HTTP Method Description URI GET Get Target Group Interaction Contacts of a URI for $top and $filter parameters: specific Interaction Contact Origin from the re quired target group. /TargetGroups(guid'<Target Group Note UUID>')/ TargetGroupInteractionContacts? You must pass the $top parameter to get the following properties: Target Group Interaction Contacts Interaction Contact Origin You can get only 1000 target group interaction contacts with each request. The $expand parameter is not supported. You must pass the $top and $filter parameters to get the following properties: $top=<Number of interaction contacts> & $filter=InteractionContactOrigin eq `<Channel or Origin of the Interaction Contact>' URI for $top and $select parameters: /TargetGroups(guid'<Target Group UUID>')/ Interaction Contact ID TargetGroupInteractionContacts? Interaction Contact Origin $top=<Number of interaction The $filter parameter is not mandatory in the following scenarios: You use the $select parameter to get the TargetGroupMemberUUID You use the $select parameter to get the InteractionContactUUID contacts>&$format=json& $select=TargetGroupMemberUUID,Int eractionContactUUID,TargetGroupUU ID You use the $select parameter to get the TargetGroupUUID To use the $filter parameter with Interaction Contact Origin, the Interaction Contact Origin must not be defined as Shareable in the system. POST Assign an Interaction Contact to a specific target group by using the Interaction Contact UUID. Note You can assign only the Member Type 03 (Contacts) to a Target Group. /TargetGroups(guid'<Target Group UUID>')/ TargetGroupInteractionContacts Assign an Interaction Contact to a specific target group by using the Interaction Contact ID and Interaction Contact Origin. /TargetGroups(guid'<Target Group UUID>')/ TargetGroupInteractionContacts Note To assign a contact, the Interaction Contact Origin must not be defined as Shareable in your system. 758 PUBLIC Integration Guide Integration APIs 5.4.1.2 Payload Examples The following examples show how you can use the Target Groups API. Note Delete request is not supported on Target Groups API. GET Requests - Examples Get the first 100 Target Groups /sap/opu/odata/SAP/API_MKT_TARGET_GROUP_SRV/TargetGroups?$format=json&$top=100 Get the first 100 Target Groups filtered by Target Group Type and LifeCycle Status /sap/opu/odata/SAP/API_MKT_TARGET_GROUP_SRV/TargetGroups? $filter=TargetGroupLifeCycleStatus eq '1' and TargetGroupCategoryName eq 'Static'& $top=100&$format=json Get the first 100 Target Groups filtered by Marketing Area and Segmentation Object /sap/opu/odata/SAP/API_MKT_TARGET_GROUP_SRV/TargetGroups?$filter=MarketingArea eq 'CXXGLOBAL' and SegmentationObject eq 'SAP_CONTACT_ENGAGEMENT_SIN'&$top=100& $format=json Get the first 1000 Contacts (UUID, Contact ID, and Contact Origin) belonging to a particular Target Group /sap/opu/odata/SAP/API_MKT_TARGET_GROUP_SRV/TargetGroups(guid'9CDCD400-0C70-1ED6BF9C-0C6E0BB242E9')/TargetGroupInteractionContacts?$filter=InteractionContactOrigin eq 'SAP_CRM_BUPA'& $select=InteractionContactUUID,TargetGroupUUID,InteractionContactId&$top=1000& $format=json POST Requests - Examples Create a Static Target Group /sap/opu/odata/SAP/API_MKT_TARGET_GROUP_SRV/TargetGroups Sample Code { "TargetGroupName" : "DR-TG-2018-04-20T12:36:04.0000000", "MarketingArea" : "GLOBAL", "TargetGroupDescription" : "This API supports only Static TG creation-2018-04-20T12:36:04.0000000", "TargetGroupMainResponsible" : "hsghds", "TargetGroupMemberType" : "03" Integration Guide Integration APIs PUBLIC 759 } Add a Contact, by its UUID to an existing Static Target Group /sap/opu/odata/SAP/API_MKT_TARGET_GROUP_SRV/TargetGroups(guid'9CDCD400-0C70-1ED6BF9C-0C6E0BB242E9')/TargetGroupInteractionContacts Sample Code { "InteractionContactUUID":"8CDCD400-0C70-1ED6-BF9C-0C6E0BB242E9", "TargetGroupUUID":"9CDCD400-0C70-1ED6-BF9C-0C6E0BB242E9" } Add a Contact, by its Contact ID and Contact Origin to an existing Static Target Group /sap/opu/odata/SAP/API_MKT_TARGET_GROUP_SRV/TargetGroups(guid'9CDCD400-0C70-1ED6BF9C-0C6E0BB242E9')/TargetGroupInteractionContacts Sample Code { "TargetGroupUUID":"9CDCD400-0C70-1ED6-BF9C-0C6E0BB242E9", "InteractionContactId":"321981", "InteractionContactOrigin":"SAP_CRM_BUPA" } OData Batch Requests - Examples POST a Target Group and Assign a Contact Using ICID and ICOrigin_$batch /sap/opu/odata/SAP/API_MKT_TARGET_GROUP_SRV/$batch Sample Code --batch_01869434-0005 Content-Type: multipart/mixed; boundary=changeset_01869434-0005-0001 --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST TargetGroups HTTP/1.1 Content-Type: application/json Content-Length: 1021 Content-ID: 1 {"TargetGroupName":"API TG_BATCH1 _2018-04-20T12:36:04.0000000","MarketingArea":"GLOBAL","TargetGroupMemberType" :"03"} --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST $1/TargetGroupInteractionContacts HTTP/1.1 Content-Type: application/json Content-Length: 1021 {"InteractionContactId":"321981","InteractionContactOrigin":"SAP_CRM_BUPA"} 760 PUBLIC Integration Guide Integration APIs --changeset_01869434-0005-0001---batch_01869434-0005-- 5.4.2 Export Target Groups and Target Group Member Data With this integration you can export target groups to an external system. For more information on how to export target group data, see: Create Export File Export Definitions 5.5 Campaign Management 5.5.1 Campaign and Target Group Data With the OData Service CUAN_INITIATIVE_SRV you can retrieve certain attributes of campaigns and target groups, for example, for the recommendation scenario. Overview With the OData Service CUAN_INITIATIVE_SRV you can to retrieve certain attributes of campaigns and target groups, for example, for the recommendation scenario. Details of the Service Entity URLs: https://<Server>:<Port>/sap/opu/odata/sap/CUAN_INITIATIVE_SRV/Initiatives https://<Server>:<Port>/sap/opu/odata/sap/CUAN_INITIATIVE_SRV/TargetGroups Request Mode: GET Entity Data Model: CUAN Initiative (CUAN_INITIATIVE) Support of OData Features: See the following chapters for implementation details and search behavior of the OData services. Integration Guide Integration APIs PUBLIC 761 Entity Type Initiative Entitty Type Property Description Edm Core Type Max Length Key Name The name of the cam Edm.String 40 No paign Description The description of the Edm.String n.a. No campaign InitiativeId The identifier of the Edm.String 10 Yes campaign InitiativeExt The external identifier Edm.String 10 No of the campaign LifeCycleStatus- The life cycle status Edm.String 1 No StatusCode code of the campaign LifeCycleStatus- The life cycle status Edm.String 60 No StatusDescription description of the cam paign Search-SearchTerm The search term of the Edm.String n.a. No campaign Search- The tile filter category Edm.String 2 No TileFilterCategor of the campaign y Category- The category code of Edm.String 3 No CategoryCode the campaign Category- The category descrip Edm.String 60 No CategoryDescripti tion of the campaign on Category- The category type of Edm.Int16 n.a. No CategoryType the campaign Filter- The interaction con Edm.String n.a. No InteractionContac tact identifier of the tId campaign Filter- The interaction con Edm.String 20 No InteractionContac tact identifier origin of tIdOrigin the campaign 762 PUBLIC Integration Guide Integration APIs Target Group Entity Type Property Description Edm Core Type Max Length Key TargetGroupId The identifier of the Edm.String 10 Yes target group CustomerMemberCou The customer member Edm.Int32 n.a. No nt count of the target group OData Service Call (GET) Examples Used in the Recommendation Scenario Searching campaigns with a search term and additional filters: Sample Code https://<Server>:<Port>/sap/opu/odata/sap/CUAN_INITIATIVE_SRV/Initiatives/? $expand=TargetGroup& $select=Name,Description,InitiativeId,InitiativeIdExt,LifecycleStatus,TargetGr oup/CustomerMemberCount&$filter=Search/SearchTerm eq 'tes' and Category/ CategoryCode eq '' and (Search/TileFilterCategory eq '1' or Search/ TileFilterCategory eq '2') Selecting a specific campaign to create a customer segment: Sample Code https://<Server>:<Port>/sap/opu/odata/sap/CUAN_INITIATIVE_SRV/ Initiatives('0000009108')/?$expand=TargetGroup& $select=Name,Description,InitiativeId,InitiativeIdExt,LifecycleStatus,TargetGr oup/CustomerMemberCount Getting campaigns for the current user with the specified filters: Sample Code https://<Server>:<Port>/sap/opu/odata/sap/CUAN_INITIATIVE_SRV/Initiatives/? $select=Name,Description,InitiativeId,InitiativeIdExt&$filter=Category/ CategoryCode eq '' and Search/TileFilterCategory eq '1' and (Filter/ InteractionContactId eq '1d998c85cc3d5205' or Filter/InteractionContactId eq 'john.dempsey@hana.com') and (Filter/InteractionContactIdOrigin eq 'EMAIL' or Filter/InteractionContactIdOrigin eq 'COOKIE_ID') 5.5.2 Campaign Execution Plans Campaign execution plans can be imported from other systems using a public OData application programming interface (API). You can use the public CUAN_MPO_IMPORT_SRV OData service to upload (import) campaign execution plans. The upload of campaign execution plans is always started through the ImportHeaders entity and a deep insert on the ExecPlanItem entity. Integration Guide Integration APIs PUBLIC 763 Entity Data Model The following tables list the details of the Campaign Execution Plan import service entities. OData Version Root URI Authorizations Support of OData Features 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ CUAN_MPO_IMPORT_SRV/ The following role is required: SAP_CEI_MPO_EXEC_PLAN_IMPORT See the following chapters for implementation details and search behavior of the OData services. Entity Data Model: ImportHeader Name Id Is Key TRUE Timestam FALSE p UserName FALSE SourceSy FALSE stemType SourceSy FALSE stemId ProcessA FALSE llOrNoth ing Edm Core Max Type Length Edm.Strin -g Edm.Strin -g Edm.Strin 12 g Edm.Strin 3 g Edm.Strin 20 g Edm.Boo -lean Creatable Updatable Sortable Nullable Filterable Complex Type Name TRUE FALSE FALSE FALSE FALSE n.a. TRUE FALSE FALSE TRUE FALSE n.a. TRUE FALSE FALSE TRUE FALSE n.a. TRUE FALSE FALSE FALSE FALSE n.a. TRUE FALSE FALSE FALSE FALSE n.a. TRUE FALSE FALSE TRUE FALSE n.a. Entity Data Model: ExecPlanItem Name Is Key Edm Core Max Type Length Creatable Updatable Sortable Nullable Filterable Complex Type Name Id TRUE Edm.Strin 10 FALSE FALSE FALSE FALSE FALSE n.a. g 764 PUBLIC Integration Guide Integration APIs Name Is Key Optimiza TRUE tionScen arioId Campaign FALSE Id Timestam FALSE p Interact FALSE ionConta ctId Edm Core Max Type Length Edm.Strin 20 g Creatable Updatable Sortable Nullable Filterable Complex Type Name TRUE FALSE FALSE FALSE FALSE n.a. Edm.Strin 10 g Edm.Date -Time Edm.Strin 255 g TRUE FALSE FALSE TRUE FALSE n.a. TRUE FALSE FALSE TRUE FALSE n.a. TRUE FALSE FALSE TRUE FALSE n.a. The OData service provides the basic CRUD services as follows: The upload of data is always started through the ImportHeaders entity and, in order to provide bulk processing, a deep insert on the ExecPlanItem entity (CREATE_DEEP_ENTITY). The fields of the OData entities have the following meaning: ImportHeader Id: A technical ID of one import service execution. In case no value is provided by the caller, an ID is generated by system. Timestamp: Timestamp of the import run. In case no value is provided by the caller, a timestamp is generated by the system. UserName: Name of the user who started the import. In case no value is provided by the caller, the system uses system name. SourceSystemType: The type of the source system and can be freely defined, for example, CRM or ERP. SourceSystemId: The ID of the source system and can be freely defined. ProcessAllOrNothing: In case an error occurrs, this flag defines if all imported offers are discarded or only the faulty ones. Default is true. ExecPlanItem Id OptimizationScenarioId CampaignId Timestamp InteractionContactId Integration Guide Integration APIs PUBLIC 765 Calling the OData Service Operation Create Request The upload of campaign execution plans is started as a post request through the ImportHeaders entity and a deep insert on the ExecPlanItem entity (CREATE_DEEP_ENTITY). The following example shows the coding for creating a campaign execution plan. URL (POST): /sap/opu/odata/sap/CUAN_MPO_IMPORT_SRV/ImportHeaders Sample Code POST data: { "Id" : "", "Timestamp" : "2016-07-01T08:10:12", "SourceSystemType" : "EXT", "SourceSystemId" : "JMeter_Auto", "ExecPlanItems" : [ { "Id" : "", "OptimizationScenarioId" : "PHONE", "CampaignId" : "234", "Timestamp" : "2016-06-16T13:10:12", "InteractionContactId" : "3440B5B11ACE1EE693DCDDFBB3B211B5" }, { "Id" : "", "OptimizationScenarioId" : "PHONE", "CampaignId" : "321", "Timestamp" : "2016-07-16T17:11:03", "InteractionContactId" : "3440B5B11ACE1EE69E934168A6E95CEE" } ] } Response Example for response in case of successful creation: Sample Code { : "d": : { : : "__metadata": : : { : : : "id":"<system>:<port>/sap/opu/odata/sap/CUAN_MPO_IMPORT_SRV/ ImportHeaders('E41D2DE534A01ED6A2F92AC2DD49165E')", : : : "uri":"<system>:<port>/sap/opu/odata/sap/CUAN_MPO_IMPORT_SRV/ ImportHeaders('E41D2DE534A01ED6A2F92AC2DD49165E')", : : : "type":"CUAN_MPO_IMPORT_SRV.ImportHeader" : : }, : : "Id":"E41D2DE534A01ED6A2F92AC2DD49165E", : : "Timestamp":"\/Date(1467360612000)\/", : : "SourceSystemType":"EXT", : : "SourceSystemId":"JMeter_Auto", : : "Username":"AUT_TESTER", : : "ProcessAllOrNothing":false, : : "ExecPlanItems":null : } } 766 PUBLIC Integration Guide Integration APIs 5.5.3 Campaigns Public OData API (API_MKT_CAMPAIGN_SRV) for Campaigns. Technical Data The public API for Campaigns supports operations on the Campaigns business object. Note We recommend that you use the current version 0003 of this service. Don't revert to using version 0002 once you start using version 0003 since this may result in data inconsistencies. However, if you want to continue using the previous version, you'll find the help link here: Campaigns API, Version 0002: Campaigns API, Version 0002 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_CAMPAIGN_SRV;V=3 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CAMPAIGN_SRV;V=3/$metadata The following business catalog role is required: SAP_CEC_BC_MKT_API_CPG3_PC SAP_COM_0204 CEC-MKT-CPG Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Yes 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 767 Access Link Remarks https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_SRV;v=0002/$m etadata?sap-documentation=all Only for internal access. You need to provide the server and port names. Marketing - Campaign 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. Campaigns API General access link takes you directly to the Campaign 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 5.5.3.1 Structure of API_MKT_CAMPAIGN_SRV Entities The Campaign OData API provides the following entities: Entity Description Path Campaigns This entity contains campaign data. /Campaigns AssignedTargetGroups This entity contains target groups that are assigned /CampaignAssignedTargetGroups to a campaign. TeamMembers This entity contains team members that are as signed to a campaign. /CampaignAssignedTeamMembers 768 PUBLIC Integration Guide Integration APIs Entity ActualSpends SpendHeaders ExternalCampaignRe ferences Interests SpendHeaderTimeS plits SpendItemTimeSplits SpendItems Description Path This entity provides information on the actual spend /ActualSpends amount and the committed amount of a campaign. This entity provides generic information about /SpendHeaders spend period, status and whether SpendItems ex ists or not. SpendHeaders contains data as soon as spend information for a campaign is maintained. This entity contains external campaigns that are as /ExternalCampaignReferences signed to a campaign. This entity contains interests that are assigned to a /CampaignAssignedInterests campaign. This entity exists for each SpendHeaders and pro /SpendHeaderTimeSplits vides information on how the planned spend header amount is distributed over the period. This entity exists for each SpendItem and provides /SpendItemTimeSplits information on how the planned spend item amount is distributed to the spend periods. This entity contains data as soon as a campaign is planned in detail. It provides generic information about the spend item itself and its spend period. /SpendItems You can view sample payloads and test the API at https://api.sap.com . Campaigns Resource Path: /Campaigns You can perform the following operations on the Campaigns entity set: Operations on Campaigns entity set HTTP Method Description Path GET Get a list of campaigns. This method supports standard OData parameters such /Campaigns?$top=1 as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby. Note The Campaigns OData API does not support Lead Transfer Campaigns (process type = `05'). A maximum of 100 campaigns can be fetched in a single request. Get the details of a specific campaign using the Campaign UUID. / Campaigns(guid'<Cam paign UUID>') Integration Guide Integration APIs PUBLIC 769 HTTP Method POST Description Get a list of campaigns. Get a specific campaign using the Campaign UUID. Get a list of target groups assigned to a specific campaign. Get a list of assigned team members to a campaign using the Campaign UUID. Get the actual spend of a specific campaign. Get a specific campaign's spend header information. Get a list of external campaign references from a specific campaign. Get a list of a campaign's assigned interests. Create a campaign. Create a campaign and assign a target group to the campaign by using the $batch parameter. Add a target group to a specific campaign. Path /Campaigns / Campaigns({Campaign UUID}) / Campaigns({Campaign UUID})/ CampaignAssignedTar getGroups / Campaigns({Campaign UUID})/ CampaignAssignedTea mMembers / Campaigns({Campaign UUID})/ CampaignActualSpend / Campaigns({Campaign UUID})/ CampaignSpendHeader / Campaigns({Campaign UUID})/ ExternalCampaignRef erences / Campaigns({Campaign UUID})/ CampaignAssignedInt erests /Campaigns /Campaigns/$batch / Campaigns({Campaign UUID})/ CampaignAssignedTar getGroups 770 PUBLIC Integration Guide Integration APIs HTTP Method PUT PATCH Description Path Assign team members to a specific campaign. / Campaigns({Campaign UUID})/ CampaignAssignedTea mMembers Add spend headers to a specific campaign. / Campaigns({Campaign UUID})/ CampaignSpendHeader Assign interests to a specific campaign. / Campaigns({Campaign UUID})/ CampaignAssignedInt erests Create a campaign from a template. / CreateCampaignFromT emplate Update the data for an In Preparation campaign. / Campaigns(guid'<Cam paign UUID>') Update the data for an In Preparation campaign. For example, you can update the Life Cycle Status of a campaign. / Campaigns({Campaign UUID}) AssignedTargetGroups Resource Path: /AssignedTargetGroups You can perform the following operations on the AssignedTargetGroups entity set: Operations on AssignedTargetGroups entity set HTTP Method Description GET Get a list of target groups assigned to the cam paign. Get the details of an assigned target group. Get the details of all target groups. Path /Campaigns({CampaignUUID})/ CampaignAssignedTargetGroups / AssignedTargetGroups(TargetGroupUUID={T argetGroupUUID},CampaignUUID={CampaignU UID}) /AssignedTargetGroups Integration Guide Integration APIs PUBLIC 771 HTTP Method POST DELETE Description Path Create an assigned target group for a specific campaign by using the Campaign UUID. /Campaigns({CampaignUUID})/ CampaignAssignedTargetGroups Assign target groups to a campaign. /AssignedTargetGroups Delete an assigned target group from a campaign. / AssignedTargetGroups(TargetGroupUUID={T argetGroupUUID},CampaignUUID={CampaignU UID}) TeamMembers Resource Path: /TeamMembers You can perform the following operations on the TeamMembers entity set: Operations on TeamMembers entity set HTTP Method Description GET Get a list of team members assigned to a specific campaign. Path /Campaigns({CampaignUUID})/ CampaignAssignedTeamMembers POST PATCH DELETE Get the details of an assigned team member. / TeamMembers(CampaignUUID={CampaignUUID}, TeamMemberName='{TeamMemberName}') Get the details of all team members. /TeamMembers Create an assigned interest for a specific campaign by using the Campaign UUID. /Campaigns({CampaignUUID})/ CampaignAssignedTeamMembers Add new team members. /TeamMembers Update the data of a team member. For ex ample, you can change the owner of a cam paign. / TeamMembers(CampaignUUID={CampaignUUID}, TeamMemberName='{TeamMemberName}') Delete an assigned team member from a campaign. / TeamMembers(CampaignUUID={CampaignUUID}, TeamMemberName='{TeamMemberName}') ActualSpends Resource Path: /ActualSpends 772 PUBLIC Integration Guide Integration APIs You can perform the following operations on the ActualSpends entity set: Operations on ActualSpends entity set HTTP Method Description Path GET Get a list of actual spends. /ActualSpends Get a list of actual spends for a specific campaign. / Campaigns({CampaignUUID})/ CampaignActualSpend Get actual spend information from a specific campaign. / ActualSpends({CampaignUUID }) SpendHeaders Resource Path: /SpendHeaders You can perform the following operations on the SpendHeaders entity set: Operations on SpendHeaders entity set HTTP Method Description Path GET Get specific spend header information. / SpendHeaders({MarketingSpe Note ndHeaderUUID}) Do not use GET SpendHeader if IsPlannedInDetail == true. Get a list of spend headers. /SpendHeaders Get a spend header for a campaign. / Campaigns({CampaignUUID})/ CampaignSpendHeader Get the header time split from a spe cific spend header. / SpendHeaders({MarketingSpe ndHeaderUUID})/ HeaderTimeSplit Get a list of items from a specific spend / header. SpendHeaders({MarketingSpe ndHeaderUUID})/Item Integration Guide Integration APIs PUBLIC 773 HTTP Method POST PATCH Description Path Create a spend header for an existing campaign. /SpendHeaders Deep create: Create a spend header in cluding its spend items and spend item time splits for an existing campaign. Add a campaign spend header to a spe / cific campaign. Campaigns({CampaignUUID})/ CampaignSpendHeader Add a list of items to a specific spend header. / SpendHeaders({MarketingSpe ndHeaderUUID})/Item Update a specific spend header. / SpendHeaders({MarketingSpe ndHeaderUUID}) ExternalCampaignReferences Resource Path: /ExternalCampaignReferences You can perform the following operations on the ExternalCampaignReferences entity set: Operations on ExternalCampaignReferences entity set HTTP Method Description Path GET Get a list of external campaign referen / ces for a specific campaign. Campaigns({CampaignUUID})/ ExternalCampaignReferences Get details of a specific external cam paign reference. / ExternalCampaignReference s({ExternalCampaignUUID}) Get a list of external campaign referen / ces. ExternalCampaignReferences Interests Resource Path: /Interests You can perform the following operations on the Interests entity set: 774 PUBLIC Integration Guide Integration APIs Operations on Interests entity set HTTP Method Description Path GET Get a list of interests assigned to a specific campaign. /Campaigns({CampaignUUID})/ CampaignAssignedInterests Get the details of an assigned interest. / Interests(CampaignUUID={CampaignUUID} ,InterestItem='{InterestItem}') Get the details of all interests. /Interests POST Create an assigned interest for a specific campaign by using the Campaign UUID. /Campaigns({CampaignUUID})/ CampaignAssignedInterests Add new interests. /Interests DELETE Delete an assigned interest from a campaign. / Interests(CampaignUUID={CampaignUUID} ,InterestItem='{InterestItem}') SpendHeaderTimeSplits Resource Path: /SpendHeaderTimeSplits You can perform the following operations on the SpendHeaderTimeSplits entity set: Operations on SpendHeaderTimeSplits entity set HTTP Method Description Path GET Get specific spend header time split in / formation. SpendHeaderTimeSplits({Mar ketingSpendHdrTimeSplitUUI D}) Get a list of spend header time splits. /SpendHeaderTimeSplits Get spend header time splits for a spe cific spend header. / SpendHeaders({MarketingSpe ndHeaderUUID})/ HeaderTimeSplit SpendItemTimeSplits Resource Path: /SpendItemTimeSplits Integration Guide Integration APIs PUBLIC 775 You can perform the following operations on theSpendItemTimeSplits entity set: Operations on SpendItemTimeSplits entity set HTTP Method Description Path GET Get specific spend item time split infor / mation. SpendItemTimeSplits({Marke tingSpendItmTimeSplitUUID} ) Get a list of spend item time splits. /SpendItemTimeSplits POST Get spend item time splits for a specific / spend item. SpendItems({MarketingSpend ItemUUID})/ItemTimeSplit Create spend item time splits. /SpendItemTimeSplits PATCH DELETE Create a spend item time split and add them to a specific spend item. / SpendItems({MarketingSpend ItemUUID})/ItemTimeSplit Update a specific spend item time split. / SpendItemTimeSplits({Marke tingSpendItmTimeSplitUUID} ) Delete a specific spend item time split. / SpendItemTimeSplits({Marke tingSpendItmTimeSplitUUID} ) SpendItems Resource Path: /SpendItems You can perform the following operations on theSpendItems entity set: Operations on SpendItems entity set HTTP Method Description Path GET Get specific spend item information. / SpendItems({MarketingSpend ItemUUID}) Get a list of spend items. /SpendItems Get spend items for a specific spend header. / SpendHeaders({MarketingSpe ndHeaderUUID})/Item 776 PUBLIC Integration Guide Integration APIs HTTP Method POST PATCH DELETE Description Path Get item time splits for a specific spend / item. SpendItems({MarketingSpend ItemUUID})/ItemTimeSplit Create a spend item. /SpendItems Deep create: Create a spend item in cluding its spend item time splits for an existing spend header. Add item time splits to a specific spend item. / SpendItems({MarketingSpend ItemUUID})/ItemTimeSplit Add items to a specific spend header. / SpendHeaders({MarketingSpe ndHeaderUUID})/Item Update a specific spend item. / SpendItems({MarketingSpend ItemUUID}) Delete a specific spend item and all re lated spend item time splits. / SpendItems({MarketingSpend ItemUUID}) 5.5.3.2 Payload Examples The following examples show how you can use the Campaigns API. GET Requests - Examples Get the First 100 Campaigns /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/Campaigns?$top=100&$format=json Get the First 100 Campaigns Filtered by Campaign Category and LifeCycle Status /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/Campaigns? $filter=CampaignLifecycleStatus eq '1' and CampaignCategory eq 'CME'&$top=100& $format=json Get the First 100 Campaigns Filtered by Marketing Area and Media Type /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/Campaigns?$filter=MediaType eq 'PRINT' and MarketingArea eq 'CXXGLOBAL'&$top=100&$format=json Integration Guide Integration APIs PUBLIC 777 Get a Campaign's Assigned Target Group, Interests, Assigned Team Members /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')? $expand=CampaignAssignedTargetGroups,CampaignAssignedInterests,CampaignAssignedTeam Members&$format=json POST Requests - Examples Post a Campaign /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/Campaigns Sample Code { "CampaignName": "Email Campaign 1SY 2018-04-20T12:36:04.0000000", "CampaignDescription" : "V2 New Description 2018-04-20T12:36:04.0000000", "MarketingArea" : "Global", "CampaignCategory" : "CME", "CommunicationCategoryUUID" : "1C98EC18-1855-1EE7-A8BF-713D0AF485F8", "MarketingProgramUUID": "0050569F-4A52-1ED7-8481-8A95A404CF53", "MediaType":"PRINT", "CampaignPriority" : "3", "CampaignExecutionFrqcyUnit" : "2" } Assign a Target Group to a Created Campaign /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/CampaignAssignedTargetGroups Sample Code { "TargetGroupUUID": "9CDCD400-0C70-1ED6-BF9C-0C6E0BB242E9" } Assign a Team Member to a Campaign /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/CampaignAssignedTeamMembers Assign an Interest to a Created Campaign /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/CampaignAssignedInterests Sample Code { "CampaignUUID":"94188283-1c7d-1ed9-82d1-59d7230c7110", "InterestItem": "CAMERA" 778 PUBLIC Integration Guide Integration APIs } Update Requests - Examples PUT a Campaign /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110') Sample Code { "CampaignName" : "Email Campaign 1SY 2018-04-20T12:36:04.0000000", "CampaignDescription" : "DR_PUT-DESC Change", "CampaignScheduleDateTime" : "2018-07-30T11:36:00", "CampaignExecutionFrqcyInterval" : "001", "CampaignExecutionFrqcyUnit" : "3", "MediaType":"PRINT", "MarketingProgramUUID" : "0050569F-4A52-1ED7-8481-8A95A404CF53", "CommunicationCategoryUUID" : "1C98EC18-1855-1EE7-A8BF-713D0AF485F8", "CampaignPriority" : "1", "CampaignStartDate" : "2018-06-22T00:00:00", "CampaignEndDate" : "2018-08-22T00:00:00", "CampaignOwner" : "CB9980000130" } PUT a Campaign's Team Member sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ TeamMembers(CampaignUUID=guid'94188283-1c7d-1ed9-82d1-59d7230c7110',TeamMemberName= 'CB9980000130') Sample Code { "TeamMemberName": "ERIKA", "IsOwner" : true } Delete Requests - Examples Unassign a Target Group from a Campaign /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ AssignedTargetGroups(TargetGroupUUID=guid'9CDCD400-0C70-1ED6BF9C-0C6E0BB242E9',CampaignUUID=guid'94188283-1c7d-1ed9-82d1-59d7230c7110') Integration Guide Integration APIs PUBLIC 779 Unassign a Team Member from a Campaign /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ TeamMembers(CampaignUUID=guid'94188283-1c7d-1ed9-82d1-59d7230c7110',TeamMemberName= 'CB9980000130') Unassign an Interest from a Campaign /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/ Interests(CampaignUUID=guid'94188283-1c7d-1ed9-82d1-59d7230c7110',InterestItem='CAM ERA') Batch OData Requests - Examples Create Campaigns in a Batch /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/$batch Sample Code --batch_020c-a527-decc Content-Type: multipart/mixed; boundary=changeset_9970-5898-d67d --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns?sap-client=100 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true Content-Type: application/json Content-Length: 588 {"CampaignName":"DR CPG -1 2018-04-20T12:36:04.0000000","CampaignDescription":"My CPG 2018-04-20T12:36:04.0000000","MarketingArea":"GLOBAL","CampaignCategory":"CME" } --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns?sap-client=100 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true Content-Type: application/json Content-Length: 588 {"CampaignName":"DR CPG -2 2018-04-20T12:36:04.0000000","CampaignDescription":"My CPG2018-04-20T12:36:04.0000000","MarketingArea":"GLOBAL","CampaignCategory":"C ME"} --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns?sap-client=100 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en 780 PUBLIC Integration Guide Integration APIs DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true Content-Type: application/json Content-Length: 588 {"CampaignName":"DR CPG -3 2018-04-20T12:36:04.0000000","CampaignDescription":"My CPG2018-04-20T12:36:04.0000000","MarketingArea":"GLOBAL","CampaignCategory":"C ME"} --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns?sap-client=100 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true Content-Type: application/json Content-Length: 588 {"CampaignName":"DR CPG -4 2018-04-20T12:36:04.0000000","CampaignDescription":"My CPG2018-04-20T12:36:04.0000000","MarketingArea":"2018-04-20T12:36:04.0000000", "CampaignCategory":"CME"} --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns?sap-client=100 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true Content-Type: application/json Content-Length: 588 {"CampaignName":"DR CPG -5 2018-04-20T12:36:04.0000000","CampaignDescription":"My CPG2018-04-20T12:36:04.0000000","MarketingArea":"GLOBAL","CampaignCategory":"C ME"} --changeset_9970-5898-d67d---batch_020c-a527-decc-- Assign Target Group to a Campaign in a Batch /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/$batch Sample Code --batchtest01 Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/ CampaignAssignedTargetGroups HTTP/1.1 Content-Type: application/json Content-Length: 588 { "CampaignUUID": "94188283-1c7d-1ed9-82d1-59d7230c7110", "TargetGroupUUID": "9CDCD400-0C70-1ED6-BF9C-0C6E0BB242E9" } --changeset Integration Guide Integration APIs PUBLIC 781 Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/ CampaignAssignedTargetGroups HTTP/1.1 Content-Type: application/atom+xml Content-Length: 588 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:CampaignUUID>94188283-1c7d-1ed9-82d1-59d7230c7110</d:CampaignUUID> <d:TargetGroupUUID>9CDCD400-0C70-1ED6-BF9C-0C6E0BB242E9</d:TargetGroupUUID> </m:properties> </atom:content> </atom:entry> --changeset---batchtest01-- Assign Team Members to a Campaign in a Batch /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/$batch Sample Code --batchtest Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/ CampaignAssignedTeamMembers HTTP/1.1 Content-Type: application/atom+xml Content-Length: 588 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:CampaignUUID>94188283-1c7d-1ed9-82d1-59d7230c7110</d:CampaignUUID> <d:TeamMemberName>CB9980000130</d:TeamMemberName> </m:properties> </atom:content> </atom:entry> --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/ CampaignAssignedTeamMembers HTTP/1.1 Content-Type: application/atom+xml Content-Length: 588 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:CampaignUUID>94188283-1c7d-1ed9-82d1-59d7230c7110</d:CampaignUUID> <d:TeamMemberName>CB9980000130</d:TeamMemberName> </m:properties> </atom:content> </atom:entry> --changeset-- 782 PUBLIC Integration Guide Integration APIs --batchtest-- Assign Interests to a Campaign in a Batch /sap/opu/odata/SAP/API_MKT_CAMPAIGN_SRV;v=3/$batch Sample Code --batchtest Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/ CampaignAssignedInterests HTTP/1.1 Content-Type: application/atom+xml Content-Length: 588 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:CampaignUUID>94188283-1c7d-1ed9-82d1-59d7230c7110</d:CampaignUUID> <d:InterestItem>CAMERA</d:InterestItem> </m:properties> </atom:content> </atom:entry> --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/ CampaignAssignedInterests HTTP/1.1 Content-Type: application/atom+xml Content-Length: 588 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:CampaignUUID>94188283-1c7d-1ed9-82d1-59d7230c7110</d:CampaignUUID> <d:InterestItem>CAMERA</d:InterestItem> </m:properties> </atom:content> </atom:entry> --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns(guid'94188283-1c7d-1ed9-82d1-59d7230c7110')/ CampaignAssignedInterests HTTP/1.1 Content-Type: application/atom+xml Content-Length: 588 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:CampaignUUID>94188283-1c7d-1ed9-82d1-59d7230c7110</d:CampaignUUID> <d:InterestItem>CAMERA</d:InterestItem> </m:properties> </atom:content> </atom:entry> --changeset---batchtest-- Integration Guide Integration APIs PUBLIC 783 Spend Header, Spend Item, and Spend Item Time Splits Create One Spend Header, One Spend Item, and Three Spend Item Time Splits The following is a deep create example using content-id and one batch request: Sample Code --batchtest_085421042017-0001 Content-Type: multipart/mixed; boundary=changeset_085421042017-0001-0001 --changeset_085421042017-0001-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST Campaigns HTTP/1.1 Content-Type: application/atom+xml Content-Length: 999 Content-ID: 1 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:CampaignName>Email Campaign Batch 1</d:CampaignName> <d:CampaignDescription>Email Campaign</d:CampaignDescription> <d:MarketingArea>GERMANY</d:MarketingArea> </m:properties> </atom:content> </atom:entry> --changeset_085421042017-0001-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST $1/CampaignSpendHeader HTTP/1.1 Content-Type: application/atom+xml Content-Length: 999 Content-ID: 2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingSpendPeriodStartYear>2018</d:MarketingSpendPeriodStartYear> <d:MarketingSpendPeriodStartMonth>01</d:MarketingSpendPeriodStartMonth> <d:MarketingSpendPeriodEndYear>2018</d:MarketingSpendPeriodEndYear> <d:MarketingSpendPeriodEndMonth>04</d:MarketingSpendPeriodEndMonth> <d:PlannedMktgSpendHeaderAmt>5000.00</d:PlannedMktgSpendHeaderAmt> <d:PlannedMktgSpendHeaderCrcy>USD</d:PlannedMktgSpendHeaderCrcy> </m:properties> </atom:content> </atom:entry> --changeset_085421042017-0001-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST $2/Item HTTP/1.1 Content-Type: application/atom+xml Content-Length: 999 Content-ID: 10 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 784 PUBLIC Integration Guide Integration APIs xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingSpendType>DIGITAL</d:MarketingSpendType> <d:MarketingSpendItemName>Digi Costs</d:MarketingSpendItemName> <d:MarketingSpendPeriodStartYear>2018</d:MarketingSpendPeriodStartYear> <d:MarketingSpendPeriodStartMonth>02</d:MarketingSpendPeriodStartMonth> <d:MarketingSpendPeriodEndYear>2018</d:MarketingSpendPeriodEndYear> <d:MarketingSpendPeriodEndMonth>04</d:MarketingSpendPeriodEndMonth> </m:properties> </atom:content> </atom:entry> --changeset_085421042017-0001-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST $10/ItemTimeSplit HTTP/1.1 Content-Type: application/atom+xml Content-Length: 999 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingSpendCalendarYear>2018</d:MarketingSpendCalendarYear> <d:MarketingSpendCalendarQuarter>1</d:MarketingSpendCalendarQuarter> <d:MarketingSpendCalendarMonth>02</d:MarketingSpendCalendarMonth> <d:PlannedMktgSpendAmt>2000.00</d:PlannedMktgSpendAmt> <d:PlannedMktgSpendCrcy>USD</d:PlannedMktgSpendCrcy> </m:properties> </atom:content> </atom:entry> --changeset_085421042017-0001-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST $10/ItemTimeSplit HTTP/1.1 Content-Type: application/atom+xml Content-Length: 999 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingSpendCalendarYear>2018</d:MarketingSpendCalendarYear> <d:MarketingSpendCalendarQuarter>1</d:MarketingSpendCalendarQuarter> <d:MarketingSpendCalendarMonth>03</d:MarketingSpendCalendarMonth> <d:PlannedMktgSpendAmt>3000.00</d:PlannedMktgSpendAmt> <d:PlannedMktgSpendCrcy>USD</d:PlannedMktgSpendCrcy> </m:properties> </atom:content> </atom:entry> --changeset_085421042017-0001-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST $10/ItemTimeSplit HTTP/1.1 Content-Type: application/atom+xml Content-Length: 999 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <atom:content type="application/xml"> <m:properties> <d:MarketingSpendCalendarYear>2018</d:MarketingSpendCalendarYear> <d:MarketingSpendCalendarQuarter>1</d:MarketingSpendCalendarQuarter> <d:MarketingSpendCalendarMonth>04</d:MarketingSpendCalendarMonth> <d:PlannedMktgSpendAmt>4000.00</d:PlannedMktgSpendAmt> Integration Guide Integration APIs PUBLIC 785 <d:PlannedMktgSpendCrcy>USD</d:PlannedMktgSpendCrcy> </m:properties> </atom:content> </atom:entry> --changeset_085421042017-0001-0001---batchtest_085421042017-0001-- Spend Header Create Spend Header Sample Code { "MarketingSpendStatus" : "00", "CampaignUUID" : "6C0B84B7-5523-1ED7-BBF7-F8A14CC949B6", "MarketingSpendPeriodStartYear" : "2018", "MarketingSpendPeriodStartMonth" : "03", "MarketingSpendPeriodEndYear" : "2018", "MarketingSpendPeriodEndMonth" : "04", "PlannedMktgSpendHeaderAmt" : "3000.00", "PlannedMktgSpendHeaderCrcy" : "USD" } Update Spend Header Period and Planned Spend Sample Code { "MarketingSpendPeriodStartYear" "MarketingSpendPeriodStartMonth" "MarketingSpendPeriodEndYear" "MarketingSpendPeriodEndMonth" "PlannedMktgSpendHeaderAmt" "PlannedMktgSpendHeaderCrcy" } : "2018", : "04", : "2018", : "05", : "10000", : "USD" Spend Item Create Spend Item Sample Code { "MarketingSpendHeaderUUID" : "6C0B84B7-5523-1EE7-BED2-B47CFBED5A07", "MarketingSpendType" : "DIGITAL", "MarketingSpendItemName" : "Print Costs", "MarketingSpendPeriodStartYear" : "2018", "MarketingSpendPeriodStartMonth" : "04", "MarketingSpendPeriodEndYear" : "2018", "MarketingSpendPeriodEndMonth" : "04" } 786 PUBLIC Integration Guide Integration APIs Create One Spend Item and 2 Spend Item Time Splits Sample Code { "MarketingSpendHeaderUUID" : "6C0B84B7-5523-1ED7-BED4-79CB3454407E", "MarketingSpendType" : "Print", "MarketingSpendItemName" : "Paper", "MarketingSpendPeriodStartYear" : "2018", "MarketingSpendPeriodStartMonth" : "04", "MarketingSpendPeriodEndYear" : "2018", "MarketingSpendPeriodEndMonth" : "05", "ItemTimeSplit" : [ { "MarketingSpendCalendarYear" : "2018", "MarketingSpendCalendarQuarter" : "2", "MarketingSpendCalendarMonth" : "04", "PlannedMktgSpendAmt" : "4000.00", "PlannedMktgSpendCrcy" : "USD" }, { "MarketingSpendCalendarYear" : "2018", "MarketingSpendCalendarQuarter" : "2", "MarketingSpendCalendarMonth" : "05", "PlannedMktgSpendAmt" : "5000.00", "PlannedMktgSpendCrcy" : "USD" } ] } Spend Item Time Splits Create Spend Item Time Splits Sample Code { "MarketingSpendItemUUID" : "6C0B84B7-5523-1ED8-80D0-9AAE7F2C3528", "MarketingSpendCalendarYear" : "2018", "MarketingSpendCalendarQuarter" : "1", "MarketingSpendCalendarMonth" : "03", "PlannedMktgSpendAmt" : "5999.00", "PlannedMktgSpendCrcy" : "USD" } Integration Guide Integration APIs PUBLIC 787 5.5.3.3 Function Imports Function imports are used to perform custom operations on an entity, in addition to typical OData operations. Create Campaign Using Campaign Template ID and Description HTTP Method POST Description Create a campaign using the campaign template ID and description Path / CreateCampaignFromT emplate? TemplateID='<Campai gn Template ID>'&CampaignName=' <Description>' 5.5.4 Campaign Templates Public OData API (API_MKT_CAMPAIGN_TEMPLATE_SRV) for Campaign Templates. Technical Data The public API for Campaign Templates supports operations on the Campaign Templates business object. OData Version Root URI Service Metadata URI Authorizations Communication Scenario ID 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CAMPAIGN_TEMPLATE_SRV https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CAMPAIGN_TEMPLATE _SRV/$metadata The following business catalog role is required: SAP_CEC_BC_MKT_API_CPG_PC SAP_COM_0204 788 PUBLIC Integration Guide Integration APIs Component for Incidents Field Extensibility Supported CEC-MKT-CPG Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. No 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_CAMPAIGN_TEMPLATE_SRV/ $metadata?sapdocumentation=all Only for internal access. You need to provide the server and port names. Marketing - Campaign Templates 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. Campaign Templates API General access link takes you directly to the Campaign Templates 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 Integration Guide Integration APIs PUBLIC 789 Related Information https://api.sap.com 5.5.4.1 Structure of API_MKT_CAMPAIGN_TEMPLATE_SRV Entity Data Model The Campaign Template OData API provides the following entities: Entity Description Path CampaignTemplates This entity contains campaign template data. /CampaignTemplates AssignedInterests This entity contains interests that are assigned to a /AssignedInterests campaign template. AssignedTargetGroups This entity contains target groups that are assigned /CampaignAssignedTargetGroups to a campaign template. TeamMembers This entity contains team members that are as signed to a campaign template. /TeamMembers You can view sample payloads and test the API at https://api.sap.com . CampaignTemplates Resource Path: /CampaignTemplates You can perform the following operations on the CampaignTemplates entity set: Operations on CampaignTemplates entity set HTTP Method Description Path GET Get a list of campaigns. This method supports standard OData parameters such /CampaignTemplates as $filter, $select, $top, $skip, $count, $inlinecount, and $orderby. Get the details of a specific campaign template using the Campaign Template ID. / CampaignTemplates(' {CampaignTemplate}' ) 790 PUBLIC Integration Guide Integration APIs AssignedInterests Resource Path: /AssignedInterests You can perform the following operations on the AssignedInterests entity set: Operations on AssignedInterests entity set HTTP Method Description GET Get a list of interests assigned to a specific campaign template. Get a list of assigned interests. Path / AssignedInterests(I temOfInterest='{Ite mOfInterest}',Campa ignTemplate='{Campa ignTemplate}') /AssignedInterests AssignedTargetGroups Resource Path: /AssignedTargetGroups You can perform the following operations on the AssignedTargetGroups entity set: Operations on AssignedTargetGroups entity set HTTP Method Description GET Get a list of assigned target groups. Get the details of an assigned target group. Path / AssignedTargetGroup s / AssignedTargetGroup s(TargetGroupUUID={ TargetGroupUUID},Ca mpaignTemplate='{Ca mpaignTemplate}') TeamMembers Resource Path: /TeamMembers Integration Guide Integration APIs PUBLIC 791 You can perform the following operations on the TeamMembers entity set: Operations on TeamMembers entity set HTTP Method Description GET Get a specific team member assigned to a campaign template. Get a list of team members. Path / TeamMembers(Campaig nTemplate='{Campaig nTemplate}',Campaig nTemplateTeamMember Name='{CampaignTemp lateTeamMemberName} ') /TeamMembers 5.5.4.2 Payload Examples The following examples show how you can use the Campaign Templates API. GET Requests - Examples Get the First 100 Campaign Templates /sap/opu/odata/sap/API_MKT_CAMPAIGN_TEMPLATE_SRV/CampaignTemplates?$top=100& $format=json Get the First 100 Campaign Templates Filtered by Campaign Category Type and Marketing Area /sap/opu/odata/sap/API_MKT_CAMPAIGN_TEMPLATE_SRV/CampaignTemplates? $filter=MarketingArea eq 'GLOBAL' and CampaignCategoryType eq 'FB'&$top=100& $format=json Get a Campaign Template's Assigned Target Group sap/opu/odata/sap/API_MKT_CAMPAIGN_TEMPLATE_SRV/CampaignTemplates('C000000BDA')/ to_AssignedTargetGroups?$format=json Get a Campaign Template's Assigned Team Member /sap/opu/odata/sap/API_MKT_CAMPAIGN_TEMPLATE_SRV/ CampaignTemplates('erika.mustermann@privat.de')/to_AssignedTeamMembers?top=5& $format=json Get a Campaign Template's Assigned Interest /sap/opu/odata/sap/API_MKT_CAMPAIGN_TEMPLATE_SRV/ CampaignTemplates('erika.mustermann@privat.de')/to_AssignedInterests?$$format=json 792 PUBLIC Integration Guide Integration APIs 5.5.5 Campaign Message Content and Personalized Email Content Public OData API (API_MKT_CAMPAIGN_MESSAGE_SRV) for exporting and importing message content in multiple languages. Overview The public API for Campaign Message Content supports the following operations for the Marketing Engagement Business Object: Note This function is not available for the new editor, that is message type Email Lite and Email Template Lite. Creating a message. For example, create an email or a text message using the MessageEntityType entity. Exporting the message content for defined languages Export messages as an HTML stream for defined languages. For example, you can use the exported HTML Message Content in a third-party HTML testing tool. Export the Message Block Content (HTML body and subject) and its condition assignments for defined languages. For example, you can use the exported HTML Message Block Content in a third-party translation tool. Importing the message content for defined languages Import the Message Block Content for defined languages. Import the Message Block Content. For example, importing the HTML content of an email message for a new message created using the entity MessageContentEntityType. Create the Message Block Content of the block and subject for new languages. Update the Message Block Content of the block and subject for existing languages. Assigning a marketing agency to a message. Fetching marketing agencies, assigned to a message. Querying all installed languages using the ValueHelps entity set. Querying for all marketing areas using the ValueHelps entity set. Updating the HTML message content of an existing message. The following restrictions apply: You cannot update the name of the message. You cannot update a reusable block. You cannot update the Confirmation (CON) content type. If the SUBJECT block type is not available in the file, the SUBJECT block is removed during the update. You can only update messages that have the status In Preparation. You can update the existing message if no other language other than the default language exists. You can update text messages, line messages, and mobile push notifications with a single block that only contains plain text. Integration Guide Integration APIs PUBLIC 793 Technical Data OData Version Root URI Service Metadata URI Authorizations Communication Scenario ID Component for Incidents Field Extensibility Supported Support of OData Features Feature Function Import Exception Handling 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/$metadata https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/$metadata?sapdocumentation=all The following business catalog role is required: SAP_CEC_BC_MKT_API_CMC_PC SAP_COM_0208 CEC-MKT-MEM Note Not to be used for HTTP errors. For more information, see HTTP Response Sta tus Codes [page 408]. No Support The Function Import GetPersonalizedMessages is called using REST GET and supports the following import parameters: CampaignOutbound='<the outbound id>' LinkTrackingIsDisabled=true/false Exceptions are caught and logged on top level of the service. Use Case You can use the Campaign Message Content (API_MKT_CAMPAIGN_MESSAGE_SRV) ODATA API for the following use cases: Use the API as a basis for collaborating with marketing agencies to create messages, and to map messages to agency users. An application that is built specifically for agencies or a third-party agency application can use this API and integrate this with the SAP Marketing Cloud system. Use the API to build a translation application for using translation as a service. The translation-as-a-service model enables translators to download messages and following translation, upload the translated content to the SAP Marketing Cloud system. Use the API to update the HTML message content of an existing message, if no other language other than the default language exists. You can use this functionality if an agency has uploaded an incorrect file, and the file has to be replaced instead of creating a message. 794 PUBLIC Integration Guide Integration APIs Use this API in a customer care scenario where a customer care executive can access the personalized user content for a particular user. For example, during a call with a certain customer, the customer care executive gets access to the personalized content. For this use case, link tracking can be disabled using the parameter LINKTRACKING_DISABLED = true. 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_CAMPAIGN_MESSAGE_SRV;v =0002/$metadata?sapdocumentation=all Only for internal access. You need to provide the server and port names. Marketing - Campaign Message Con tent Details Page General access to the Details page of the service on the SAP API Hub. One-time registration 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. Campaign Message Content API General access link takes you directly to the Campaign Message Content meta data 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 Entity Data Model for Personalized Email Content The following figure shows the entity data model (EDM) for this OData Service. Integration Guide Integration APIs PUBLIC 795 Permissions This feature can be enabled using the Business Role SAP_COM_CSR_0094. This feature must be assigned to a generic user for email recipients using a profile. The feature can be assigned to a specific user using a profile for call agents using this service. Add the following objects to the business role: Metadata: R3TR IWSG API_MKT_CAMPAIGN_MESSAGE_SRV_0001 Service: R3TR IWSV API_MKT_CAMPAIGN_MESSAGE_SRV 0001 Maintain the following authorization data for the business role: Authorization Object HPA_MKT_AR Authorization Field Activity MKTAREA_ID Display HPA_OBJ Display Object Name * CUAN_COMMUNICATION_CATEGORY CUAN_MARKETING_ENGAGEMENT CUAN_OFFER CUAN_PRODUCT CUAN_SENDER_PROFILE HPA_USER PRECO_SCENARIO 796 PUBLIC Integration Guide Integration APIs Authorization Object HPA_ME_TMP Authorization Field HPA_ME_TMP Activity Change Display Change Display Object Name CUAN_MARKETING_ENGAGEMENT HPA_USER Messages Template Entity Sets The Campaign Message Content OData API provides the following entity sets: Messages [page 798] MessageContents [page 800] Blocks [page 801] BlockContents [page 802] MarketingAgencies [page 806] ValueHelps [page 807] GetPersonalizedMessage [page 808] Entity Set Entity Type Description Path Messages MessageEntityType This entity set con tains all messages /Messages MessageContents MessageConten tEntityType This entity set con /MessageContents tains all message con tent. Blocks BlockEntityType This entity set con tains all blocks in a message. /Blocks BlockContents BlockContentEnti tyType This entity set con /BlockContents tains the contents of a block. MarketingAgencies MarketingAgen cyEntityType The entity represents a marketing agency with the assigned campaign message. /MarketingAgencies ValueHelps ValueHelpEntity Type The entity represents /ValueHelps a generic value help. Integration Guide Integration APIs PUBLIC 797 Entity Set GetPersonalized Messages Entity Type Description Path GetPersonalized MessageEntityType This entity set returns the personalized cam paign message con tent for a given cam paign execution out bound id as text. /GetPersonalizedMessages You can view sample payloads and test the API at https://api.sap.com . Messages Resource Path: /Messages You can perform the following operations on the Messages entity set: Operations on Messages entity set HTTP Method Description Path GET Get the list of all messages. This method supports standard https://<Server>:<Port>/sap/opu/ OData parameters such as $filter, $select, $top, and odata/SAP/ { "MessageName": "API New Message", "MessageType": API_MKT_CAMPAIGN_MESSAGE_SRV/ "EM", "MarketingArea": "GLOBAL", "DefaultLanguage": "DE", Messages?$top=<Number of "IsTemplate": "true" } $skip. messages> Note The $top parameter is mandatory. You can get only 100 messages with each request. POST Get a specific message using the Message UUID. Create a message. Note MessageType, MessageName, MarketingArea, and De faultLanguage are the mandatory parameters for creat ing a message. https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ Messages(guid`<Message UUID>`) https://<Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_SRV/ Messages Sample Payload { "MessageName": "API New Message", "MessageType": "EM", "MarketingArea": "GLOBAL", "DefaultLanguage": "DE", 798 PUBLIC Integration Guide Integration APIs "IsTemplate": "true" } The following table describes the properties for the Messages entity. Messages Property Names and Descriptions Property Name Property Description MessageUUID Message database key. Message Identifier of a message in SAP Marketing Cloud. MessageType The type of the message. Whether the message is an email or a text message. The possible values for the MessageType are: EM - email (additionally, if the IsTemplate flag is set, the message is an email template) LIN - LINE Message LP - Landing Page MPN - Mobile Push Notification SMS - Text Message MessageTypeName The description of the message type. MessageName The name of the message. MessageStatus The status of the message. MessageStatusName The description of the message status. CreationDateTime The creation date and time. LastChangeDateTime The last changed date and time. CreatedByUser The user who created the message. CreatedByUserName The user name of the user who created the message. LastChangeByUser The user who last modified the message. LastChangeByUserName The user name of the user who last modified the message. DefaultLanguage Identifier of the default language. For example: EN. DefaultLanguageName Description of the default language. For example: English. Integration Guide Integration APIs PUBLIC 799 Property Name IsTemplate MarketingArea MarketingAreaName Property Description Defines if the message is a template. Note IsTemplate = true is a valid combination only if Messa geType is email. ID of the marketing area. Name of the marketing area. MessageContents Resource Path: /MessageContents You can perform the following operations on the MessageContents entity set: Operations on MessageContents entity set HTTP Method Description Path GET POST Get all the message contents of a mes sage. https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_S RV/Messages(guid'<Message UUID>')/MessageContents Get the specific message content of a message. https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_S RV/ MessageContents(MessageUUI D=guid'<Message UUID>',LanguageCode=<Langu age Code>) Create message content. https:// <Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_S RV/MessageContents Payload Sample: { "MessageUUID":"6c0b84b7-5523-1ed7-bcbe-2fdf35bd42b3", "LanguageCode":"EN", "LanguageName":"English", 800 PUBLIC Integration Guide Integration APIs "MessageContentHTMLString":"<!DOCTYPE html><html><head><meta charset= \"UTF-8\"></head> <body></body></html>" } The following table describes the properties for MessageContents entity. Blocks Property Names and Descriptions Property Name Property Description MessageUUID Message database key. LanguageCode ISO code of the language. Note The value of LanguageCode must be the same as the DefaultLanguage of the corresponding message (Mes sageUUID). LanguageName MessageContentHTMLString The name of the language. The HTML content of the message. Blocks Resource Path: /Blocks You can perform the following operations on the Blocks entity set: Operations on Blocks entity set HTTP Method Description GET Get all blocks in a message in a specific language. Get a specific block using the Block entity. Path https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ MessageContents(MessageUUID=guid' <MessageUUID>',LanguageCode=<Lang uage Code>)/MessageBlocks https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ Blocks(guid'<Block UUID>') Integration Guide Integration APIs PUBLIC 801 HTTP Method Description POST Create a block using the Block entity. Note This method supports creation of deep entity. You can create a deep entity using the Block to create a BlockContents entity within a Block entity. Path https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ $batch https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ Blocks The following table describes the properties for the Blocks entity. Blocks Property Names and Descriptions Property Name Property Description BlockUUID ParentBlockUUID MessageUUID LanguageCode Block BlockType Unique identifier of a block in SAP Marketing Cloud. Unique identifier of a parent block in SAP Marketing Cloud. Unique identifier of a message in SAP Marketing Cloud. ISO code of the language. Identifier of the block. The following block types exist: TEXT, OFFER, PRODUCT, PROD_RECO, OFFER_RECO, ASC, ASC_PROD, and SUB JECT. Note The BlockType field has subblocks. The BlockType=ASC can have subblocks. The values for subblocks can be BlockType=ASC_PROD (Products) or BlockType=TEXT (Header or Footer). The ParentBlockUUID property re fers to an ASC parent-block within the subblock of an ASC parent-block. BlockReuseType Whether the BlockType is reusable. If the status is R, it is a reusable block with reference. Note The header and footer BlockType can be reused. BlockContents Resource Path: /BlockContents You can perform the following operations on the BlockContents entity set: 802 PUBLIC Integration Guide Integration APIs Operations on BlockContents entity set HTTP Method Description Path GET Get all Block Contents of a Block. https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ Blocks(guid'<Block UUID>')/ MessageBlockContents Get the specific Block Content of a Block. https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ BlockContents(guid'<Block Contents UUID>') POST Create block content using the Block Content entity. https://<Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ $batch https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_CAMPAIGN_MESSAGE_SRV/ BlockContents The following table describes the properties for BlockContents entity. BlockContents Property Names and Descriptions Property Name Property Description BlockContentUUID BlockUUID MessageUUID LanguageCode BlockContentConditionID BlockContentConditionName BlockContentHTMLString BlockContentType BlockPosition Unique identifier of block content in SAP Marketing Cloud. Unique identifier of a block in SAP Marketing Cloud. Unique identifier of a message in SAP Marketing Cloud. ISO code of the language. Identifier of the condition link with block content. Name of the condition link with block content. Block content in the form of HTML string. Type of the block content like subject, text, and so on. Block position in a message. For example: The position of the SUBJECT block has a fixed value of -2. The position of the BODY block has a fixed value of -1. All other blocks start with position 0. BlockContentStyleClasses Style classes used in block content. Integration Guide Integration APIs PUBLIC 803 Property Name BlockControl 804 PUBLIC Property Description Block Control Identifier. Note The defined JSON objects and their possible properties are as follows: If the BlockType: ASC, the possible property values are: "BlockControl" : "{\"SELECTION \":{\"LAYOUT\":{\"SHOW_HEADER \":true,\"SHOW_PRODUCTS\":true, \"SHOW_FOOTER\":true}, \"NO_MESSAGE_SEND_ON_ISSUES \":true}}" "BlockControlName" : """" "BlockControl" : "{\"SELECTION \":{\"LAYOUT\":{\"SHOW_HEADER \":true,\"SHOW_PRODUCTS\":true, \"SHOW_FOOTER\":false}, \"NO_MESSAGE_SEND_ON_ISSUES \":false}}" "BlockControlName" : "" If the BlockType: ASC_PROD, the possible property values are: "BlockControl" : "{\"SELECTION \":{\"MAX_ITEMS\":8}}" "BlockControlName" : "" "BlockControl" : "{\"SELECTION \":{\"MAX_ITEMS\":9999}}" "BlockControlName" : "" If the BlockType: OFFER, the possible property val ues are: "BlockControl" : "{\"ASSIGNMENT \":\"static\",\"SELECTION\": {\"ID\":\"0000004419\",\"CI_NAME \":\"\",\"COMM_MEDIUM\":\"EMAIL \",\"CONT_MEDIUM_TYPE\":\"01\", \"LANGUAGE\":\"EN\", \"NO_MESSAGE_SEND_ON_ISSUES \":true}}" "BlockControlName" : "4419 Image" "BlockControl" : "{\"ASSIGNMENT \":\"static\",\"SELECTION\": {\"NO_MESSAGE_SEND_ON_ISSUES \":true}}", "BlockControlName" : "" Integration Guide Integration APIs Property Name Integration Guide Integration APIs Property Description If the BlockType: OFFER_RECO, the possible prop erty values are: "BlockControl" : "{\"ASSIGNMENT \":\"offer_reco\",\"SELECTION\": {\"LEADING_ITEMS\":[{\"ITEMS\": [{\"DB_KEY\": \"FF91813198160B001600236CE9B411 D4\",\"NAME\":\"R-T215\"}, {\"DB_KEY\": \"FF93813198160B001600236CE9B411 D4\",\"NAME\":\"T-T109\"}], \"ITEM_TYPE\":\"CUAN_PRODUCT \"}],\"LEADING_CATEGORIES\": [{\"ITEMS\":[{\"DB_KEY\": \"JMAT_ProdCatHier_API_20170512205027_Cat_1\",\"NAME\": \"JMAT_ProdCatHier_API_20170512205027_Cat_1\"}],\"ITEM_TYPE\": \"CUAN_PRODUCT_CATEGORY\"}], \"POSITION\":\"TOP\",\"CNT_TYPE \":\"01\",\"MAX_ITEMS\": 5,\"MAX_RESULT\": 10,\"SCENARIO_ID\": \"LD_TEST_COUPON_USAGE\", \"TARGET\":\"\", \"NO_MESSAGE_SEND_ON_ISSUES \":true}}" "BlockControlName" : "LD_TEST_COUPON_USAGE" If the BlockType: PRODUCT, the possible property values are: "BlockControl" : "" "BlockControlName" : "" "BlockControl" : "{\"ASSIGNMENT \":\"static\",\"SELECTION\": {\"PRODUCT_ID\":\"R-T129\", \"PRODUCT_ORIGIN\": \"SAP_ERP_MATNR\", \"NO_MESSAGE_SEND_ON_ISSUES \":true}}" "BlockControlName" : "R-T129" If the BlockType: PROD_RECO, the possible prop erty values are: "BlockControl" : "" "BlockControlName" : "" "BlockControl" : "{\"ASSIGNMENT \":\"prod_reco\",\"SELECTION\": {\"LEADING_ITEMS\":[{\"ITEMS\": [],\"ITEM_TYPE\":\"CUAN_PRODUCT \"}],\"MAX_ITEMS\": 7,\"MAX_RESULT\": PUBLIC 805 Property Name BlockControlName Property Description 20,\"SCENARIO_ID\": \"SAP_MOST_VIEWED_EMAIL_CAMPAIGN \",\"TARGET\":\"\", \"NO_MESSAGE_SEND_ON_ISSUES \":false}}" "BlockControlName" : "SAP_MOST_VIEWED_EMAIL_CAMPAIGN" Block Control Name. MarketingAgencies Resource Path: /MarketingAgencies You can perform the following operations on the MarketingAgencyEntityType entity set: Operations on MarketingAgencyEntityType entity set HTTP Method Description GET Get a marketing agency to assign to a campaign mes sage. Get all marketing agencies. POST Create a marketing agency to assign to a campaign message. DELETE Delete a marketing agency assigned to a campaign message. Path https://<Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_SRV/ MarketingAgencies(MessageUUID=gui d'6c0b84b7-5523-1ed8-8bce-01d61d1 37b6f',MarketingAgencyUUID=guid'6 c0b84b7-5523-1ed7bdf5-5aab5e1f5e21') https://<Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_SRV/ MarketingAgencies https://<Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_SRV/ MarketingAgencies https://<Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_SRV/ MarketingAgencies(MessageUUID=gui d'6c0b84b7-5523-1ed8-8bce-01d61d1 37b6f',MarketingAgencyUUID=guid'6 c0b84b7-5523-1ed7bdf5-5aab5e1f5e21') Sample Payload: 806 PUBLIC Integration Guide Integration APIs { "MessageUUID":"6c0b84b7-5523-1ed8-8bce-01d61d137b6f", "MarketingAgencyUUID":"6c0b84b7-5523-1ed7-bdf5-5aab5e1f5e21", "MarketingAgency":"TLGG", "MarketingAgencyName":"TLGG" } The following table describes the properties for the MarketingAgencyEntityType entity. MarketingAgencyEntityType Property Names and Descriptions Property Name Property Description MessageUUID Unique identifier of the campaign message. MarketingAgencyUUID Unique identifier of the agency. MarketingAgency Identifier of the agency. MarketingAgencyName Name of the agency. EmailAddress Email-Address of the agency. ValueHelps Resource Path: /ValueHelps You can perform the following operations on the ValueHelps entity set: Operations on ValueHelps entity set HTTP Method Description GET Get all installed languages. Get all marketing areas. Get all marketing areas for an agency. Path https://<Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_SRV/ ValueHelps?$filter=ObjectType eq 'language' https://<Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_SRV/ ValueHelps?$filter=ObjectType eq 'marketing_area' https://<Server>:<Port>/sap/opu/ odata/sap/ API_MKT_CAMPAIGN_MESSAGE_SRV/ ValueHelps?$filter=ObjectType eq ' marketing_area ' and Filter/ Context1 eq '6C0B84B7-5523-1EE8-8B85-08415437 8FB6' The following table describes the properties for the ValueHelps entity. Integration Guide Integration APIs PUBLIC 807 ValueHelps Property Names and Descriptions Property Name ObjectType Code Description Filter Property Description Type of value help. The possible values are either MARKETING_AREA or LANGUAGE. Note The value of valuehelps entity set is not case-sensitive. Identifier of the value. For example, marketing area ID. Description of the value. For example, marking area descrip tion. Generic filter structure of ValueHelpFilterCT type. The con tent is dependent on the value of ObjectType property. ObjectType MARKET ING_AREA Filter Context1 Description Unique identifier of the agency. Note ValueHelpFilterCT is the generic type for the value help. GetPersonalizedMessage Operations CRUD Operations Do not exist for this OData service scenario. Custom or Service Operations HTTP Method GET Operation Type GetPersonalizedMessage URI /GetPersonalizedMessage Operations Request URI: /API_MKT_CAMPAIGN_MESSAGE_SRV/GetPersonalizedMessage Operation Type: Function Import HTTP Method: GET 808 PUBLIC Integration Guide Integration APIs Permissions: SAP Business Role SAP_COM_CSR_0094 Request Parameters Parameter Required CampaignOu Yes tbound LinkTracki Yes ngIsDisabl ed Data Type Edm.String Edm.Boolean Description Parameter Type The campaign outbound id hash key ID to identify the campaign, execution of the campaign and the recipient of the email. If set to `true', a link tracking interac Flag tion record is written to the database, if set to `false, no tracking record is written. Request Example API_MKT_CAMPAIGN_MESSAGE_SRV/GetPersonalizedMessage? CampaignOutbound='174A024EC5EAAC77D6BF115125D284E705C90F68'&LinkTrackingIsDisable d=false Response Status and Error Codes Code 200 400 Reason OK Bad Request Description Content found and returned Code = CUAN_ME/812 (Page not found.) means: No content could be determined using the CampaignOutbound (Id) specified. Related Information https://api.sap.com 5.5.5.1 Payload Examples The following examples show how you can use the Campaign Message Content API. GET Requests - Examples Get the First 100 Messages /sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/Messages?$top=100&$format=json Integration Guide Integration APIs PUBLIC 809 Get the First 100 Messages Filtered by MessageType and MessageStatus /sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/Messages?$filter=MessageStatus eq '10' and MessageType eq 'EM'&$top=100&$format=json Get a Message Content sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/ MessageContents(MessageUUID=guid'0050569F-4A52-1ED7-8481-8A95A404CF53',LanguageCode ='EN')?$select=MessageUUID,LanguageCode,LanguageName,MessageContentHTMLString& $format=json Get a Message Content's Message Blocks /sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/ MessageContents(MessageUUID=guid'0050569F-4A52-1ED7-8481-8A95A404CF53',LanguageCode ='EN')/MessageBlocks?$format=json Get a Block's Block Contents /sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/ Blocks(guid'0050569F-4A52-1ED7-8481-8A95A404CF53')/MessageBlockContents?& $format=json POST Requests - Examples Create a Message Block /sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/Blocks Sample Code { "MessageUUID" : "0050569F-4A52-1ED7-8481-8A95A404CF53", "LanguageCode" : "EN", "BlockType" : "Offer" } Create Block Content /sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/BlockContents Sample Code { "BlockUUID" : "0050569F-4A52-1ED7-8481-8A95A404CF53", "BlockContentHTMLString" : "The Message API creates a block content for a block-2018-04-20T12:36:04.0000000", "BlockContentConditionName" : "cond2018-04-20T12:36:04.0000000", "BlockPosition" : 2, "BlockControl" : "DR", "BlockControlName" : "Divya" } 810 PUBLIC Integration Guide Integration APIs Update Requests - Examples Put a Block Content /sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/ BlockContents(guid'{{New_BlCnt_UUID}}') Sample Code { "BlockContentHTMLString" : "PUT of Block content by DR on 2018-04-20T12:36:04.0000000", "BlockPosition" : 1, "BlockControl" : "DR-PUT", "BlockControlName" : "Divya-PUT" } OData Batch Requests - Examples Post Block and Block Content in a Batch /sap/opu/odata/SAP/API_MKT_CAMPAIGN_MESSAGE_SRV/$batch Sample Code --batch_01869434-0005 Content-Type: multipart/mixed; boundary=changeset_01869434-0005-0001 --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST Blocks HTTP/1.1 Content-Type: application/json Content-Length: 1021 Content-ID: 1 {"MessageUUID" : "0050569F-4A52-1ED7-8481-8A95A404CF53","LanguageCode" : "HE" , "BlockType" : "text"} --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST Blocks HTTP/1.1 Content-Type: application/json Content-Length: 1021 Content-ID: 2 {"MessageUUID" : "0050569F-4A52-1ED7-8481-8A95A404CF53","LanguageCode" : "RU","BlockType" : "offer" } --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST $1/MessageBlockContents HTTP/1.1 Content-Type: application/json Content-Length: 1021 Integration Guide Integration APIs PUBLIC 811 {"BlockContentType" : "agfs","BlockContentHTMLString" : "Post of content by Batch-1!!!","BlockContentConditionName" : "new cond1"} --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST $2/MessageBlockContents HTTP/1.1 Content-Type: application/json Content-Length: 1021 {"BlockContentType" : "adssd","BlockContentHTMLString" : "Post of content by Batch-2!!!","BlockContentConditionName" :"JULY13"} --changeset_01869434-0005-0001---batch_01869434-0005-- 5.5.6 Campaign Success Data Public OData API (API_MKT_CMPGN_SUCCESS_IMPORT) for importing aggregated success data for Campaigns. Technical Data Name of the Service Authorizations Communication Scenario ID OData Version Root URI Service Metadata URI Field Extensibility Supported API_MKT_CMPGN_SUCCESS_IMPORT The following business catalog role is required: SAP_CEC_BC_MKT_API_SUC_PC SAP_COM_0390 2.0 https://Server:Port/sap/opu/odata/SAP/ API_MKT_CMPGN_SUCCESS_IMPORT_SRV https://Server:Port/sap/opu/odata/SAP/ API_MKT_CMPGN_SUCCESS_IMPORT_SRV/ $metadata Yes Note The SAP_COM_0304 communication scenario that was previously used by this API is obsolete as of SAP Marketing Cloud. For detailed information about how to create a new communication arrangement using SAP_COM_0390, see SAP Note 2913447 . 812 PUBLIC Integration Guide Integration APIs Technical Field Documentation You can access technical documentation for the API fields at the following service metadata URL: https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_CMPGN_SUCCESS_IMPORT_SRV/ $metadata?sap-documentation=all. 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 5.5.6.1 Basic Concepts Campaign success data can provide insights that allow marketing teams to better plan and allocate campaign budget. Use the API_MKT_CMPGN_SUCCESS_IMPORT Public OData API to import aggregated campaign success data from external systems and write the data to campaigns in SAP Marketing Cloud. Processing Info The API_CMPGN_SUCCESS_IMPORT_SRV Public OData service only supports POST operations. Single requests are submitted as a single HTTP POST request to Successes endpoint. Batch requests are submitted as a single HTTP POST request to $batch endpoint. The batch request must contain a content-type header specifying a content type of multipart/mixed and a boundary specification. If data with the following properties is already stored in SAP Marketing Cloud, a POST request containing the same properties updates the data stored in SAP Marketing Cloud: Campaign ID Ext. Campaign ID This also includes the following: Advertiser ID Managing Party Ext. Cpg. System ID (Multichannel campaigns) Date This also includes the following: Time Zone Integration Guide Integration APIs PUBLIC 813 Year Month Year Week Communication Medium 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 batch request contains many sub-requests, the HTTP status code 202 is always returned. The real HTTP returning status code and messages are shown in the response body for each individual sub-request. 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. 5.5.6.2 Structure of OData Service API_MKT_CMPGN_SUCCESS_IMPORT This document describes the structure of the Public OData API service API_MKT_CMPGN_SUCCESS_IMPORT.Make sure you read the Basic Concepts topic before you start. Entity Set: Successes This Public OData API provides the Successes entity set, which contains campaign success data and resides in /Successes. You can perform the following operation on this entity set: HTTP Method POST Operation Single import of campaign success data. Batch import of campaign success data. URI /Successes /Successes/$batch Note This API is designed for use with communication users only. 814 PUBLIC Integration Guide Integration APIs 5.5.6.3 Payload Examples The following examples show how you can use the Campaign Success Data API. POST The following request is without batch: Sample Code { "CampaignID": "0000000001", "CampaignCategoryID": "EEM", "ExternalCampaignID": "ext1", "ExternalCampaignName": "ext1", "Advertiser": "Advertiser1", "AdvertiserName": "AdvertiserName1", "ExternalCmpgnManagingParty": "party1", "ExternalCmpgnManagingPartyName": "partyName1", "CommunicationMedium": "DISPLAY_ADS", "SuccessDataDate": "/Date(662725468168)/", "SuccessDataDateTimeZone":"UTC", "YearWeek": "", "YearMonth": "", "AdServingSpendAmount": "100", "AdServingSpendAmtCrcyISOCode": "USD", "SuggestedAdServingSpendAmount": "200", "AgeRangeLowerLimit": 9, "AgeRangeUpperLimit": 10, "GenderFreeText": "female", "CountryFreeText": "usa", "RegionFreeText": "region", "InteractionStatus": "99", "InteractionType": "InvalidType", "InteractionReason": "InvalidReason", "CampaignContent": 98, "CampaignContentName": "98name", "CampaignContentLinkName": "97Name", "DeviceFreeText": "device1", "AdNetworkFreeText": "AdNetwork1", "PaidSearchKeywordText": "searchKeywordBaidu", "PaidSearchSearchTermText": "SearchTermBaidu", "CampaignReach": "96", "CampaignReachInPercent": "101.02", "NumberOfImpressions": "11", "NumberOfClicks": "12", "NumberOfUniqueClicks": "13", "NumberOfPageLikes": "14", "NumberOfPostEngagements": "15", "NumberOfOfferClaims": "16", "NumberOfVideoViews": "17", "NumberOfWebsiteConversions": "18", "NumberOfAppInstalls": "19", "NumberOfAppEngagements": "20", "NumberOfEventResponses": "21", "NumberOfRejectedMessages": "22", "NumberOfSentMessages": "23", "NumberOfDeliveredMessages": "24", "NumberOfOpenedMessages": "25", Integration Guide Integration APIs PUBLIC 815 "NumberOfHardBounces": "26", "NumberOfSoftBounces": "27", "NumberOfOrders": "28", "OrderAmount": "29", "MultiTouchAttributedOrderAmt":"29", "OrderAmountCurrencyISOCode": "USD", "NrOfMultiTchAttrCnvrsns": "29", "ProjectedOrderAmount": "290", "ProjectedNumberOfConversions": "290", "NumberOfRegistrations": "30", "NumberOfDownloads": "31", "VideoViewedAverageInPercent": "32", "GrossRatingPoints": "33", "GrossRatingPointBase": "34", "NumberOfLeads": "35", "NumberOfOpportunities": "36", "OpportunityAmount": "37", "OpportunityAmountCrcyISOCode": "USD", "NumberOfPhoneCalls": "38", "NumberOfAppointments": "39", "NumberOfFailedInteractions": "40", "NumberOfMarketingOfferViews": "41", "NumberOfEmailComplaints": "42", "NmbrOfOpenChannelInteractions": "43", "NumberOfExecutedInteractions": "44", "NumberOfTasks": "45" } POST Sample Code --batchtest Content-Type: multipart/mixed; boundary=changeset_1 --changeset_1 Content-Type: application/http Content-Transfer-Encoding: binary POST Successes HTTP/1.1 Content-Type: application/json Content-Length: 168 { "CampaignID": "0000000004", "SuccessDataDate": "2017-08-03T00:00:00", "CommunicationMedium": "", "NrOfMultiTchAttrCnvrsns":"21.54", "MultiTouchAttributedOrderAmt":"2125.34", "OrderAmountCurrencyISOCode":"USD" } --changeset_1 Content-Type: application/http Content-Transfer-Encoding: binary POST Successes HTTP/1.1 Content-Type: application/json Content-Length: 168 { "CampaignID": "1000000004", "SuccessDataDate": "2017-08-04T00:00:00", "CommunicationMedium": "", "NrOfMultiTchAttrCnvrsns":"21.54", "MultiTouchAttributedOrderAmt":"2125.34", 816 PUBLIC Integration Guide Integration APIs "OrderAmountCurrencyISOCode":"USD" } --changeset_1---batchtest Content-Type: multipart/mixed; boundary=changeset_9970-5898-d67d --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary POST Successes HTTP/1.1 Content-Type: application/json Content-Length: 168 { "CampaignID": "0000000004", "SuccessDataDate": "2017-09-02T00:00:00", "CommunicationMedium": "", "NrOfMultiTchAttrCnvrsns":"22.34", "MultiTouchAttributedOrderAmt":"2225.34", "OrderAmountCurrencyISOCode":"USD" } --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary POST Successes HTTP/1.1 Content-Type: application/json Content-Length: 168 { "CampaignID": "00000000005", "SuccessDataDate": "2017-09-02T00:00:00", "CommunicationMedium": "", "NrOfMultiTchAttrCnvrsns":"22.34", "MultiTouchAttributedOrderAmt":"2225.34", "OrderAmountCurrencyISOCode":"USD" } --changeset_9970-5898-d67d---batchtest-- 5.5.7 Import Campaign Performance Data You have the following options for uploading success data: CSV Upload - Data File Load Public OData API - Campaign Success Data [page 812] OData Pull Interface for Externally Executed Campaigns - Implementing Interfaces for External Campaign Execution [page 157] You can also manually enter target data in the Campaigns app, in addition to using the CSV upload. Campaign performance data can also be automatically retrieved through standard processes in email and Facebook campaigns. When using any of the import methods, there are a few thinks you need to keep in mind about your data. Integration Guide Integration APIs PUBLIC 817 Different Drill-Down Depending on KPI Import Data by Campaign Importing success data on campaign level allows you to use cross-campaign reporting on campaign-related dimensions such as Campaign ID or Marketing Area. Example Data by Campaign Campaign ID Impressions Clicks 100 500 5 101 1000 10 Import Data with Drill-Downs by One or Several Dimensions Additional drill-downs allow for corresponding reporting, for example, over time when a success data date is given. Importing data with a different drill-down level for various KPIs is possible, as long as you ensure that the totals remain correct. Example In an email campaign with two different links, you can divide the clicks based on which link was clicked, as you can see here: Data with Drill-Downs by One or Several Dimensions Campaign ID Success Data Date Campaign Content Link Name Impressions Clicks 100 1.1.2016 1000 100 1.1.2016 Learn More 9 100 1.1.2016 Unsubscribe 1 Total Campaign 100 1000 10 Drilling down this way can impact calculated measures, such as Click-Through Rate (Clicks/Impressions * 100%). Both variables must be available on the same level to make the calculation. In the example above, there is no division of Impression on the Campaign Content Link Name level, therefore, you cannot calculate the Click-Through Rate based on the Campaign Content Link Name. However, at other drill-down levels, such as Success Data Date, you get the expected Click-Through Rate of 1%. Totals Must Be Correct Most imported measures like Number of Impressions, Number of Clicks or Ad Serving Spend Amount are aggregated by summing up the values. To ensure a consistent reporting you have to import the data in a way 818 PUBLIC Integration Guide Integration APIs that the totals are correct independent from any drilldown or filtering. In the following example, you are totalling up the number of impressions across two days, using a drilldown based on gender. These data sets do not overlap each other, providing you with an accurate total number of impressions over those two days. Correct Totals Campaign ID Success Data Date Gender Age Range Impressions 100 1.1.2016 female 1000 100 1.1.2016 male 1000 Subtotal 1.1.2016 2000 100 2.1.2016 female 1500 100 2.1.2016 male 1500 Subtotal 2.1.2016 3000 Total Campaign 100 5000 This means that you cannot combine overlapping data sets like, for example, gender and age range. If you total together the number of impressions drilled down by gender and the number of impressions drilled down by age range, you will count the same impressions twice. This leads to inconsistent data, as shown in the example below: Incorrect Totals Campaign ID Success Data Date Gender Age Range Impressions 100 1.1.2016 female 1000 100 1.1.2016 male 1500 100 1.1.2016 1824 500 100 1.1.2016 2534 2000 Subtotal 1.1.2016 5000 Subtotal All Genders (correct) 2500 Subtotal All Age Ranges (correct) 2500 Total Campaign 100 5000 Integration Guide Integration APIs PUBLIC 819 The total in the table above is incorrect, as the number of impressions has actually been counted twice. To avoid incorrect data, you would need to organize your data with a combined drill-down, as show below: Corrected Totals Campaign ID Success Data Date Gender Age Range Impressions 100 1.1.2016 female 1824 400 100 1.1.2016 female 2534 600 100 1.1.2016 male 1824 500 100 1.1.2016 male 2534 1000 Subtotal 1.1.2016 2500 Subtotal All Genders 2500 Subtotal All Age Ranges 2500 Total Campaign 100 2500 Aggregating Reach and Unique Clicks For Reach and Unique Clicks, there are two measures that count the number of different people who saw an ad or clicked a link. You have to be careful with summing these measures up. It is rather straightforward to measure the number of impressions, but connecting those to distinct individuals is a bit more complicated. You may have the same person view an ad or click a link more than once. For that reason it's strongly recommended to import data with no drill-down by Success Data Date for Reach and Unique Clicks. Note that a drill-down by Gender or Age Range is allowed, as one person typically doesn't change age range or gender during one campaign. You may want to be careful with cross campaign reporting on Reach and Unique Clicks, as well. Overlapping target groups may create incorrect results. Discrepancies in Amounts in Some Currencies Due to the difference in the number of decimal places stored for monetary amounts in different systems, there may be a discrepancy when viewing these amounts in the different systems. In SAP Marketing Cloud, the number of decimal places in an amount depends on the currency. For example, an amount in USD is stored with two decimal places, while an amount in JPY is stored with no decimal places. However, some other systems may send amounts with more decimal places than are stored in SAP Marketing Cloud. These additional digits are cut off, which may result in minor differences when looking at totals. 820 PUBLIC Integration Guide Integration APIs Overwriting Data by Date and Campaign ID The semantical key of the data consists of the SAP Marketing Cloud Campaign ID, External Campaign ID (including Advertiser and Managing Party), Date, Time Unit, Communication Medium, and Input Method. To overwrite data, you must upload aggregated success data with the same success data date and external campaign ID as the data you wish to overwrite. This will overwrite all of the success data for that date and campaign ID combination. The success data date is optional. If no success data date is given with the imported data, all other success data of the referenced external campaign ID without a success data date will be overwritten. To delete aggregated success data, you can upload a CSV file with the success data date and external campaign ID of the data you wish to delete and leave the rest of fields blank. This will cause of the success data to be overwritten with empty fields, essentially deleting the data. Related Information Campaign Performance Interaction and Aggregated Success Data Custom Fields for Campaign Performance Assigning External References to Externally Executed, Facebook, and Google Ads Campaigns 5.5.7.1 Campaign Performance Measures and Dimensions The list of measures and dimensions for campaign performance. To overwrite data, you must upload aggregated success data with the same semantic key as the data you wish to overwrite. This will overwrite all of the success data for that key combination. The semantic key for overwriting data can consist of the following: Campaign ID Ext. Campaign ID This also includes the following: Advertiser ID Managing Party Ext. Cpg. System ID (Multichannel campaigns) Date This also includes the following: Time Zone Year Month Year Week Communication Medium Integration Guide Integration APIs PUBLIC 821 Global Field Name CalendarYear Label Calendar Year Type Performance Dimension CampaignCon tentLinkAlias Name Link Alias Performance Dimension PaidSearchKey Baidu Key Word Performance WordText Dimension PaidSearch SearchTerm Text Baidu Search Term Performance Dimension Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Calendar year the campaign performance measures refer to Alias name of the link in the campaign con tent the cam paign perform ance measures refer to CampaignCon tentLinkAlias Name Old CSV: CAM PAIGNCON TENTLINKA LIASNAME CampaignCon tentLinkAlias Name The key word of a paid search campaign the campaign per formance measures refer to, in standard processes used for Baidu cam paigns only PaidSearchKey WordText PaidSearchKey WordText PaidSearchKey wordText The search term of a paid search cam paign the cam paign perform ance measures refer to, in standard proc esses used for Baidu cam paigns only PaidSearch SearchTerm Text PaidSearch SearchTerm Text PaidSearch SearchTerm Text 822 PUBLIC Integration Guide Integration APIs Global Field Name TargetAdSer vingCostPer Click Label Target CPC Type Target TargetAdSer vingCostPer Lead Target Cost per Target Lead Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Not shown on TargetAdSer the campaign vingCostPer UI - use Click and TgtAdSrvg TgtAdSrvg Cost SpendTran Per1000Clicks sCurrency with instead. Target CampaignPer value for ad formanceType= serving cost per "TARGET" only click, there is no meaningful ag gregation possi ble, technically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Target value for ad serving cost per lead, there is no meaning ful aggregation possible, tech nically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TargetAdSer vingCostPer Lead and TgtAdSrvg SpendTran sCurrency with CampaignPer formanceType= "TARGET" only Integration Guide Integration APIs PUBLIC 823 Global Field Name Label TargetAdSer vingCostPerOr der Target Order Cost Type Target TargetAdSer vingCostPer Regn Target Reg Cost Target Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for ad serving cost per order, there is no meaning ful aggregation possible, tech nically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TargetAdSer vingCostPerOr der and TgtAdSrvg SpendTran sCurrency with CampaignPer formanceType= "TARGET" only Target value for TargetAdSer ad serving cost vingCostPer per registration, Regn and there is no TgtAdSrvg meaningful ag SpendTran gregation possi sCurrency with ble, technically CampaignPer summed up formanceType= when aggre "TARGET" only gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation 824 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TargetAdSrvg Tgt 1000 Reach Target Cost1000Reach Cost Target value for TargetAdSrvg ad serving cost Cost1000Reach per 1000 peo and TgtAdSrvg ple reached, SpendTran there is no sCurrency with meaningful ag CampaignPer gregation possi formanceType= ble, technically "TARGET" only summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TargetAdSrvg CostPerE ventRsp Tgt Event Rsp Cost Target Target value for ad serving cost per event re sponse, there is no meaningful aggregation possible, tech nically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TargetAdSrvg CostPerE ventRsp and TgtAdSrvg SpendTran sCurrency with CampaignPer formanceType= "TARGET" only TargetAdSrvg CostPerLea dInDC Target Cost per Lead Converted Amount in Dis play Currency Target value for the ad serving cost per lead converted to the display cur rency using the currency ex change rate of the campaign start date Integration Guide Integration APIs PUBLIC 825 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TargetAdSrvg CostPerPage Like Tgt Page Like Cost Target Target value for TargetAdSrvg ad serving cost CostPerPage per page like, Like and there is no TgtAdSrvg meaningful ag SpendTran gregation possi sCurrency with ble, technically CampaignPer summed up formanceType= when aggre "TARGET" only gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TargetAdSrvg CostPerReg nInDC Target Reg Cost Converted Amount in Dis play Currency Target value for the ad serving cost per regis tration con verted to the display cur rency using the currency ex change rate of the campaign start date TargetBoun ceRateInPer cent Target Bounce Target Rate Target value for bounce rate in percent, there is no meaning ful aggregation possible, tech nically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TargetBoun ceRateInPer cent with Cam paignPerfor manceType= "TARGET" only 826 PUBLIC Integration Guide Integration APIs Global Field Name TargetClick ThroughRa teInPct Label Target CTR Type Target TargetClickToO Target Click penRateInPct Open Target Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for TargetClick click-through ThroughRa rate in percent, teInPct with there is no CampaignPer meaningful ag formanceType= gregation possi "TARGET" only ble, technically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Target value for TargetClickToO click-to-open penRateInPct rate in percent, with Campaign there is no Performance meaningful ag Type= "TAR gregation possi GET" only ble, technically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Integration Guide Integration APIs PUBLIC 827 Global Field Name Label TgtAdServing CostPerDown load Target Down load Cost TgtAdSrvg Target CPC Cost1000Click (1000) sInDC TgtAdSrvg Cost1000Im prsnsInDC Target CPM (1000) Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target Target value for TgtAdServing ad serving cost CostPerDown per download, load and there is no TgtAdSrvg meaningful ag SpendTran gregation possi sCurrency with ble, technically CampaignPer summed up formanceType= when aggre "TARGET" only gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Converted Amount in Dis play Currency Target value for the ad serving cost per 1000 clicks con verted to the display cur rency using the currency ex change rate of the campaign start date Converted Amount in Dis play Currency Target value for the ad serving cost per 1000 impressions converted to the display cur rency using the currency ex change rate of the campaign start date 828 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TgtAdSrvg Tgt 1000 Reach Converted Cost1000Reach Cost Amount in Dis InDC play Currency Target value for the ad serving cost per 1000 people reached converted to the display cur rency using the currency ex change rate of the campaign start date TgtAdSrvg Cost1000Vid eoViews Tgt Cost 1000 Views Target Target value for ad serving cost per 1000 video views, there is no meaningful aggregation possible, tech nically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TgtAdSrvg Cost1000Vid eoViews and TgtAdSrvg SpendTran sCurrency with CampaignPer formanceType= "TARGET" only TgtAdSrvg Tgt Cost 1000 Cost1000VidVw Views sInDC Converted Amount in Dis play Currency Target value for the ad serving cost per 1000 video views converted to the display cur rency using the currency ex change rate of the campaign start date Integration Guide Integration APIs PUBLIC 829 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TgtAdSrvgCos tAppEngmn tInDC Tgt App Engmnt Converted Cost Amount in Dis play Currency Target value for the ad serving cost per app engagement converted to the display cur rency using the currency ex change rate of the campaign start date TgtAdSrvgCos Tgt App Install tAppInstallInDC Cost Converted Amount in Dis play Currency Target value for the ad serving cost per app in stall converted to the display currency using the currency exchange rate of the campaign start date TgtAdSrvgCost Target Down DownloadInDC load Cost Converted Amount in Dis play Currency Target value for the ad serving cost per down load converted to the display currency using the currency exchange rate of the campaign start date TgtAdSrvgCos Tgt Event Rsp tEventRspInDC Cost Converted Amount in Dis play Currency Target value for the ad serving cost per event response con verted to the display cur rency using the currency ex change rate of the campaign start date 830 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TgtAdSrvgCost Target Cost per Target GrossRatingPt GRP Target value for ad serving cost per gross rating point, there is no meaningful aggregation possible, tech nically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TgtAdSrvgCost GrossRatingPt and TgtAdSrvg SpendTran sCurrency with CampaignPer formanceType= "TARGET" only TgtAdSrvg Target Cost per CostGrssRatgP GRP tInDC Converted Amount in Dis play Currency Target value for the ad serving cost per gross rating point converted to the display cur rency using the currency ex change rate of the campaign start date TgtAdSrvg Tgt Offer Claim CostMktgOffer Cost Claim Target Target value for TgtAdSrvg ad serving cost CostMktgOffer per offer claim, Claim and there is no TgtAdSrvg meaningful ag SpendTran gregation possi sCurrency with ble, technically CampaignPer summed up formanceType= when aggre "TARGET" only gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Integration Guide Integration APIs PUBLIC 831 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TgtAdSrvgCos tOfferClai mInDC Tgt Offer Claim Cost Converted Amount in Dis play Currency Target value for the ad serving cost per offer claim converted to the display currency using the currency exchange rate of the campaign start date TgtAdSrvg Cost Per1000Clicks Target CPC (1000) Target Target value for TgtAdSrvg ad serving cost Cost per 1000 clicks, Per1000Clicks there is no and TgtAdSrvg meaningful ag SpendTran gregation possi sCurrency with ble, technically CampaignPer summed up formanceType= when aggre "TARGET" only gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TgtAdSrvg Cost Per1000Imprsn s Target CPM Target Target value for TgtAdSrvg ad serving cost Cost per 1000 im Per1000Imprsn pressions, there s and is no meaning TgtAdSrvg ful aggregation SpendTran possible, tech sCurrency with nically summed CampaignPer up when aggre formanceType= gated, don't set "TARGET" only this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation 832 PUBLIC Integration Guide Integration APIs Global Field Name Label Type TgtAdSrvgCost Tgt App Engmnt Target PerAppEngmnt Cost TgtAdSrvgCost Tgt App Install Target PerAppInstall Cost Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for TgtAdSrvgCost ad serving cost PerAppEngmnt per app en and TgtAdSrvg gagement, SpendTran there is no sCurrency with meaningful ag CampaignPer gregation possi formanceType= ble, technically "TARGET" only summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Target value for TgtAdSrvgCost ad serving cost PerAppInstall per app install, and TgtAdSrvg there is no SpendTran meaningful ag sCurrency with gregation possi CampaignPer ble, technically formanceType= summed up "TARGET" only when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Integration Guide Integration APIs PUBLIC 833 Global Field Name Label TgtAdSrvgCost Target CPC PerClickInDC TgtAdSrvgCost Target Order PerOrderInDC Cost TgtAdSrvgCost Tgt Page Like PerPgLikeInDC Cost Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Converted Amount in Dis play Currency Not shown on the campaign UI - use TgtAdSrvg Cost Per1000Clicks instead. Target value for the ad serving cost per click converted to the display currency using the currency exchange rate of the campaign start date Converted Amount in Dis play Currency Target value for the ad serving cost per order converted to the display cur rency using the currency ex change rate of the campaign start date Converted Amount in Dis play Currency Target value for the ad serving cost per page like converted to the display currency using the currency exchange rate of the campaign start date 834 PUBLIC Integration Guide Integration APIs Global Field Name Label TgtAdSrvgCost Tgt Post PerPostEngmnt Engmnt Cost Type Target TgtAdSrvgCost Tgt Cost Video Target PerVideoView View Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for TgtAdSrvgCost ad serving cost PerPostEngmnt per post en and TgtAdSrvg gagement, SpendTran there is no sCurrency with meaningful ag CampaignPer gregation possi formanceType= ble, technically "TARGET" only summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Not shown on TgtAdSrvgCost the campaign PerVideoView UI - use and TgtAdSrvg TgtAdSrvg SpendTran Cost1000Vid sCurrency with eoViews in CampaignPer stead. Target formanceType= value for ad "TARGET" only serving cost per video view, there is no meaningful ag gregation possi ble, technically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Integration Guide Integration APIs PUBLIC 835 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TgtAdSrvgCost Tgt Post PostEngmn Engmnt Cost tInDC Converted Amount in Dis play Currency Target value for the ad serving cost per post engagement converted to the display cur rency using the currency ex change rate of the campaign start date TgtAdSrvgCost Tgt Cost Video VideoViewInDC View Converted Amount in Dis play Currency Not shown on the campaign UI - use TgtAdSrvg Cost1000Vid eoViews in stead. Target value for the ad serving cost per video view con verted to the display cur rency using the currency ex change rate of the campaign start date TgtAdSrvg Cost WbsteCnvr snInDC Target Web Conv Cost Converted Amount in Dis play Currency Target value for the ad serving cost per web site conversion converted to the display cur rency using the currency ex change rate of the campaign start date 836 PUBLIC Integration Guide Integration APIs Global Field Name Label TgtAdSrvgCost Target Web WebsiteCnvrsn Conv Cost Type Target TgtLeadConver Tgt Lead Conv. Target sionRateInPct Rate Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for TgtAdSrvgCost ad serving cost WebsiteCnvrsn per website and TgtAdSrvg conversion, SpendTran there is no sCurrency with meaningful ag CampaignPer gregation possi formanceType= ble, technically "TARGET" only summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Target value for TgtLeadConver lead conversion sionRateInPct rate in percent, with Campaign there is no Performance meaningful ag Type= "TAR gregation possi GET" only ble, technically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Integration Guide Integration APIs PUBLIC 837 Global Field Name Label TgtNumberOf Converted Leads Tgt Converted Leads Type Target TgtOpenedMes Target Opened Target sageRateInPct Mess. Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for TgtNumberOf number of con Converted verted leads, Leads with there is no CampaignPer meaningful ag formanceType= gregation possi "TARGET" only ble, technically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation Target value for TgtOpenedMes opened mes sageRateInPct sage rate in per with Campaign cent, there is no Performance meaningful ag Type= "TAR gregation possi GET" only ble, technically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation 838 PUBLIC Integration Guide Integration APIs Global Field Name TgtUni queClkThrR tInPct AdNetwork AdNetwor kName AdServing Cost1000Im prsnsInDC Label Target Unique CTR Ad Network Ad Network (Description) CPM (1000) Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target Target value for unique clickthrough rate in percent, there is no meaning ful aggregation possible, tech nically summed up when aggre gated, don't set this target in combination with further di mensions such as time or gen der to avoid meaningless aggregation TgtUni queClkThrR tInPct with CampaignPer formanceType= "TARGET" only Performance Dimension Ad network code of the campaign per formance measures, a mapping of ex ternal values to internal codes is maintained with the "Map Free Texts" app AdNetwork FreeText Old CSV: AD NETWORK FREETEXT AdNetwork AdNetwork FreeText Language De pendent De scription Ad network name of the campaign per formance measures Converted Amount in Dis play Currency Ad serving cost per 1000 im pressions in display cur rency calcu lated as (ad serving spend in display cur rency / number of impressions) *1000 Integration Guide Integration APIs PUBLIC 839 Global Field Name Label AdServing Cost1000Peo pleReached Cost per 1000 Reach AdServing Cost1000Vid ViewsInDC Cost 1000 Views AdServingCos tAppEngage mentInDC App Eng. Cost AdServingCost Cost per GRP GrossRating Point AdServingCost Cost per GRP GrossRatingP tInDC AdServing Cost Per1000Clicks CPC (1000) Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Calculated Ac tual Ad serving cost per 1000 peo ple reached cal culated as (ad serving cost / reach) *1000 Converted Amount in Dis play Currency Ad serving cost per 1000 video views in display currency calcu lated as (ad serving spend in display cur rency / number of video views) *1000 Converted Amount in Dis play Currency Ad serving cost per app en gagement in display cur rency calcu lated as ad serving spend in display cur rency / number of app engage ments Calculated Ac tual Ad serving cost per gross rating point calculated as ad serving cost / gross rat ing points Converted Amount in Dis play Currency Ad serving cost per gross rating point in display currency calcu lated as ad serving spend in display cur rency / gross rating points Calculated Ac tual Ad serving cost per 1000 clicks calculated as (ad serving cost / number of clicks) *1000 840 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface AdServing Cost Per1000Click sInDC Cost per 1000 Clicks Converted Amount in Dis play Currency Ad serving cost per click in dis play currency calculated as (ad serving spend in display currency / number of clicks) *1000 AdServing Cost Per1000Imprsn s CPM Calculated Ac tual Ad serving cost per 1000 im pressions cal culated as (ad serving cost / number of im pressions) *1000 AdServing Cost Per1000Video Views Cost per 1000 Views Calculated Ac tual Ad serving cost per 1000 video views calcu lated as (ad serving cost / number of video views) *1000 AdServingCost App Engage PerAppEngage ment Cost ment Calculated Ac tual Ad serving cost per app en gagement cal culated as ad serving cost / number of app engagements AdServingCost Cost per App PerAppInstall Install Calculated Ac tual Ad serving cost per app install calculated as ad serving cost / number of app installs AdServingCost Cost App Install Converted PerAppInstal Amount in Dis lInDC play Currency Ad serving cost per app install in display cur rency calcu lated as ad serving spend in display cur rency / number of app installs Integration Guide Integration APIs PUBLIC 841 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface AdServingCost Cost per Click PerClick Calculated Ac tual Ad serving cost per click calcu lated as ad serving cost / number of clicks AdServingCost Cost per Click PerClickInDC Converted Amount in Dis play Currency Ad serving cost per click in dis play currency calculated as ad serving spend in display cur rency / number of clicks AdServingCost Cost per Down Calculated Ac PerDownload load tual Ad serving cost per download calculated as ad serving cost / number of downloads AdServingCost PerDownloa dInDC Cost per Down load Converted Amount in Dis play Currency Ad serving cost per download in display cur rency calcu lated as ad serving spend in display cur rency / number of downloads AdServingCost Event Response Calculated Ac PerEventRes Cost tual ponse Ad serving cost per event re sponse calcu lated as ad serving cost / number of event re sponses AdServingCost Event Response Converted PerEventR Cost Amount in Dis spInDC play Currency Ad serving cost per event re sponse in dis play currency calculated as ad serving spend in display cur rency / number of event re sponses 842 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface AdServingCost Cost per Lead PerLead Calculated Ac tual Ad serving cost per lead calcu lated as ad serving cost / number of leads AdServingCost Cost per Lead PerLeadInDC Converted Amount in Dis play Currency Ad serving cost per lead in dis play currency calculated as ad serving spend in display cur rency / number of leads AdServingCost Cost per Offer PerMktgOffer Claim Claim Calculated Ac tual Ad serving cost per offer claim calculated as ad serving cost / number of offer claims AdServingCost Cost Offer PerOfferClai Claim mInDC Converted Amount in Dis play Currency Ad serving cost per offer claim in display cur rency calcu lated as ad serving spend in display cur rency / number of offer claims AdServingCost Cost per Order PerOrder Calculated Ac tual Ad serving cost per order calcu lated as ad serving cost / number of or ders AdServingCost Cost per Order PerOrderInDC Converted Amount in Dis play Currency Ad serving cost per order in dis play currency calculated as ad serving spend in display cur rency / number of orders Integration Guide Integration APIs PUBLIC 843 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface AdServingCost Cost per Page PerPageLike Like Calculated Ac tual Ad serving cost per page like calculated as ad serving cost / number of page likes AdServingCost Cost Page Like PerPageLi keInDC Converted Amount in Dis play Currency Ad serving cost per page like in display cur rency calcu lated as ad serving spend in display cur rency / number of page likes AdServingCost Post Engage PerPostEngage ment Cost ment Calculated Ac tual Ad serving cost per post en gagement cal culated as ad serving cost / number of post engagements AdServingCost Post Eng. Cost PerPostEngmn tInDC Converted Amount in Dis play Currency Ad serving cost per post en gagement in display cur rency calcu lated as ad serving spend in display cur rency / number of post engage ments AdServingCost Registration PerRegistration Cost Calculated Ac tual Ad serving cost per registration calculated as ad serving cost / number of reg istrations AdServingCost Cost per Video PerVideoView View Calculated Ac tual Ad serving cost per video view calculated as ad serving cost / number of video views 844 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface AdServingCost Cost Video View Converted PerVideoVie Amount in Dis wInDC play Currency Ad serving cost per video view in display cur rency calcu lated as ad serving spend in display cur rency / number of video views AdServingCost Web Conver PerWebsi sion Cost teCnvrsn Calculated Ac tual Ad serving cost per website conversion cal culated as ad serving cost / number of web site conver sions AdServingCos tRegistratio nInDC Registration Cost Converted Amount in Dis play Currency Ad serving cost per registration in display cur rency calcu lated as ad serving spend in display cur rency / number of registrations AdServingCost Web Conv. Cost Converted WebsiteCnvr Amount in Dis snInDC play Currency Ad serving cost per website conversion in display cur rency calcu lated as ad serving spend in display cur rency / number of website con versions Integration Guide Integration APIs PUBLIC 845 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface AdServing Ad Serving SpendAmount Spend Persistent Ac tual Amount spend for ad serving, summed up when aggre gated AdServing SpendAmount and AdServing SpendTran sCurrency with CampaignPer formanceType= "ACTUAL" only SpendAmount and SpendCur rency AdServing SpendAmount and AdServing SpendAmtCr cyISOCode Old CSV: SPEND_AMOU NT and SPEND_CUR RENCY AdServing SpendAmoun tInDC AdSrvg Cost1000Peo pleReachInDC Ad Serving Spend Cost per 1000 Reach Converted Amount in Dis play Currency Ad serving spend amount converted to the display cur rency using the currency ex change rate of the campaign start date Converted Amount in Dis play Currency Ad serving cost per 1000 peo ple reached in display cur rency calcu lated as (ad serving spend in display cur rency / reach) *1000 Advertiser Advertiser ID External Cam Advertiser ID of paign Reference the external campaign, the advertiser ID is part of the se mantical key of the external campaign, not supported for campaign tar gets Advertiser (with CampaignPer formanceType= "ACTUAL" only) Old CSV: AD VERTISER Advertiser 846 PUBLIC Integration Guide Integration APIs Global Field Name Advertiser Name Label Advertiser Name ExternalCam paignSystem Type Ext. Cpg. Sys tem ID AgeRange Age Range AverageFre quency Average Fre quency BounceRateIn Bounce Rate Percent Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface External Cam paign Reference Advertiser name of the ex ternal cam paign, not sup ported for cam paign targets Advertiser Name (with CampaignPer formanceType= "ACTUAL" only) Old CSV: AD VERTISER NAME Advertiser Name External Cam ID of the exter ExternalCam paign Reference nal campaign paignSystem system. This ID Type (with is defined in the CampaignPer communication formanceType= arrangement "ACTUAL" only) required for the Steps on External Platform action. For more infor mation, see Steps on Exter nal Platform. ExternalCam paignSystem Type Performance Dimension The age range the campaign performance measures refer to AgeRangeLo werLimit and AgeRangeUp perLimit AgeRangeLow and AgeRange High Old CSV: AGE_RANGE_L OW and AGE_RANGE_H IGH AgeRangeLo werLimit and AgeRangeUp perLimit Calculated Ac tual Average fre quency of im pressions cal culated as num ber of impres sions / reach Calculated Ac tual Bounce rate in percent calcu lated as ((hard + soft boun ces)/number of sent messages) *100% Integration Guide Integration APIs PUBLIC 847 Global Field Name Label CampaignAuto Node ID mationActio nUUID Type Performance Dimension CampaignCate Campaign Cat Campaign Di gory egory mension CampaignCate goryName Campaign Cat egory (Descrip tion) Language De pendent De scription CampaignCon Content Link tentLinkName Name Performance Dimension CampaignCon Content Name Performance tentName Dimension CampaignEnd Campaign End Campaign Di Date Date mension CampaignID Campaign ID Campaign Di mension CampaignLife Camp. Life Cy Campaign Di cycleStatus cle St. mension CampaignLife cycleStatus Name Camp. Life Cy Language De cle St. (Descrip pendent De tion) scription Campaign Name Campaign Name Campaign Di mension Campaign Owner Campaign Owner Campaign Di mension CampaignOw nerName Campaign Owner (De scription) Campaign Di mension Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface UUID of cam paign automa tion action. Will only be used for automation tab, not for perform ance tab Category code CampaignCate of the campaign gory CampaignCate goryID Category name of the campaign Name of the link in the cam paign content the campaign performance measures refer to CampaignCon tentLinkName Old CSV: CAM PAIGNCON TENTLIN KNAME CampaignCon tentLinkName CampaignCon tentLinkName Name of the campaign con tent the cam paign perform ance measures refer to CampaignCon tentName Old CSV: EXT_CON TENT_TITLE CampaignCon tentName CampaignCon tentName End date of the campaign ID of the SAP Marketing Cloud cam paign. CampaignID Old CSV: CAM PAIGN_ID Life cycle status code of the campaign Life cycle status name of the campaign Name of the campaign ID of the cam paign owner Name of the campaign owner CampaignID 848 PUBLIC Integration Guide Integration APIs Global Field Name Label CampaignPro Process Type cessType Type Campaign Di mension CampaignPro Process Type cessTypeName (Description) Campaign Reach Reach Language De pendent De scription Persistent Ac tual Campaign Reach in Per ReachInPercent cent Persistent Ac tual CampaignStart Campaign Start Campaign Di Date Date mension Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Process type code of the campaign Process type name of the campaign Reach, sum med up when aggregated, this is a people centric meas ure - be careful to combine it with non-per son related di mensions such as time when importing data as this leads to wrong aggre gated values, a combination with people re lated dimen sions such as gender is fine Campaign Reach with CampaignPer formanceType= "ACTUAL" UniqueImpres sions Old CSV: UNIQUE_IM PRESSIONS Campaign Reach Reach in per cent, summed up when aggre gated, this is a people centric measure - be careful to com bine it with nonperson related dimensions such as time when importing data as this leads to wrong aggregated val ues, a combina tion with people related dimen sions such as gender is fine Campaign ReachInPercent with Campaign Performance Type= "AC TUAL" Old CSV: CAM PAIGNREACH INPERCENT UniqueImpres sionsInPercent Campaign ReachInPercent Start date of the campaign Integration Guide Integration APIs PUBLIC 849 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface CampaignSuc cessImportMe thod Import Method Other The code of the method the campaign per formance data was imported with, filled auto matically by the system if per formance data is retrieved ClickThrough CTR RateInPercent Calculated Ac tual Click-through rate in percent calculated as (number of clicks / (im pressions + sent mes sages)) * 100%, depending on the campaign type typically either impres sions or sent messages are given ClickToOpenRa Click-To-Open teInPercent Rate Calculated Ac tual Click-to-open rate in percent calculated as (number of clicks / number of opened mes sages) *100% CmpgnPerfAltv Drill Down DrillDown Other Alternative drill down of the campaign per formance data used to sepa rate independ ent data sets that must not be aggregated together, only used for Baidu campaigns 850 PUBLIC Integration Guide Integration APIs Global Field Name Label CmpgnPerfor Time Unit manceTimeUnit Type Other CmpgnPerfTi meUnitName Time Unit (De scription) Language De pendent De scription CmpgnSucces sImportMe thodName Import Method (Description) Language De pendent De scription Communica tionMedium Communication Performance Medium Dimension Communica tionMedium Name Communication Language De Medium (De pendent De scription) scription Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface The time unit code the cam paign perform ance data was imported with, filled automati cally by the sys tem if perform ance data is re trieved depend ing on the gran ularity of the in coming data being daily, weekly or monthly The time unit name the cam paign perform ance data was imported with The name of the method the campaign per formance data was imported with Communication Communica medium code tionMedium of the campaign performance Old CSV: measures, the COMM_ME communication DIUM medium used to deliver the ad, possible val ues can be looked up and maintained with the Manage Your Solution app Communica tionMedium Communica tionMedium Communication medium name of the campaign performance measures Integration Guide Integration APIs PUBLIC 851 Global Field Name CountryCode CountryName DeviceType DeviceType Name ExternalCam paignAction Name ExternalCam paignID Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Country/ Region Performance Dimension Country/region code of the campaign per formance measures, a mapping of ex ternal values to internal codes is maintained with the "Map Free Texts" app CountryFree Text Old CSV: COUNTRY_FT Country CountryFree Text Country/ Region (De scription) Language De pendent De scription Country/region name of the campaign per formance measures Device Type Performance Dimension Device type code of the campaign per formance measures, a mapping of ex ternal values to internal codes is maintained with the "Map Free Texts" app DeviceFreeText Old CSV: DEVI CEFREETEXT DeviceType DeviceFreeText Device Type (Description) Language De pendent De scription Device type name of the campaign per formance measures Ext. Cpg. Action External Cam Name of exter paign Reference nal campaign action used in multichannel campaigns. Ext. Campaign ID External Cam paign Reference ID of a cam paign executed on an external platform as signed to the SAP Marketing Cloud cam paign, not sup ported for cam paign targets ExternalCam paignID (with CampaignPer formanceType= "ACTUAL" only) Old CSV: EXT_CAM PAIGN_ID ServerCam paignId ExternalCam paignID 852 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface ExternalCam paignName Ext. Campaign Name External Cam paign Reference Name of the ex ternal cam paign, not sup ported for cam paign targets ExternalCam paignName (with Cam paignPerfor manceType= "ACTUAL" only) Old CSV: EXT_CAM PAIGN_NAME ExternalCam paignName ExternalCam paignURL External CmpgnMana gingParty Ext. Campaign URL External Cam Link to the paign Reference campaign on the external platform Managing Party External Cam paign Reference Party ID of the party managing the external campaign, the party ID is part of the semanti cal key of the external cam paign, not sup ported for cam paign targets External CmpgnMana gingParty (with CampaignPer formanceType= "ACTUAL" only) Old CSV: EX TER NALCMPGN MANAGING PARTY External CmpgnMana gingParty External CmpgnMana gingPartyName Managing Party Name External Cam paign Reference Party name of the party man aging the exter nal campaign, not supported for campaign targets External CmpgnMana gingPartyName (with Cam paignPerfor manceType= "ACTUAL" only) Old CSV: EX TER NALCMPGN MANAGING PARTYNAME External CmpgnMana gingPartyName Integration Guide Integration APIs PUBLIC 853 Global Field Name GenderCode Label Gender GenderCode Name Gender (De scription) GrossRating PointBase GRP Base GrossRating Points Gross Rating Points Type Performance Dimension Language De pendent De scription Performance Dimension Persistent Ac tual Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Gender code of the campaign performance measures, a mapping of ex ternal values to internal codes is maintained with the "Map Free Texts" app GenderFreeText Gender Old CSV: GEN DER_FT GenderFreeText Gender code name of the campaign per formance measures Base the gross rating points measure refers to, typically contains a cus tom string de scribing the au dience the gross rating points are re lated to, not supported for campaign tar gets GrossRating PointBase (with CampaignPer formanceType= "ACTUAL" only) Old CSV: GROSSRA TINGPOINT BASE GrossRating PointBase GrossRating PointBase Gross rating points, sum med up when aggregated, be aware that an aggregation of gross rating points with a different gross rating point base doesn't make sense but technically is not prevented GrossRating Points with CampaignPer formanceType= "ACTUAL" Old CSV: GROSSRA TINGPOINTS GrossRating Points GrossRating Points 854 PUBLIC Integration Guide Integration APIs Global Field Name Label Type InteractionRea Interaction Rea Performance son son Dimension InteractionRea sonName Interaction Rea Language De son (Descrip pendent De tion) scription Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface The interaction InteractionRea reason code the son (with Cam campaign per paignPerfor formance manceType= measures refer "ACTUAL" only) to, mainly pro viding failure Old CSV: IN reasons for SAP TERACTION Marketing REASON Cloud internally executed cam paigns such as a failed market ing permission check, possible values can be looked up and maintained with the Manage Your Solution app, not sup ported for cam paign targets InteractionRea son InteractionRea son The interaction reason name the campaign performance measures refer to Integration Guide Integration APIs PUBLIC 855 Global Field Name Label Type InteractionSta Interaction Sta Performance tus tus Dimension InteractionSta tusName Interaction Sta Language De tus (Descrip pendent De tion) scription Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Status code of the interaction the campaign performance measures refer to, mainly used for measures related to busi ness docu ments such as leads or sales orders to pro vide a status of the business document, pos sible values are: InteractionSta tus (with Cam paignPerfor manceType= "ACTUAL" only) Old CSV: IN TERACTION STATUS InteractionSta tus InteractionSta tus 01 In Proc ess 02 Re leased 03 Com pleted 04 Cancel led 05 Con verted 06 Suc cessful 07 Unsuc cessful 00 New Not supported for campaign targets Status name of the interaction the campaign performance measures refer to 856 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface InteractionType Interaction Type Performance Dimension Type code of the interaction the campaign performance measures refer to, mainly used together with interaction rea sons, possible values can be looked up and maintained with the Manage Your Solution app, not sup ported for cam paign targets InteractionType (with Cam paignPerfor manceType= "ACTUAL" only) Old CSV: IN TERACTION TYPE InteractionType InteractionType InteractionTy peName Interaction Type (Descrip tion) Language De pendent De scription Type name of the interaction the campaign performance measures refer to LeadConver sionRateInPer cent Lead Conver sion Rate Calculated Ac tual Lead conver sion rate in per cent calculated as (number of converted leads / number of leads) *100% LeadNurture Lead Nurture ID Campaign Di mension Technical ID of a lead nurture using a cam paign CSV upload ig nores field LeadNurture Name Lead Nurture Name Campaign Di mension Name of a lead nurture using a campaign CSV upload ig nores field LeadNurtureS Lead Nurture tageUUID Stage UUID Campaign Di mension Guid of lead nurture stage CSV upload ig nores field LeadNurtureS Lead Nurture tageName Stage Name Campaign Di mension Name of a lead nurture stage using a cam paign CSV upload ig nores field MarketingArea Marketing Area Campaign Di mension Marketing area ID of the cam paign Integration Guide Integration APIs PUBLIC 857 Global Field Name Label Type MarketingArea Name Marketing Area (Description) Language De pendent De scription MarketingPlan Marketing Plan Campaign Di ID mension MarketingPlan Mktg Plan Name Name Campaign Di mension MarketingProg Program ramID Campaign Di mension MarketingProg Program Name Campaign Di ramName mension MediaType Media Type ID Performance Dimension MediaType Name Media Type ID (Description) Language De pendent De scription Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Marketing area name of the campaign ID of the mar keting plan as sociated with the campaign Name of the marketing plan associated with the campaign ID of the mar keting program associated with the campaign Name of the marketing pro gram associ ated with the campaign Media type code of the campaign per formance measures, the media type is derived from the communi cation medium, if no communi cation medium is given the me dia type is taken from the campaign, pos sible values can be looked up and maintained with the Man age Your Solu tion app Media type name of the campaign per formance measures 858 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface MultiTouchAt Multi Touch Ord Converted tributedOrdAm Amt Amount in Dis tInDC play Currency Multi touch at tributed order amount con verted to the display cur rency using the currency ex change rate of the campaign start date MultiTouchAt tributedOrder Amt Multi Touch Ord Persistent Ac Amt tual Order amount MultiTouchAt attributed to tributedOrder the campaign Amt and Order using multi TransactionCur touch attribu rency with tion, summed CampaignPer up when aggre formanceType= gated, typically "ACTUAL" used with SAP Hybris Cus tomer Attribu Old CSV: MUL TITOUCHAT tion integration, TRIBUTEDOR summed up DERAMT and when aggre gated ORDERTRAN SACTIONCUR RENCY MultiTouchAt tributedOrder Amt and Order AmountCurren cyISOCode NmbrOfOpen ChannelInter actions Open Channel Interac Persistent Ac tual Number of open channel interactions, summed up when aggre gated, used for campaigns exe cuted in SAP Marketing Cloud that in clude custom actions imple mented using the open chan nel NmbrOfOpen ChannelInter actions with CampaignPer formanceType= "ACTUAL" Old CSV: NMBROFOPEN CHANNELIN TERACTIONS NmbrOfOpen ChannelInter actions Integration Guide Integration APIs PUBLIC 859 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface NrOfMultiTch Multi Touch AttrCnvrsns Cnvrsns NumberOfAp App Engage pEngagements ments Persistent Ac tual Persistent Ac tual Number of con versions attrib uted to the campaign using multi touch at tribution, typi cally used with SAP Hybris Customer Attri bution integra tion, summed up when aggre gated NrOfMultiTch AttrCnvrsns with Campaign Performance Type= "AC TUAL" Old CSV: NROF MULTI TCHATTRCNVR SNS Number of app engagements as a result of the campaign, summed up when aggre gated NumberOfAp pEngagements with Campaign Performance Type= "AC TUAL" AppEngage ments Old CSV: APP_ENGAGE MENTS NrOfMultiTch AttrCnvrsns NumberOfAp pEngagements NumberOfAp App Installs pInstalls Persistent Ac tual Number of app installs attrib uted to the campaign, sum med up when aggregated NumberOfAp pInstalls with CampaignPer formanceType= "ACTUAL" Old CSV: APP_INSTALLS AppInstalls NumberOfAp pInstalls NumberOfAp pointments Appointments Persistent Ac tual Number of ap pointments scheduled as a result of the campaign, sum med up when aggregated NumberOfAp pointments with Campaign Performance Type= "AC TUAL" Old CSV: NUM BEROFAP POINTMENTS Appointments NumberOfAp pointments NumberOf Clicks Clicks Persistent Ac tual Number of clicks, summed up when aggre gated NumberOf Clicks with CampaignPer formanceType= "ACTUAL" Clicks Old CSV: CLICKS NumberOf Clicks 860 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface NumberOfCon Converted vertedLeads Leads Calculated Ac tual NumberOfDeli Delivered Mes Persistent Ac veredMessages sages tual NumberOf Downloads Downloads Persistent Ac tual Number of con verted leads created as a re sult of the cam paign Number of messages suc cessfully deliv ered by the campaign, for campaigns exe cuted in SAP Marketing Cloud delivered messages = sent messages - hard and soft bounces - re jected mes sages, summed up when aggre gated NumberOfDeli veredMessages with Campaign Performance Type= "AC TUAL" DeliveredMes sages Old CSV: DELIV ERED_MES SAGES Number of downloads at tributed to the campaign, sum med up when aggregated NumberOf Downloads with CampaignPer formanceType= "ACTUAL" Old CSV: NUM BEROFDOWN LOADS Downloads NumberOfDeli veredMessages NumberOf Downloads NumberOfE Email Com mailComplaints plaints Persistent Ac tual Number of email com plaints, the number of times a mail sent by the campaign was marked as spam, summed up when aggre gated NumberOfE mailComplaints with Campaign Performance Type= "AC TUAL" Old CSV: NUM BEROFEMAIL COMPLAINTS EmailCom plaints NumberOfE mailComplaints Integration Guide Integration APIs PUBLIC 861 Global Field Name Label NumberOfE Event Re ventResponses sponses Type Persistent Ac tual NumberOfExe cutedInterac tions Executed Inter act. Persistent Ac tual NumberOfFaile Failed Interac Persistent Ac dInteractions tions tual Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Number of event re sponses, typi cally used with Facebook cam paigns, sum med up when aggregated NumberOfE ventResponses with Campaign Performance Type= "AC TUAL" EventRes ponses Old CSV: EVENT_RE SPONSE S NumberOfE ventResponses Number of in teractions exe cuted by the SAP Marketing Cloud cam paign, summed up when aggre gated NumberOfExe cutedInterac tions (with CampaignPer formanceType= "ACTUAL" only) Old CSV: NUM BEROFEXECU TEDINTERAC TIONS ExecutedInter actions NumberOfExe cutedInterac tions Number of NumberOfFaile FailedInterac failed interac dInteractions tions tions, for cam (with Cam paigns exe paignPerfor cuted in SAP manceType= Marketing "ACTUAL" only) Cloud this is the number of in Old CSV: NUM teractions that BEROFFAILE have been trig DINTERAC gered but could TIONS not be executed for various rea sons such as missing mar keting permis sions, summed up when aggre gated NumberOfFaile dInteractions 862 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface NumberOf HardBounces Hard Bounces Persistent Ac tual Number of hard bounces for sent messages, summed up when aggre gated NumberOf HardBounces with Campaign Performance Type= "AC TUAL" HardBounces Old CSV: NUM BEROFHARD BOUNCES NumberOf HardBounces NumberOfIm Impressions pressions Persistent Ac tual Number of im pressions, sum med up when aggregated NumberOfIm pressions with CampaignPer formanceType= "ACTUAL" Impressions Old CSV: IM PRESSIONS NumberOfIm pressions NumberO fLeads No. of Leads Persistent Ac tual Number of leads created as a result of the campaign, summed up when aggre gated NumberO fLeads with CampaignPer formanceType= "ACTUAL" Leads Old CSV: NUM BEROFLEADS NumberO fLeads NumberOfMar ketingOffer Views Offer Views Persistent Ac tual Number of offer views as a re sult of the cam paign, summed up when aggre gated NumberOfMar ketingOffer Views with CampaignPer formanceType= "ACTUAL" OfferViews Old CSV: NUM BEROFMARKE TINGOFFER VIEWS NumberOfMar ketingOffer Views NumberOfMkt Offer Claims gOfferClaims Persistent Ac tual Number of offer claims as a re sult of the cam paign, summed up when aggre gated NumberOfOf ferClaims with CampaignPer formanceType= "ACTUAL" Old CSV: OF FER_CLAIMS OfferClaims NumberOfOf ferClaims Integration Guide Integration APIs PUBLIC 863 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface NumberOfOpe Opened Mes nedMessages sages Persistent Ac tual Number of opened mes sages, summed up when aggre gated NumberOfOpe nedMessages with Campaign Performance Type= "AC TUAL" OpenedMes sages Old CSV: NUM BEROFOPE NEDMES SAGES NumberOfOpe nedMessages NumberOfOp No. of Opportu Persistent Ac portunities nities tual Number of op portunities cre ated as a result of the cam paign, summed up when aggre gated NumberOfOp portunities with CampaignPer formanceType= "ACTUAL" Old CSV: NUM BEROFOPPOR TUNITIES Opportunities NumberOfOp portunities NumberOfOr ders Number of Or Persistent Ac ders tual Number of or ders attributed to the cam paign, summed up when aggre gated NumberOfOr ders with Cam paignPerfor manceType= "ACTUAL" Orders Old CSV: NUM BEROFORDERS NumberOfOr ders NumberOf PageLikes Page Likes NumberOfPho Phone Calls neCalls Persistent Ac tual Persistent Ac tual Number of page likes as a result of the cam paign, typically used for Face book cam paigns, sum med up when aggregated NumberOf PageLikes with CampaignPer formanceType= "ACTUAL" Old CSV: PAGE_LIKES PageLikes Number of phone calls trig gered as a re sult of the cam paign, summed up when aggre gated NumberOfPho neCalls with CampaignPer formanceType= "ACTUAL" Old CSV: NUM BEROFPHONE CALLS PhoneCalls NumberOf PageLikes NumberOfPho neCalls 864 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface NumberOfPos Page Post Eng. Persistent Ac tEngagements tual Number of en gagements with a page post, typically used with Facebook campaigns, summed up when aggre gated NumberOfPos tEngagements with Campaign Performance Type= "AC TUAL" Old CSV: POST_EN GAGEMENTS PostEngage ments NumberOfPos tEngagements NumberOfRe Registrations gistrations Persistent Ac tual Number of reg istrations at tributed to the campaign, sum med up when aggregated NumberOfRe gistrations with CampaignPer formanceType= "ACTUAL" Old CSV: NUM BEROFREGIS TRATIONS Registrations NumberOfRe gistrations NumberOfRe Rejected Mes Persistent Ac jectedMessages sages tual Number of re NumberOfRe RejectedMes jected mes jectedMessages sages sages, for cam with Campaign paigns exe Performance cuted in SAP Type= "AC Marketing TUAL" Cloud this is the number of mes Old CSV: RE sages that has JECTED_MES been sent suc SAGES cessfully to an external plat form but that have been re jected for any reason by this platform with out being counted as hard or soft bounces, summed up when aggre gated NumberOfRe jectedMessages Integration Guide Integration APIs PUBLIC 865 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface NumberOfSent Sent Messages Persistent Ac Messages tual NumberOfSoft Soft Bounces Bounces Persistent Ac tual The number of messages sent by the cam paign, the type of the message such as email or SMS typi cally is given by the communi cation medium, summed up when aggre gated NumberOfSent SentMessages Messages with CampaignPer formanceType= "ACTUAL" Old CSV: SENT_MES SAGES NumberOfSent Messages Number of soft bounces for sent messages, summed up when aggre gated NumberOfSoft Bounces with CampaignPer formanceType= "ACTUAL" Old CSV: NUM BEROFSOFT BOUNCES SoftBounces NumberOfSoft Bounces NumberOf Tasks Tasks Persistent Ac tual Number of tasks triggered as a result of the campaign, typically tasks are created in a connected CRM system, sum med up when aggregated NumberOf Tasks with CampaignPer formanceType= "ACTUAL" Old CSV: NUM BEROFTASKS Tasks NmbrOfTrigger Triggered Inter Calculated Ac edInteractions act. tual Number of trig gered interac tions calculated as executed in teractions + failed interac tions NumberOf Tasks 866 PUBLIC Integration Guide Integration APIs Global Field Name Label NumberOfUni Unique Clicks queClicks NumberOfVi deoViews Video Views Type Persistent Ac tual Persistent Ac tual Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Number of unique clicks, the number of different people that clicked an ad. For cam paigns exe cuted in SAP Marketing Cloud the num ber of unique clicks is per content (and not per link in the content or per campaign), summed up when aggre gated, this is a people centric measure - be careful to com bine it with nonperson related dimensions such as time when importing data as this leads to wrong aggregated val ues, a combina tion with people related dimen sions such as gender is fine NumberOfUni queClicks with CampaignPer formanceType= "ACTUAL" Old CSV: UNIQUE_CLICK S UniqueClicks NumberOfUni queClicks Number of video views, summed up when aggre gated NumberOfVi deoViews with CampaignPer formanceType= "ACTUAL" VideoViews NumberOfVi deoViews Old CSV: VIDEO_VIEWS Integration Guide Integration APIs PUBLIC 867 Global Field Name Label NumberOfWeb Website Con siteConversions versions OpenedMessa geRateInPer cent Opened Mes sages in % OpportunityA Opportunity mount Amount Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Persistent Ac tual Number of web NumberOfWeb WebsiteConver NumberOfWeb site conver siteConversions sions siteConversions sions attributed with Campaign to the cam Performance paign, typically Type= "AC used for Face TUAL" book cam paigns, for other scenarios there are dedi Old CSV: WEB SITE_CONVER SIONS cated measures for the different types of conver sions such as number of or ders or number of registrations, summed up when aggre gated Calculated Ac tual Rate of opened messages in percent calcu lated as (num ber of opened messages / number of de livered mes sages) *100% Persistent Ac tual Opportunity amount attrib uted to the campaign, sum med up when aggregated OpportunityA mount and Op portunityTran sactionCur rency with CampaignPer formanceType= "ACTUAL" OpportunityA mount / Oppor tunityAmount Currency OpportunityA mount and Op portunityA mountCrcyISO Code Old CSV: OP PORTUNITYA MOUNT and OPPORTUNITY TRANSAC TIONCUR RENCY 868 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface OpportunityA mountInDC OrderAmount Opportunity Amount Order Amount Converted Amount in Dis play Currency Opportunity amount con verted to the display cur rency using the currency ex change rate of the campaign start date Persistent Ac tual Order amount attributed to the campaign, summed up when aggre gated OrderAmount and OrderTran sactionCur rency with CampaignPer formanceType= "ACTUAL" OrderAmount / OrderAmount Currency OrderAmount and OrderA mountCurren cyISOCode Old CSV: OR DERAMOUNT and ORDER TRANSAC TIONCUR RENCY OrderAmoun tInDC Order Amount ProjectedNum berOfConver sions Proj. Conver sions Converted Amount in Dis play Currency Order amount converted to the display cur rency using the currency ex change rate of the campaign start date Persistent Ac tual Projected num ProjectedNum ber of conver berOfConver sions that could sions (with have been ach CampaignPer ieved with an formanceType= optimized cam "ACTUAL" only) paign, typically used with SAP Hybris Cus Old CSV: PROJ ECTEDNUM tomer Attribu BEROFCON tion integration, VERSIONS summed up when aggre gated ProjectedNum berOfConver sions Integration Guide Integration APIs PUBLIC 869 Global Field Name Label ProjectedOrder Proj.Order Amount Amount ProjectedOrder Proj. Order AmountInDC Amount Region Region RegionName Region (De scription) SuccessData Date Date Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Persistent Ac tual Projected order ProjectedOrder amount that Amount and Or could have derTransaction been achieved Currency (with with an opti CampaignPer mized cam formanceType= paign, typically "ACTUAL" only) used with SAP Hybris Cus tomer Attribu Old CSV: PROJ ECTEDORDER tion integration, AMOUNT and summed up ORDERTRAN when aggre gated SACTIONCUR RENCY ProjectedOrder Amount and Or derAmountCur rencyISOCode Converted Amount in Dis play Currency Projected order amount con verted to the display cur rency using the currency ex change rate of the campaign start date Performance Dimension Region code of the campaign performance measures, a mapping of ex ternal values to internal codes is maintained with the "Map Free Texts" app RegionFreeText Old CSV: RE GION_FT Region Language De pendent De scription Region name of the campaign performance measures Performance Dimension Date the cam paign perform ance measures refer to CampaignPer formanceDate Old CSV: RE PORT ING_DATE Date RegionFreeText SuccessData Date 870 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface SuccessData Time Last LastChangeDa Changed teTime Other SuccessDataR eplicationSta tus Reporting Sta tus Other SuccessData Timezone DateTimeZone SuggestedAd ServingSpen dAmount Suggested Spend Performance Dimension Persistent Ac tual Date and time when the per formance data record was last updated, filled automatically by the system if performance data is retrieved Status code of the campaign success data replication, filled automati cally by the sys tem if perform ance data is re trieved Time zone of success data date CampaignPer formanceDate Zone TimeZone Suggested ad SuggestedAd serving spend ServingSpen amount for an dAmount and optimized cam AdServing paign, typically SpendTran used with SAP sCurrency with Hybris Cus CampaignPer tomer Attribu formanceType= tion integration, "ACTUAL" only summed up when aggre gated Old CSV: SUG GESTEDAD SERVINGSPEN DAMOUNT and SPEND_CUR RENCY SuccessData DateTimeZone SuggestedAd ServingSpen dAmount SuggestedAd ServingSpen dAmtInDC Suggested Spend Converted Amount in Dis play Currency Suggested ad serving spend amount con verted to the display cur rency using the currency ex change rate of the campaign start date Integration Guide Integration APIs PUBLIC 871 Global Field Name TargetCam paignReach Label Target Reach Type Target TargetGrossRa Target GRPs tingPoints Target Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for the reach, sum med up when aggregated, this is a people centric meas ure - be careful to combine it with non-per son related di mensions such as time when importing data as this leads to wrong aggre gated values, a combination with people re lated dimen sions such as gender is fine Campaign Reach with CampaignPer formanceType= "TARGET" Old CSV: UNIQUE_IM PRESSIONS Target value for the gross rating points, sum med up when aggregated, be aware that an aggregation of gross rating points with a different gross rating point base doesn't make sense but technically is not prevented GrossRating Points with CampaignPer formanceType= "TARGET" Old CSV: GROSSRA TINGPOINTS 872 PUBLIC Integration Guide Integration APIs Global Field Name Label Type TargetMultiTch Target MTA Ord Target AttrOrderAmt Amt TargetNmbrO fAppEngage ments Tgt App En gagements Target TargetNumber Target App In Target OfAppInstalls stalls TargetNumber OfAppoint ments Target Appoint ments Target Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for MultiTouchAt the multi touch tributedOrder attributed order Amt and Order amount, sum TransactionCur med up when rency with aggregated CampaignPer formanceType= "TARGET" Old CSV: MUL TITOUCHAT TRIBUTEDOR DERAMT and ORDERTRAN SACTIONCUR RENCY Target value for the number of app engage ments, sum med up when aggregated NumberOfAp pEngagements with Campaign Performance Type= "TAR GET" Old CSV: APP_ENGAGE MENTS Target value for the number of app installs, summed up when aggre gated NumberOfAp pInstalls with CampaignPer formanceType= "TARGET" Old CSV: APP_INSTALLS Target value for the number of appointments, summed up when aggre gated NumberOfAp pointments with Campaign Performance Type= "TAR GET" Old CSV: NUM BEROFAP POINTMENTS Integration Guide Integration APIs PUBLIC 873 Global Field Name Label TargetNumber Target Clicks OfClicks Type Target TargetNumber Target Down OfDownloads loads Target TargetNumber Target Hard OfHardBounces Bounces Target TargetNumber Target Impres Target OfImpressions sions TargetNumber Target No. of OfLeads Leads Target Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for the number of clicks, summed up when aggre gated NumberOf Clicks with CampaignPer formanceType= "TARGET" Old CSV: CLICKS Target value for the number of downloads, summed up when aggre gated NumberOf Downloads with CampaignPer formanceType= "TARGET" Old CSV: NUM BEROFDOWN LOADS Target value for NumberOf the number of HardBounces hard bounces, with Campaign in contrast to Performance most other tar Type= "TAR gets less is con GET" sidered to be better, summed Old CSV: NUM up when aggre BEROFHARD gated BOUNCES Target value for the number of impressions, summed up when aggre gated NumberOfIm pressions with CampaignPer formanceType= "TARGET" Old CSV: IM PRESSIONS Target value for the number of leads, summed up when aggre gated NumberO fLeads with CampaignPer formanceType= "TARGET" Old CSV: NUMBER OFLEADS 874 PUBLIC Integration Guide Integration APIs Global Field Name Label Type TargetNumber OfOpportuni ties Target Opportu Target nities TargetNumber Tgt Number of Target OfOrders Orders TargetNumber Target Page OfPageLikes Likes Target TargetNumber Target Phone OfPhoneCalls Calls Target TargetNumber Target Registra Target OfRegistrations tions Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for the number of opportunities, summed up when aggre gated NumberOfOp portunities with CampaignPer formanceType= "TARGET" Old CSV: NUM BEROFOPPOR TUNITIES Target value for the number of orders, sum med up when aggregated NumberOfOr ders with Cam paignPerfor manceType= "TARGET" Old CSV: NUM BEROFORDERS Target value for NumberOf the number of PageLikes with page likes, sum CampaignPer med up when formanceType= aggregated "TARGET" Old CSV: PAGE_LIKES Target value for the number of phone calls, summed up when aggre gated NumberOfPho neCalls with CampaignPer formanceType= "TARGET" Old CSV: NUM BEROFPHONE CALLS Target value for the number of registrations, summed up when aggre gated NumberOfRe gistrations with CampaignPer formanceType= "TARGET" Old CSV: NUM BEROFREGIS TRATIONS Integration Guide Integration APIs PUBLIC 875 Global Field Name Label TargetNumber OfSentMes sages Target Sent Messages Type Target TargetNumber Target Soft OfSoftBounces Bounces Target TargetNumber Target Tasks OfTasks Target TargetNumber Target Unique OfUniqueClicks Clicks Target Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for the number of sent messages, summed up when aggre gated NumberOfSent Messages with CampaignPer formanceType= "TARGET" Old CSV: SENT_MES SAGES Target value for NumberOfSoft the number of Bounces with soft bounces, in CampaignPer contrast to formanceType= most other tar "TARGET" gets less is con sidered to be Old CSV: NUM better, summed BEROFSOFT up when aggre BOUNCES gated Target value for the number of tasks, summed up when aggre gated NumberOf Tasks with CampaignPer formanceType= "TARGET" Old CSV: NUM BEROFTASKS Target value for NumberOfUni the number of queClicks with unique clicks, CampaignPer summed up formanceType= when aggre "TARGET" gated, this is a people centric measure - be careful to com Old CSV: UNIQUE_CLICK S bine it with non- person related dimensions such as time when importing data as this leads to wrong aggregated val ues, a combina tion with people related dimen sions such as gender is fine 876 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TargetNumber Target Video OfVideoViews Views Target Target value for the number of video views, summed up when aggre gated NumberOfVi deoViews with CampaignPer formanceType= "TARGET" Old CSV: VIDEO_VIEWS TargetOpportu Tgt Opportunity Target nityAmount Amt Target value for the opportunity amount, sum med up when aggregated OpportunityA mount and Op portunityTran sactionCur rency with CampaignPer formanceType= "TARGET" Old CSV: OP PORTUNITYA MOUNT and OPPORTUNITY TRANSAC TIONCUR RENCY TargetOpportu nityAmoun tInDC Tgt Opportunity Amt Converted Amount in Dis play Currency Target value for the opportunity amount con verted to the display cur rency using the currency ex change rate of the campaign start date TargetOrderA Target Order mount Amount Target Target value for the order amount, sum med up when aggregated OrderAmount and OrderTran sactionCur rency with CampaignPer formanceType= "TARGET" Old CSV: OR DERAMOUNT and ORDER TRANSAC TIONCUR RENCY Integration Guide Integration APIs PUBLIC 877 Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TargetOrderA Target Order mountInDC Amount Converted Amount in Dis play Currency Target value for the order amount con verted to the display cur rency using the currency ex change rate of the campaign start date TgtCampaign Tgt Reach in ReachInPercent Percent Target Target value for the reach in percent, sum med up when aggregated, this is a people centric meas ure - be careful to combine it with non-per son related di mensions such as time when importing data as this leads to wrong aggre gated values, a combination with people re lated dimen sions such as gender is fine Campaign ReachInPercent with Campaign Performance Type= "TAR GET" Old CSV: CAM PAIGNREACH INPERCENT TgtMultiTchAt trOrdAmtInDC Target MTA Ord Converted Amt Amount in Dis play Currency Target value for the multi touch attributed order amount con verted to the display cur rency using the currency ex change rate of the campaign start date 878 PUBLIC Integration Guide Integration APIs Global Field Name Label TgtNmbrOfDeli Tgt Delivered veredMessages Msgs Type Target TgtNmbrO fOpnChnlInter actions Tgt Open Chan Target nel Int TgtNmbrOf Target Conver WebsiteConver sions sions Target TgtNrOfMul tiTch AttrCnvrsns Tgt MTA Con versions Target Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for the number of delivered mes sages, summed up when aggre gated NumberOfDeli veredMessages with Campaign Performance Type= "TAR GET" Old CSV: DELIV ERED_MES SAGES Target value for the number of open channel interactions, summed up when aggre gated NmbrOfOpen ChannelInter actions with CampaignPer formanceType= "TARGET" Old CSV: NMBROFOPEN CHANNELIN TERACTIONS Target value for the number of website conver sions, summed up when aggre gated NumberOfWeb siteConversions with Campaign Performance Type= "TAR GET" Old CSV: WEB SITE_CONVER SIONS Target value for NrOfMultiTch the number of AttrCnvrsns multi touch at with Campaign tributed conver Performance sions, summed Type= "TAR up when aggre GET" gated Old CSV: NROF MULTI TCHATTRCNVR SNS Integration Guide Integration APIs PUBLIC 879 Global Field Name Label Type TgtNumberOfE Tgt Email Com Target mailComplaints plaints TgtNumberOfE Tgt Event Re ventResponses sponses Target TgtNumber OfMktgOffer Claims Target Offer Claims Target TgtNumber OfMktgOffer Views Target Offer Views Target Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Target value for the number of email com plaints, in con trast to most other targets less is consid ered to be bet ter, summed up when aggre gated NumberOfE mailComplaints with Campaign Performance Type= "TAR GET" Old CSV: NUM BEROFEMAIL COMPLAINTS Target value for the number of event re sponses, sum med up when aggregated NumberOfE ventResponses with Campaign Performance Type= "TAR GET" Old CSV: EVENT_RE SPONSES Target value for the number of offer claims, summed up when aggre gated NumberOfOf ferClaims with CampaignPer formanceType= "TARGET" Old CSV: OF FER_CLAIMS Target value for the number of offer views, summed up when aggre gated NumberOfMar ketingOffer Views with CampaignPer formanceType= "TARGET" Old CSV: NUM BEROFMARKE TINGOFFER VIEWS 880 PUBLIC Integration Guide Integration APIs Global Field Name Label Type Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface TgtNumberO fOpenedMes sages Tgt Opened Messages Target Target value for the number of opened mes sages, summed up when aggre gated NumberOfOpe nedMessages with Campaign Performance Type= "TAR GET" Old CSV: NUM BEROFOPE NEDMES SAGES TgtNumberOf PostEngage ments Tgt Page Post Eng. Target Target value for the number of page post en gagements, summed up when aggre gated NumberOfPos tEngagements with Campaign Performance Type= "TAR GET" Old CSV: POST_EN GAGEMENTS TgtNumberO fRejectedMes sages UniqueClick ThroughRa teInPct Target Rejected Target Msgs Unique CTR Calculated Ac tual Target value for the number of rejected mes sages, in con trast to most other targets less is consid ered to be bet ter, summed up when aggre gated NumberOfRe jectedMessages with Campaign Performance Type= "TAR GET" Old CSV: RE JECTED_MES SAGES Unique clickthrough rate in percent calcu lated as (num ber of unique clicks / (reach + sent mes sages)) * 100%, depending on the campaign type typically either reach or sent messages is given Integration Guide Integration APIs PUBLIC 881 Global Field Name Label VideoViewedA verageInPer cent Per. Video Viewed YearMonth Year Month YearQuarter Year Quarter YearWeek Year Week Type Persistent Ac tual Performance Dimension Performance Dimension Performance Dimension Description Column in CSV Upload Name in Exter nal Campaign OData Pull In terface Name in OData Push Interface Average per centage of video viewed, aggregated as average weighted by the number of video views VideoViewedA verageInPer cent with Cam paignPerfor manceType= "ACTUAL" Old CSV: VID EOVIEWEDA VERAGEINPER CENT VideoViewedA verageInPer cent VideoViewedA verageInPer cent Year and month the campaign performance measures refer to YearMonth Old CSV: YEAR MONTH YearMonth Year and quar ter the cam paign perform ance measures refers to Year and week the campaign performance measures refer to YearWeek YearWeek Old CSV: YEAR WEEK YearMonth YearWeek 5.5.7.2 Aggregated Success Data from Interactions Some interactions are used to update aggregated success for campaigns. Interactions Certain interactions are used to update the aggregated success data of campaigns. These interactions need to have a timestamp and a reference to a campaign. Therefore, the following interaction attributes must be correctly maintained: UTC Time Stamp in Long Form (TIMESTAMP) Campaign ID (INITIATIVE_ID) Note Aggregated success data can't be extended to include any additional measures and dimensions from interactions than those that are already used. 882 PUBLIC Integration Guide Integration APIs The interactions can have any communication medium besides Business Document (BUSINESS_DOCUMENT) and WeChat (WEC). To see a list of business documents used to update aggregated success data, see the Business Documents section below. Interactions Used to Update Aggregated Success Measure Global Field Names Delivered Messages NumberOfDeliveredMessages The number of delivered messages equals the number of successfully sent messages, minus the bounces. Interaction Types Outbound Email (EMAIL_OUTBOUND) Emails Classified as Complaint (Spam) (EMAIL_COMPLAINT) Outbound Text Message (SMS_OUT BOUND) Mobile Notification Sent (MOB_APP_NOTIF_SENT) Outbound Message from Digital Ac count (DIG_ACC_OUTBOUND) Hard Bounces NumberOfHardBounces Hard Bounce (EMAIL_BOUNCE_HARD) Hard Bounce (SMS_BOUNCE_HARD) Hard Bounce (BOUNCE_HARD) Soft Bounces NumberOfSoftBounces Soft Bounce (EMAIL_BOUNCE_SOFT) Soft Bounce (SMS_BOUNCE_SOFT) Email Complaints Opened Messages NumberOfEmailComplaints NumberOfOpenedMessages Emails Classified as Complaint (Spam) (EMAIL_COMPLAINT) Email Opened (EMAIL_OPENED) Mobile Notification Viewed (MOB_APP_NOTIF_VIEWED) Integration Guide Integration APIs PUBLIC 883 Measure Global Field Names Sent Messages NumberOfSentMessages The number of sent messages is the sum of interactions with one of the ap plicable interaction types. Rejected Messages Clicks Executed Interactions These include all interactions that aren't inbound. An execution run key (EXECU TION_RUN_KEY) is required. Failed Interactions NumberOfRejectedMessages NumberOfClicks NumberOfExecutedInteractions NumberOfFailedInteractions Unique Clicks NumberOfUniqueClicks Unique clicks are calculated per email or message and can't be broken down by link. Open Channel Interactions NmbrOfOpenChannelInteractions The execution run key (EXECU TION_RUN_KEY) must contain a value for an Open Channel Action. Interaction Types Outbound Email (EMAIL_OUTBOUND) Hard Bounce (EMAIL_BOUNCE_HARD) Soft Bounce (EMAIL_BOUNCE_SOFT) Emails Classified as Complaint (Spam) (EMAIL_COMPLAINT) Outbound Text Message (SMS_OUT BOUND) Hard Bounce (SMS_BOUNCE_HARD) Soft Bounce (SMS_BOUNCE_SOFT) Hard Bounce (BOUNCE_HARD) Mobile Notification Sent (MOB_APP_NOTIF_SENT) Outbound Message from Digital Ac count (DIG_ACC_OUTBOUND) Delivery Failed (DELIVERY_FAILED) Delivery Failed (DELIVERY_FAILED) Click Through (CLICK_THROUGH) Any interaction type Outbound Failed (OUTBOUND_FAILED) Outbound Check Failed (OUT BOUND_CHCK_FAILED) Click Through (CLICK_THROUGH) Open Channel (OPEN_CHANNEL) For more information about the Open Channel Integration, see Open Channel Integration [page 194]. 884 PUBLIC Integration Guide Integration APIs For all of these measures, except for Unique Clicks, the following dimensions are available as drilldowns in the aggregated success, if data is available: Communication Medium Interaction UTC Date Interaction Date in Campaign Time Zone Campaign Time Zone Campaign Content ID Campaign Content Name Campaign Automation Action UUID For Clicks, the following dimensions are also available: Campaign Content Link Name Campaign Content Link Alias Name For Failed Interations and Delivery Failed Messages, the following dimensions are also available: Interaction Type Interaction Reason For Unique Clicks, the following dimensions are available: Communication Medium Campaign Content ID Campaign Content Name Campaign Automation Action UUID Campaign Execution Run Date Business Documents The measures in aggregated success listed below are updated using business documents. These business documents are handled the same as the interactions above. All of the business documents must have the communication medium Business Document (BUSINESS_DOCUMENT). Business Documents Used to Update Aggregated Success Measure Global Field Names Leads NumberOfLeads Interaction Types Lead (MARKETING_LEAD) Opportunities Opportunity Amount Orders NumberOfOpportunities Opportunity ('OPPORTUNITY) OpportunityAmount, OpportunityTran Opportunity ('OPPORTUNITY) sactionCurrency NumberOfOrders Sales Order (SALES_ORDER) Order Amount OrderAmount, OrderTransactionCur rency Sales Order (SALES_ORDER) Integration Guide Integration APIs PUBLIC 885 Measure Phone Calls Appointments Tasks Executed Interactions Failed Interactions Global Field Names NumberOfPhoneCalls NumberOfAppointments NumberOfTasks NumberOfExecutedInteractions NumberOfFailedInteractions Interaction Types Incoming Telephone Call (TELE PHONE_INBOUND) Outgoing Telephone Call (TELE PHONE_OUTBOUND) Unsuccessful Telephone Call (TELE PHONE_UNSUCESSFL) Appointment (APPOINTMENT) Canceled Appointment (APPOINT MENT_CANCELLD) Task (TASK) Any interaction type (excluding inbound interactions) Outbound Failed (OUTBOUND_FAILED) Outbound Check Failed (OUT BOUND_CHCK_FAILED) For all of the business documents, the following dimensions are available as drilldowns, when data is available: Communication Medium Interaction Status Interaction UTC Date Interaction Date in Campaign Time Zone Campaign Time Zone Campaign Automation Action UUID 5.5.8 Survey Set up the SAP Marketing Cloud integration with either a third-party survey tool or SAP Qualtrics Surveys via the SAP Cloud Integration. You can integrate survey metadata and survey responses from either a third-party survey tool or SAP Qualtrics Surveys using an OData service. Use the imported survey responses to create target groups and view analytics in the Query Browser app. Prerequisites You have a third-party survey tool or SAP Qualtrics Surveys. You have configured communication management by using the communication scenario SAP_COM_0073. For more information, see Communication Management. You've created a Survey channel by performing the following steps: 886 PUBLIC Integration Guide Integration APIs 1. In SAP Marketing Cloud, launch the Manage Your Solution app. 2. Add a new interaction channel Survey. 3. Assign communication medium Web and interaction type Survey Response to the Survey channel. 4. Choose Save. Context As a marketer, it's important to get constant feedback from your valued customers about the product or service that you're selling on the market. Marketers initiate online surveys using third-party survey provider tools or use SAP Qualtrics Surveys to collect valuable feedback from their customers, analyze survey responses, and use this data to improve customer experience. Procedure 1. Create a survey using a third-party survey tool or using SAP Qualtrics Surveys. 2. Use extensibility tools in the third-party survey tool to create a custom variable and name it as soid. 3. Copy the generated survey URL. 4. Create an email template in SAP Marketing Cloud: a. Launch the Content Studio app. b. In the New Content dialog box, select Global from the Marketing Area dropdown. c. Choose Create. d. In the Design tab, paste the survey URL into the Text field of the email. e. Select the Outbound ID for Consuming App checkbox to append a unique reference to the survey URL. The Outbound ID is the external ID of the interaction contact. f. Release the email template. 5. Use the email template in email campaigns. For more information, see Email and Text Message Campaigns. The target group members receive the email containing the survey link. The survey responses are stored in the third-party survey tool. 6. Use the OData API service to import the survey responses into SAP Marketing Cloud. For more information, see Survey OData API [page 890]. By default, the Survey node is hidden on the Segmentation UI. For any segmentation profile, you must enable Survey Name from the Segmentation Configuration app. 7. Use the survey responses to create a target group in segmentation: a. Launch the Segmentation Models app and choose Create. b. In the Profile dropdown, select the required segmentation profile. The All Consumers and All Contacts segmentation profiles include the data of the All Interactions segmentation profile. The All Interactions segmentation profile doesn't include the data of the All Consumers and All Contacts segmentation profiles. c. Drag the Provider attribute from Survey group, and choose the required survey provider from the value help. d. Enter the Segment Name (optional) and choose Keep. Integration Guide Integration APIs PUBLIC 887 e. Drag the Name attribute from Survey group and choose the required survey name from the value help. f. Drag the Question attribute from Survey group and choose the required survey question from the value help. The following tables list the survey question types and subtype supported in SAP Marketing Cloud: Question type `MX' - Matrix along with the question subtype `MU' - Menu isn't supported in SAP Marketing Cloud. Survey Question Types: Question Type Description RB Radio Button CB Checkbox DL Dropdown List FT Free Text MX Matrix OE Open Ended DG Demographic DT Date Time OT Survey Question Subtypes: Rank Order Question Subtype Description VT Vertical HZ Horizontal MU Menu SL Single RT Rating RK Ranking ML Multiple NU Numerical ES Essay IN International 888 PUBLIC Integration Guide Integration APIs Question Subtype US BO DO TO DT Description United States Both Date Only Time Only Descriptive Text The following table lists the Qualtrics question types and subtype supported by SAP Marketing Cloud: Qualtrics Question Type - SAP Marketing Cloud Subtype - SAP Marketing Cloud MAVR (Multiple Answers, Vertical) CB VT MAHR (Multiple Answers, CB HZ Horizontal) SAVR (Single Answer, Vertical) RB VT SAHR (Single Answer, Horizontal) RB HZ DL (Drop Down) DL MU SB (Select Box) RB VT MSB (Multiple Select Boxes) CB VT NPS RB HZ TE (Text Entry) FT SL/ML/ES Slider RB RT RO (Rank Order) RO RK Matrix MX SL SAP Marketing Cloud supports only Drop Down List and Single Answer subtype questions for Matrix question type on SAP Qualtrics Surveys. g. Drag the Answer attribute from Survey group and choose the survey responses that you would like to analyze. You can refine the segmentation model using the following survey fields: Provider Question Answer Integration Guide Integration APIs PUBLIC 889 Marketing Area ID Survey Status Free Text Responded At h. After completing segmentation, create a target group based on survey responses. 8. Use the target group in the Campaigns app to send emails. 5.5.8.1 Survey OData API OData API (CUAN_SURVEY_IMPORT_SRV) that supports operations on survey metadata and survey responses. Overview The Survey OData API supports operations on the Survey Business Object. Name of the Service Authorizations Communication Scenario ID Component for Incidents CUAN_SURVEY_IMPORT_SRV This feature can be enabled with the Communication Sce nario SAP_COM_0073. SAP_COM_0073 CEC-MKT-INT-SI (Survey Integration) 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 Suported 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ CUAN_SURVEY_IMPORT_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ CUAN_SURVEY_IMPORT_SRV/$metadata Yes You can view sample payloads and test the API at https://api.sap.com . 890 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/ CUAN_SURVEY_IMPORT_SRV;v=0002/ $metadata?sapdocumentation=all Only for internal access. You must provide the server and port names. Marketing - Survey 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. Survey ODATA API General access link takes you directly to the Survey metadata file. One-time regis tration 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 Entities The Survey OData API provides the following entities: Entity SurveySet QuestionSet SurveyResponseSet Description Path This entity contains survey metadata. /SurveySet This entity contains survey questions. /QuestionSet This entity contains survey responses. /SurveyResponseSet Integration Guide Integration APIs PUBLIC 891 Entity AnswerSet ChoiceSet SurveyResponseDetailSet EventSet Description Path This entity contains survey answers to /AnswerSet survey questions. This entity contains choice options to the survey questions. /ChoiceSet This entity contains details of the sur vey responses. /SurveyResponseDetailSet This entity contains details of events associated with surveys. /EventSet SurveySet Resource Path: /SurveySet You can perform the following operations on the SurveySet entity: Operations on SurveySet Entity HTTP Method Description GET Get a list of surveys. Get a specific survey. POST Create a survey. Note You can either create a survey or a poll. By default, the SurveyType is blank and creates a survey. If you want to create a poll, enter P in the SurveyType field. Path /SurveySet /SurveySet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`) /SurveySet You can extend the fields of the SurveySet entity as follows: 1. Configure communication management. For more information, see Communication Management. 2. Create a custom field. For more information, see Custom Fields 3. On the UIs and Reports tab, enable the Field Usage for Survey Import Service. 4. The payload of the SurveySet entity contains the new field. 892 PUBLIC Integration Guide Integration APIs QuestionSet Resource Path: /QuestionSet You can perform the following operations on the QuestionSet entity: Operations on QuestionSet Entity HTTP Method Description Path GET Get list of questions of a survey. /QuestionSet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`) Get a specific question of a survey. /QuestionSet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,QuestionId=`<Question ID>`) Get the list of questions in a particular survey. /SurveySet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,)/SurveyQuestionSet POST Create a survey question. /QuestionSet SurveyResponseSet Resource Path: /SurveyResponseSet You can perform the following operations on the SurveyResponseSet entity: Operations on SurveyResponseSet Entity HTTP Method Description GET Get list of responses of all surveys. Get a response of a specific survey. Get all the responses of a specific survey. Path /SurveyResponseSet /SurveyResponseSet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,ResponseId=`<Response ID>`) /SurveySet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`)/SurveySurveyResponseSet Integration Guide Integration APIs PUBLIC 893 HTTP Method POST Description Create a survey response. Note Use extensibility tools in the thirdparty survey tool to create a custom variable and name it as soid. For more information, see Survey [page 886]. While importing survey responses, the e-mail ID must be unique so that there's no inconsistency in the CONTACT_KEY of the survey re sponse. An interaction of type SURVEY_RESPONSE is created for each survey response. Path /SurveyResponseSet AnswerSet Resource Path: /AnswerSet You can perform the following operations on the AnswerSet entity: Operations on AnswerSet Entity HTTP Method Description Path GET Get the answer of a specific question in a sur /QuestionSet(QuestionId=`<Question vey. ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,SurveyId=`<Survey ID>`)/ QuestionAnswerSet Get the list of questions and answers for a particular survey. /SurveySet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>)?&$expand=SurveyQuestionSet/ QuestionAnswerSet ChoiceSet Resource Path: /ChoiceSet 894 PUBLIC Integration Guide Integration APIs You can perform the following operations on the ChoiceSet entity: Operations on ChoiceSet Entity HTTP Method Description Path GET Get the choices to a specific question in a sur /QuestionSet(QuestionId=`<Question vey. ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,SurveyId=`<Survey ID>`)/ QuestionChoiceSet Get the list of questions and choices for a specific survey. /SurveySet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>)?&$expand=SurveyQuestionSet/ QuestionChoiceSet Get the list of questions, answers, and choices for a specific survey. /SurveySet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>)/SurveyQuestionSet?sapclient=100& $expand=QuestionAnswerSet,QuestionChoi ceSet /SurveySet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>))?&$expand=SurveyQuestionSet/ QuestionAnswerSet,SurveyQuestionSet/ QuestionChoiceSet (with root data) SurveyResponseDetailSet You can perform the following operations on the SurveyResponseDetailSet entity: Resource Path: /SurveyResponseDetailSet Operations on SurveyResponseDetailSet Entity HTTP Method Description Path GET Get the response details of a specific survey. /SurveyResponseSet(Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,ResponseId=<Response ID>`, `SurveyId=`<Survey ID>`)/ SurveyResponseSurveyResponseDetailSet Integration Guide Integration APIs PUBLIC 895 EventSet Resource Path: /EventSet You can perform the following operations on the EventSet entity: Operations on EventSet Entity HTTP Method Description Path GET Get the list of all events of all surveys. /EventSet Get the list of all events for a specific survey. /SurveySet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,Version=`<Survey Version Number>`)/SurveyEventSet Get the details of a particular event for a spe cific survey. /EventSet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,MktgEventUUID=`<MktgEventUUID>`) POST Create an event. /EventSet PUT Update a specific event for the specified sur /EventSet(SurveyId=`<Survey vey. ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,MktgEventUUID=`<MktgEventUUID>`) DELETE Delete a specific event for the specified sur vey. /EventSet(SurveyId=`<Survey ID>`,Provider=`<Survey Provider>`,=Version=`<Survey Version Number>`,MktgEventUUID=`<MktgEventUUID>`) 5.5.8.2 Payload Examples for Survey The following examples show how you can use the Survey API. Payload Example for Survey ROOT: POST OData End-Point: /sap/opu/odata/SAP/CUAN_SURVEY_IMPORT_SRV/SurveySet Sample Code { "SurveyId":"1234", "Provider":"SurveyMonkey", "Version":1, "Name":"SurveyMonkey Demo", "NickName":"Demo", "AccountId":"1", 896 PUBLIC Integration Guide Integration APIs "Category":"customer feedback", "Url":"www.surveymonkey.com", "MarketingAreaId":"Global", "Language":"E", "IsSurveyAnonymous":false, "CreatedOn":"2018-01-01T02:03:04", "ModifiedOn":"2018-02-02T02:03:04", "ValidFrom":"2018-01-01T02:03:04", "ValidTo":"2018-12-31T02:03:04", "IsMultipleRespAllowed":true } Payload Example for Survey ROOT and Question: POST OData End-Point: /sap/opu/odata/SAP/CUAN_SURVEY_IMPORT_SRV/SurveySet Sample Code { "SurveyId":"1234", "Provider":"SurveyMonkey", "Version":1, "Name":"SurveyMonkey Demo", "NickName":"Demo", "AccountId":"1", "Category":"customer feedback", "Url":"www.surveymonkey.com", "MarketingAreaId":"Global", "Language":"E", "IsSurveyAnonymous":false, "CreatedOn":"2018-01-01T02:03:04", "ModifiedOn":"2018-02-02T02:03:04", "ValidFrom":"2018-01-01T02:03:04", "ValidTo":"2018-12-31T02:03:04", "IsMultipleRespAllowed":false, "SurveyQuestionSet": [ { "SurveyId":"1234", "Provider":"SurveyMonkey", "Version":1, "QuestionId": "Q2", "Language": "E", "PageId": 1, "Position": 1, "IsMandatory": false, "Type": "RB", "TypeName": "Single", "SubType": "VT", "Text": "Gender" } ] } Payload Example for Survey ROOT, Question, and Answer: POST OData End-Point: /sap/opu/odata/SAP/CUAN_SURVEY_IMPORT_SRV/SurveySet Integration Guide Integration APIs PUBLIC 897 Sample Code { "SurveyId":"1234", "Provider":"SurveyMonkey", "Version":1, "Name":"SurveyMonkey Demo", "NickName":"Demo", "AccountId":"1", "Category":"customer feedback", "Url":"www.surveymonkey.com", "MarketingAreaId":"Global", "Language":"E", "IsSurveyAnonymous":false, "CreatedOn":"2018-01-01T02:03:04", "ModifiedOn":"2018-02-02T02:03:04", "ValidFrom":"2018-01-01T02:03:04", "ValidTo":"2018-12-31T02:03:04", "IsMultipleRespAllowed":false, "SurveyQuestionSet":[ { "SurveyId":"1234", "Provider":"SurveyMonkey", "Version":1, "QuestionId": "Q2", "Language": "E", "PageId": 1, "Position": 1, "IsMandatory": false, "Type": "RB", "TypeName": "Single", "SubType": "VT", "Text": "Gender", "QuestionAnswerSet":[ { "RowId":"A1", "Language":"E", "RowText":"Male", "RowPosition":1 }, { "RowId":"A2", "Language":"E", "RowText":"Female", "RowPosition":2 } ] } ] } Payload Example for Survey Metadata ($batch): POST OData End-Point: /sap/opu/odata/SAP/CUAN_SURVEY_IMPORT_SRV/$batch Sample Code --batch_01869434-0005 Content-Type: multipart/mixed; boundary=changeset_01869434-0005-0001 --changeset_01869434-0005-0001 Content-Type: application/http 898 PUBLIC Integration Guide Integration APIs Content-Transfer-Encoding: binary POST SurveySet HTTP/1.1 Content-Type: application/json Content-Length: 1021 {"SurveyId":"1234","Provider":"SurveyMonkey","Version": 1,"ValidFrom":"2018-01-03T02:03:04","ValidTo":"2018-12-31T02:03:04","CreatedOn ":"2018-01-02T02:03:04","ModifiedOn":"2018-02-02T02:03:04","SurveyQuestionSet{ "SurveyId":"1234","Provider":"SurveyMonkey","Version": 1,"QuestionId":"Q1","Language":"E","Text":"Gender","Type":"RB","QuestionAnswer Set":[{"RowId":"A1","RowText":"Male","Language":"E","RowPosition":1}, {"RowId":"A2","RowText":"Female","Language":"E","RowPosition":2}]}]} --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST SurveySet HTTP/1.1 Content-Type: application/json Content-Length: 1021 {"SurveyId":"12345","Provider":"SurveyMonkey","Version": 1,"ValidFrom":"2018-01-03T02:03:04","ValidTo":"2018-12-31T02:03:04","CreatedOn ":"2018-01-02T02:03:04","ModifiedOn":"2018-02-02T02:03:04"} --changeset_01869434-0005-0001---batch_01869434-0005-- Payload Example for Survey Response: POST OData End-Point: /sap/opu/odata/SAP/CUAN_SURVEY_IMPORT_SRV/SurveyResponseSet Sample Code { "SurveyId":"1234", "Provider":"SurveyMonkey", "Version":1, "ResponseId":"11", "Id":"response@sap.com", "IdOrigin":"EMAIL", "IsResponseAnonymous":false, "ResponseUrl":" www.surveymonkey.com ", "RespondedOn":"2018-03-08T02:03:04", "SurveyResponseSurveyResponseDetailSet":[ { "QuestionId":"Q1", "ResponseIdRow":"A1" }, { "QuestionId":"Q2", "ResponseIdRow":"R1", "ResponseIdCol":"C2" } ], "SurveyResponseContactSet": { "SurveyId": "1234", "Provider": "SurveyMonkey", "Version": 1, "NameFirst": "Suresh", "NameLast": "K", "EmailAddr": "suresh.r.kai@sap.com", "TelephoneNo": "9008122077" } } Integration Guide Integration APIs PUBLIC 899 Payload Example for Survey Response ($batch): POST OData End-Point: /sap/opu/odata/SAP/CUAN_SURVEY_IMPORT_SRV/$batch Sample Code --batch_01869434-0005 Content-Type: multipart/mixed; boundary=changeset_01869434-0005-0001 --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST SurveyResponseSet HTTP/1.1 Content-Type: application/json Content-Length: 1021 { "Provider":"SurveyMonkey", "ResponseId":"11", "SurveyId":"1234", "Version":1, "Id":"response1r11@sap.com", "IdOrigin":"EMAIL", "IsResponseAnonymous":false, "ResponseUrl":"www.surveymonkey.com", "RespondedOn":"2018-02-04T02:03:04", "SurveyResponseSurveyResponseDetailSet":[ { "QuestionId":"Q1", "ResponseIdRow":"A1" }, { "QuestionId":"Q2", "ResponseIdRow":"R1", "ResponseIdCol":"C2" } ] } --changeset_01869434-0005-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST SurveyResponseSet HTTP/1.1 Content-Type: application/json Content-Length: 1021 { "Provider":"SurveyMonkey", "ResponseId":"12", "SurveyId":"1234", "Version":1, "Id":"response1r12@sap.com", "IdOrigin":"EMAIL", "IsResponseAnonymous":false, "ResponseUrl":"www.surveymonkey.com", "RespondedOn":"2018-02-04T02:03:04", "SurveyResponseSurveyResponseDetailSet":[ { "QuestionId":"Q1", "ResponseIdRow":"A1" }, { "QuestionId":"Q2", "ResponseIdRow":"R1", "ResponseIdCol":"C2" 900 PUBLIC Integration Guide Integration APIs } ] } --changeset_01869434-0005-0001---batch_01869434-0005-- Payload Example for an Event Creation: POST OData End-Point: /sap/opu/odata/SAP/CUAN_SURVEY_IMPORT_SRV/EventSet Sample Code { "SurveyId":"SRV_EVT1_0002", "Provider":"Qualtrics", "Version":1, "MktgEventExternalID":"5482759", "MktgEventUUID":"6C0B84B7-5523-1EE9-B2B0-5DAC5A630B55", "MktgEventProvider":"ON24_ID", "MktgEventProviderAccount":"23192" } 5.5.9 Read Content of Export Files in Campaigns Public OData API for Export Definition. An export definition is a template for structuring the export of target group member data, included in a target group or a campaign, to CSV files. Overview The public API for Export Definition supports operations on the Export Definition Business Object. Name of the Service Underlying BO Package API_MKT_EXPORT_DEFINITION BO HPA_EXPORT_DEFINITION Read of BO CUAN_INITIATIVE and CUAN_MARKETING_ORCHESTRATION CUAN_ODATA_API_EXPORT_DEF Integration Guide Integration APIs PUBLIC 901 Technical Data Technical Data of Service OData Version Root URI Service Metadata URI Communication Scenario ID Component for Incidents 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_EXPORT_DEFINITION_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_EXPORT_DEFINITION_SRV/$metadata SAP_COM_0311 CEC-MKT-EXP 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: Access Link Remarks https:// <Server>:<Port>/sap/opu/ odata/SAP/ API_MKT_EXPORT_DEFINITION_SRV/ $metadata?sapdocumentation=all Only for internal access. You need to provide the server and port names. Read Content of Export Files in Cam paigns 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. Read Content of Export Files in Cam paigns API General access link takes you directly to the Read Content of Export Files in Campaigns 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: 902 PUBLIC Integration Guide Integration APIs Metadata Value in XML sap:updatable sap:creatable nullable Meaning When FALSE read-only field read-only field mandatory field Entity Sets The Export Definition OData API provides the following entity sets: Entity Set ObjectFiles Description This entity contains data for an export file created during campaign execu tion. Path /ObjectFiles Resource Path: /ObjectFiles You can perform the following operations on the /ObjectFiles entity set: Operations on ObjectFiles entity set HTTP Method Description GET Get a list of Export File Names for a campaign ID. Note Provide property CampaignID Provide property FileName (space) Use property DateFrom as filter to get files not older than the specified date/time Path / ObjectFiles(CampaignID='nnnn nnnnnn',FileName=") /ObjectFiles? $filter=CampaignID eq 'nnnnnnnnnn' and DateFrom gt datetime'yyyy-mm-ttThh:mm:ss GET (STREAM) Get the stream of an Export File Content in Xstring for mat for the specified properties FileName and CampaignID. Note / ObjectFiles(CampaignID='nnnnnnnn nn',FileName='mmmmmmmmmmmmmmmmm' )/$value Provide properties CampaignID and FileName (from result of first GET) The $value parameter is mandatory. You can view sample payloads and test the API at https://api.sap.com . Integration Guide Integration APIs PUBLIC 903 5.5.10 Marketing Events This section about marketing events gives you all the details about the public OData API (API_MKT_EVENT_SRV). Marketing Events OData API [page 904] Public OData API (API_MKT_EVENT_SRV) for importing events data from third-party event provider platforms. Payload Examples for Marketing Events [page 917] The following examples show how you can use the marketing events API: Function Imports [page 922] Function imports are used to perform custom operations on an entity, in addition to typical OData operations. This section also provides payload examples. 5.5.10.1 Marketing Events OData API Public OData API (API_MKT_EVENT_SRV) for importing events data from third-party event provider platforms. Overview With the OData Service API_MKT_EVENT_SRV, you can import events, participants, and participants Q&A from third-party event provider platforms such as ON24, Zoom, and so on. Participants are imported as contacts and are used for event promotions and follow-up marketing activities in SAP Marketing Cloud. OData Version Root URI Service Metadata URI Authorizations Communication Scenario ID Component for Incidents 2.0 https://Server:Port/sap/opu/odata/SAP/ API_MKT_EVENT_SRV https://Server:Port/sap/opu/odata/SAP/API_MKT_EVENT_SRV/$metadata Business Catalog: SAP_CEC_BC_MKT_API_EVENT_PC SAP_COM_CSR_0371 CEC-MKT-EVT Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Field Extensibility Supported Yes 904 PUBLIC Integration Guide Integration APIs Recommendation APIs do not support parallel calls for a single marketing event. SAP recommends that you make API calls in a sequence for a given marketing event. 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 https:// <Server>:<Port>/sap/opu/ odata/SAP/API_MKT_EVENT_SRV/ $metadata?sapdocumentation=all Marketing - Marketing Events Page Marketing Events API Remarks Only for internal access. You need to provide the server and port names. 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. General access link takes you directly to the Marketing Events metadata file. Onetime registration or logon is required. Support of OData Features Feature Query options for value help entities Bulk processing using deep-create Batch processing of multiple service call Contact check Support The current implementation of the value help entities supports the following query options, which can be either passed as a query or path parameters: $top and $skip $select $orderby $count and $inlinecount The service supports bulk processing using deep-create. Multiple services like import events, participants, and participant Q&A can be called together. While importing a participant as contact, checks if a contact with same ID and ori gin already exists in SAP Marketing system. Integration Guide Integration APIs PUBLIC 905 Entity Data Model Service Metadata URI: https://Server:Port/sap/opu/odata/SAP/API_MKT_EVENT_SRV/$metadata MarketingEvents Resource Path: /MarketingEvents You can perform the following operations on the MarketingEvents resource: Operations on the MarketingEvents resource HTTP Method Description GET Getting all marketing events GET Getting a single marketing event URI /MarketingEvents /MarketingEvents ('<MktgEventUUID>') POST Deep-create or create a single program /MarketingEvents PUT Updating a single marketing event /MarketingEvents ('<MktgEventUUID>') Properties Parameter Description Creatable MktgEventUUID Unique identifier generated in SAP Marketing Cloud system for every marketing event MktgEvent Identifier of the marketing event MktgObjVersHdr UUID Unique identifier generated in SAP Marketing Cloud system for version of the marketing object MktgEventExter External identifier X nalId of the imported marketing event Updatable Key Mandatory X (except for event with the status "In Preparation") 906 PUBLIC Integration Guide Integration APIs Parameter Description Creatable MktgEventProvi Name of the mar X der keting event pro vider Note This field is va lidated with the ID Origin of contact maintained in the SAP Mar keting Cloud system. MktgEventProvi Provider account X derAccount of the marketing event MktgEventName Name of the mar X keting event MktgEventDescr Description of the X iption marketing event MktgEventStatu Identifier of the X s marketing event status. This is a pre-delivered and configurable field. MktgEventStatu Name of the mar sName keting event status MediaType Identifier of the X media type. This is a pre-delivered and configurable field. MediaTypeName Name of the media type MktgEventEndDa End date and time X teTime (in UTC) of the marketing event Updatable Key X X X X X X X (except for events with status "Conducted" and "Cancelled") Mandatory X X X X Integration Guide Integration APIs PUBLIC 907 Parameter Description Creatable MktgEventStart Start date and X DateTime time (in UTC) of the marketing event Note Value of event start date should be lesser than or equal to the value of event end date. If the event start date is in the future, then you cannot set the event sta tus to "Con ducted". Updatable Key X (except for events with status "Conducted" and "Cancelled") Mandatory X 908 PUBLIC Integration Guide Integration APIs Parameter Description Creatable MktgEvtReplayA Date and time (in X vailFromDateTi UTC) from when me the on-demand re cording will be available. Note Value of ondemand re cording availa ble from date (MKTGEVTREP LAYAVAILFRO MDATETIME) should be lesser than or equal to the value of ondemand re cording availa ble until date (MKTGEVTREP LAYAVAILTOD ATETIME). MktgEvtReplayA Date and time (in X vailToDateTime UTC) until when the on-demand re cording will be available MktgEventTimez Time zone of the X one marketing event. This is a pre-deliv ered and configu- rable field. MarketingArea Identifier of the X marketing area MarketingAreaN Name of the mar ame keting area name Language Language key X Updatable Key X X X X X Mandatory Integration Guide Integration APIs PUBLIC 909 Parameter Description Creatable MktgEventInfoU URL of the market X RL ing event MktgEventRegis Registration URL X trationURL of the marketing event MktgEventOnlin Live URL of the X eURL marketing event MktgEventRepla On-demand URL X yURL of the marketing event MktgEventType Type of the mar X keting event. This is a pre-delivered field. MktgEventTypeN Type name of the ame marketing event CreatedByUser Name of the user who created the marketing event CreationDateTi me Date and time when the market ing event was cre ated LastChangedByU ser Name of the user who last changed the marketing event LastChangeDate Time Date and time when the market ing event was last changed The following event status values are available: 0001 for In Preparation 0002 for Ready 0003 for Cancelled 0004 for Conducted 0005 for Archived Updatable Key X X X X 910 PUBLIC Mandatory Integration Guide Integration APIs The following event type values are available: _ (read as blank) for Online 10 for In Person The following event status transitions are possible: Source Status ID 0001 0001 0001 0001 0002 0002 0002 0003 0004 Target Status ID 0002 0003 0004 0005 0003 0004 0005 0005 0005 EventParticipants Resource Path: /EventParticipants You can perform the following operations on the EventParticipants resource: Operations on the EventParticipants resource HTTP Method Description GET Getting all marketing event participants GET Getting a single marketing event participant URI /EventParticipants /EventParticipants ('<MktgEventParticipantUUID>') POST Deep-create or create a single marketing event participant /MarketingEvents ('<MktgEventUUID>')/ to_Participant PUT Updating a single marketing event participant /EventParticipants ('<MktgEventParticipantUUID>') DELETE Deleting a single marketing event participant along with it's interactions and survey response data /EventParticipants ('<MktgEventParticipantUUID>') Integration Guide Integration APIs PUBLIC 911 Properties Parameter Description Creatable MktgEventParti cipantUUID Unique identifier generated in SAP Marketing Cloud system for every marketing event participant MktgEventUUID Unique identifier generated in SAP Marketing Cloud system for every marketing event MktgEventParti External identifier X cipantExternal of the imported ID marketing event participant ContactOrigin Origin of interac X tion contact data MktgEngagement Participation score X Score TotalNumberOfM Total number of X inutesAttended minutes a partici pant attended the event live and on- demand NumberOfQuesti ons Number of ques X tions asked by par ticipants NumberOfPollsA Number of polls X nswered responded by par ticipants NumberOfSurvey sAnswered Number of surveys X answered by par ticipants NumberOfConten Number of con X tDownloads tents downloaded by participants Updatable Key X X X X X X X Mandatory X X 912 PUBLIC Integration Guide Integration APIs Parameter Description Creatable TotalNumberOfM Total number of X inutesLive minutes a partici pant attended the event live TotalNumberOfM Total number of X inutesReplay minutes a partici pant attended the event on-demand MktgEventParti Identifier of the X cipantStatus participant status. A list of participant status is pre-deliv ered. MktgEventParti Identifier of the X cipantID participant MktgEventParti cipantStatusNa me Name of the par ticipant status CreationDateTi me Date and time when the market ing event was cre ated CreatedByUser Name of the user who created the marketing event LastChangeDate Time Date and time when the market ing event was last changed LastChangedByU ser Name of the user who last changed the marketing event FullName Full name of the participant EmailAddress Email address of the participant Updatable Key X X X Mandatory Integration Guide Integration APIs PUBLIC 913 Parameter Description Creatable CompanyName Company name of the participant IsEndOfPurpose Blocked Indicates that a participant's data is discarded irre versibly on the event provider platform Updatable Key Mandatory The following table shows if you are allowed to create participants based on the status of the event: Participant Status Event Status In Prepara tion Ready Attended No No Registered No Yes No show No No Invited No No Conducted Cancelled Archived Yes No No Yes No No Yes No No No No No EventStatuses Resource Path: /EventStatuses You can perform the following operations on the EventStatuses resource: Operations on the EventStatuses resource HTTP Method Description GET Getting all marketing event participants URI /EventStatuses Properties Parameter MktgEventStatus Description Creatable Identifier of the mar keting events status Updaatable Key X 914 PUBLIC Integration Guide Integration APIs Parameter Description Creatable MktgEventStatusNa Name of the marketing me event status Updaatable Key ParticipantQuestionAnswers Resource Path: /ParticipantQuestionAnswers You can perform the following operations on the EventStatuses resource: Operations on the ParticipantQuestionAnswers resource HTTP Method Description URI GET Getting all questions and answers of marketing event partici /ParticipantQuestionAnswers pant GET GET POST PUT DELETE Getting a single participant's questions and answers /ParticipantQuestionAnswers ('<MktgEvtPrtcpntQstnAnswUUID>') Getting all questions and answers of a single marketing event's participants /EventParticipants ('<MktgEventParticipantUUID>')/ to_QuestionAnswer Deep-create or a single participant's questions and answers create /EventParticipants ('<MktgEventParticipantUUID>')/ to_QuestionAnswer Updating a single participant's questions and answers /ParticipantQuestionAnswers ('<MktgEvtPrtcpntQstnAnswUUID>') Deleting a single participant's questions and answers /ParticipantQuestionAnswers ('<MktgEvtPrtcpntQstnAnswUUID>') Properties Parameter Description Creatable MktgEvtPrtcpntQst nAnswUUID Unique identifier gen erated in SAP Market ing Cloud system for questions and answers of the marketing event participant Updaatable Key X Integration Guide Integration APIs PUBLIC 915 Parameter Description Creatable MktgEventParticip antUUID Unique identifier gen erated in SAP Market ing Cloud system for every marketing event participant MktgEventUUID Unique identifier gen erated in SAP Market ing Cloud system for every marketing event MktgEvtPrtcpntQst Question asked by the X nTxt marketing event par ticipant MktgEvtPrtcpntAns Answer provided by X wTxt the marketing event participant Updaatable Key X X Common Status and Error Codes Code 204 404 201 400 Reason Marketing events, participants, or Q&A updated successfully. Not found, for example, marketing events, participants, or Q&A with the given key cannot be found in the system. Marketing events, participants, or Q&A imported successfully. Bad request, for example, a marketing event, participant, or Q&A with the same key already exists. Related Information https://api.sap.com 916 PUBLIC Integration Guide Integration APIs 5.5.10.2 Payload Examples for Marketing Events The following examples show how you can use the marketing events API: Payload Example for Deep-Create of Marketing Events: POST URI:/MarketingEvents Request Example:[POST] https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_EVENT_SRV/ MarketingEvents Sample Code { "MktgEventExternalId" : "EXt1", "MktgEventProvider" : "ON24_ID", "MktgEventProviderAccount" : "31835", "MktgEventName" : "EVENT", "MktgEventDescription" : "EVENT", "MktgEventStatus" : "0001", "MediaType" : "EVENTS", "MktgEventEndDateTime" : "1018-10-10T12:34:32", "MktgEventStartDateTime" : "1018-10-10T12:34:32", "MktgEvtReplayAvailFromDateTime" : "1018-10-10T12:34:32", "MktgEvtReplayAvailToDateTime" : "1018-10-10T12:34:32", "MktgEventTimezone" : "CET", "MarketingArea" : "GLOBAL", "Language" : "EN", "MktgEventTypeName" : "Online", "MktgEventInfoURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventRegistrationURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventOnlineURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventReplayURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "to_Participant" : [{ "MktgEventParticipantExternalID" : "barryallen@mailinator.com", "ContactOrigin" : "ON24_ID", "MktgEventParticipantID" : "ID1" "MktgEngagementScore" : 10, "TotalNumberOfMinutesAttended" : 20, "NumberOfQuestions" : 60, "NumberOfPollsAnswered" : 50, "NumberOfSurveysAnswered" : 0, "NumberOfContentDownloads" : 0, "TotalNumberOfMinutesLive" : 10, "TotalNumberOfMinutesReplay" : 0, "MktgEventParticipantStatus" : "1003", "to_QuestionAnswer": [ { "MktgEvtPrtcpntQstnTxt": "Can I replay the recording?", "MktgEvtPrtcpntAnswTxt": "Yes you can" } ] } ] } Integration Guide Integration APIs PUBLIC 917 Payload Example for Marketing Events Create: POST URI:/MarketingEvents Request Example:[POST] https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_EVENT_SRV/ MarketingEvents Sample Code { "MktgEventExternalId" : "EXt11", "MktgEventProvider" : "ON24_ID", "MktgEventProviderAccount" : "31835", "MktgEventName" : "EVENT", "MktgEventDescription" : "EVENT", "MktgEventStatus" : "0004", "MediaType" : "EVENTS", "MktgEventEndDateTime" : "2019-04-10T12:37:33", "MktgEventStartDateTime" : "2019-04-10T11:34:32", "MktgEvtReplayAvailFromDateTime" : "1019-10-10T12:34:32", "MktgEvtReplayAvailToDateTime" : "1020-10-10T12:34:33", "MktgEventTimezone" : "CET", "MarketingArea" : "GLOBAL", "Language" : "EN", "MktgEventTypeName" : "Online" "MktgEventInfoURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventRegistrationURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventOnlineURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventReplayURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A" } Payload Example for Marketing Events Update: PUT URI:/MarketingEvents ('<MktgEventUUID>') Request Example:[PUT] https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_EVENT_SRV/ MarketingEvents('<MktgEventUUID>') Sample Code { "MktgEventExternalId" : "EXt11", "MktgEventProvider" : "ON24_ID", "MktgEventProviderAccount" : "31835", "MktgEventName" : "EVENT", "MktgEventDescription" : "EVENT", "MktgEventStatus" : "0004", "MediaType" : "EVENTS", "MktgEventEndDateTime" : "2019-04-10T12:37:33", "MktgEventStartDateTime" : "2019-04-10T11:34:32", "MktgEvtReplayAvailFromDateTime" : "1019-10-10T12:34:32", "MktgEvtReplayAvailToDateTime" : "1020-10-10T12:34:33", "MktgEventTimezone" : "CET", "MarketingArea" : "GLOBAL", 918 PUBLIC Integration Guide Integration APIs "Language" : "EN", "MktgEventTypeName" : "Online" "MktgEventInfoURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventRegistrationURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventOnlineURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventReplayURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A" } Payload Example for Marketing Events Participant Update: PUT URI:/EventParticipants ('<MktgEventParticipantUUID>') Request Example:[PUT] https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_EVENT_SRV/ EventParticipants ('<MktgEventParticipantUUID>') Sample Code { "MktgEventParticipantExternalID" : "EventParticipant@eventstest.com", "ContactOrigin" : "ON24_ID", "MktgEngagementScore" : 10, "TotalNumberOfMinutesAttended" : 20, "NumberOfQuestions" : 60, "NumberOfPollsAnswered" : 50, "NumberOfSurveysAnswered" : 0, "NumberOfContentDownloads" : 0, "TotalNumberOfMinutesLive" : 10, "TotalNumberOfMinutesReplay" : 0, "MktgEventParticipantStatus" : "1002", "MktgEventParticipantID" : "ID1" } Payload Example for Participant Questions and Answers Create: POST URI:/EventParticipants ('<MktgEventParticipantUUID>')/to_QuestionAnswer Request Example:[POST] https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_EVENT_SRV/ EventParticipants ('<MktgEventParticipantUUID>')/to_QuestionAnswer Sample Code { "MktgEvtPrtcpntQstnTxt": "Can I replay the recording?", "MktgEvtPrtcpntAnswTxt": "Yes you can" } Integration Guide Integration APIs PUBLIC 919 Payload Example for Participant Questions and Answers Update: PUT URI:/ParticipantQuestionAnswers ('<MktgEvtPrtcpntQstnAnswUUID>') Request Example:[PUT] https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_EVENT_SRV/ ParticipantQuestionAnswers('<MktgEvtPrtcpntQstnAnswUUID>') Sample Code { "MktgEvtPrtcpntQstnTxt": "Is recording available?", "MktgEvtPrtcpntAnswTxt": "Yes " } Payload Example for Marketing Events ($batch): POST URI:$batch Request Example:[POST] https://<Server>:<Port>/sap/opu/odata/SAP/API_MKT_EVENT_SRV/ $batch Sample Code --batch Content-Type: multipart/mixed; boundary=changeset_01869434-0008-0001 --changeset_01869434-0008-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST MarketingEvents HTTP/1.1 Content-Type: application/json Content-Length: 1021 { "MktgEventExternalId" : "EXt1", "MktgEventProvider" : "ON24_ID", "MktgEventProviderAccount" : "31835", "MktgEventName" : "EVENT", "MktgEventDescription" : "EVENT", "MktgEventStatus" : "0001", "MediaType" : "EVENTS", "MktgEventEndDateTime" : "1018-10-10T12:34:32", "MktgEventStartDateTime" : "1018-10-10T12:34:32", "MktgEvtReplayAvailFromDateTime" : "1018-10-10T12:34:32", "MktgEvtReplayAvailToDateTime" : "1018-10-10T12:34:32", "MktgEventTimezone" : "CET", "MarketingArea" : "GLOBAL", "Language" : "EN", "MktgEventInfoURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventRegistrationURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventOnlineURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "MktgEventReplayURL" : "https://event.on24.com/wcc/r/ 1918973/12F107615216042B4905524623A91E9A", "to_Participant" : [{ "MktgEventParticipantExternalID" : "barryallen@mailinator.com", "ContactOrigin" : "ON24_ID", "MktgEngagementScore" : 10, 920 PUBLIC Integration Guide Integration APIs "TotalNumberOfMinutesAttended" : 20, "NumberOfQuestions" : 60, "NumberOfPollsAnswered" : 50, "NumberOfSurveysAnswered" : 0, "NumberOfContentDownloads" : 0, "TotalNumberOfMinutesLive" : 10, "TotalNumberOfMinutesReplay" : 0, "MktgEventParticipantStatus" : "1003" } ] } --changeset_01869434-0008-0001 Content-Type: application/http Content-Transfer-Encoding: binary POST MarketingEvents(guid'6c0b84b7-5523-1ed9-8ba5-cf63a92f034f')/ to_Participant HTTP/1.1 Content-Type: application/json Content-Length: 1021 { "MktgEventParticipantExternalID" : "eveprt2002@mailinator.com", "ContactOrigin" : "EMAIL", "MktgEngagementScore" : 10, "TotalNumberOfMinutesAttended" : 20, "NumberOfPollsAnswered" : 50, "NumberOfSurveysAnswered" : 0, "NumberOfContentDownloads" : 0, "TotalNumberOfMinutesLive" : 0, "TotalNumberOfMinutesReplay" : 0, "MktgEventParticipantStatus" : "1002" } --changeset_01869434-0008-0001 Content-Type: application/http Content-Transfer-Encoding: binary PUT EventParticipants(guid'6c0b84b7-5523-1ed9-8ba9-3c522fd891d6') HTTP/1.1 Content-Type: application/json Content-Length: 1021 { "MktgEventParticipantExternalID" : "eveprt22@mailinator.com", "ContactOrigin" : "EMAIL", "MktgEngagementScore" : 10, "TotalNumberOfMinutesAttended" : 20, "NumberOfPollsAnswered" : 90, "NumberOfSurveysAnswered" : 0, "NumberOfContentDownloads" : 0, "TotalNumberOfMinutesLive" : 0, "TotalNumberOfMinutesReplay" : 0, "MktgEventParticipantStatus" : "0002" } --changeset_01869434-0008-0001---batch-- Integration Guide Integration APIs PUBLIC 921 5.5.10.3 Function Imports Function imports are used to perform custom operations on an entity, in addition to typical OData operations. This section also provides payload examples. Get Event Languages HTTP Method GET Description Get the list of event languages Path /GetEventLanguage Payload Examples Get Event Languages /sap/opu/odata/SAP/API_MKT_EVENT_SRV/GetEventLanguage 5.6 Commerce Marketing The following APIs are avaible for the Commerce Marketing business area. Recommendations (SAP Business Technology Platform) [page 923] Public OData API (API_MKT_RECOMMENDATION_SRV) that allows a client system to obtain recommendations from the SAP Marketing Cloud using the SAP Business Technology Platform. Recommendations [page 939] The PROD_RECO_RUNTIME_SRV OData service enables customer channels to receive recommendations generated by Recommendation. External Recommendations [page 954] Use the public OData API API_MKT_EXTERNAL_RECMDN_SRV to upload (import) recommendations from external sources. Recommendations Interaction Data [page 971] OData service (PROD_RECO_RUNTIME_SRV) for posting interactions to an SAP HANA database. Import Offers [page 973] Use the public OData API CUAN_OFFER_IMPORT_SRV to upload (import) offers from external sources. Read Offers [page 1002] Public OData API (API_MKT_OFFER_SRV) for Offers Discover Offers [page 1008] Use the API OData service CUAN_OFFER_DISCOVERY_SRV for SAP Marketing Cloud Offers to find suitable offers for a consumer. 922 PUBLIC Integration Guide Integration APIs Coupons [page 1026] Public OData API (API_MKT_COUPON_SRV) for Coupons. 5.6.1 Recommendations (SAP Business Technology Platform) Public OData API (API_MKT_RECOMMENDATION_SRV) that allows a client system to obtain recommendations from the SAP Marketing Cloud using the SAP Business Technology Platform. Technical Data Name of Service Authorization OData Version Root URL Service Metadata URI Field Extensibility Supported API_MKT_RECOMMENDATION_SRV No authorization is required, however, a Security String must be obtained from the Recommendation Scenarios app. Ap pend the security string to every request for validation to oc cur. Note The security string is only valid for requests that origi nate from your system, however, it should not be shared. 2.0 https://[Recommendation Scenario URL]/api/ API_MKT_RECOMMENDATION_SRV/ The root URL points to the SAP Business Technology Platform tenant that is assigned to you. The Root URL (Rec ommendation Scenario URL) is provided through the Recommendation Scenarios app. With the proper user (for example, Marketing Expert or Business Analyst), you can log on to their SAP Marketing Cloud tenant and obtain the nec essary information to consume the service. https://[Recommendation Scenario URL]/api/ API_MKT_RECOMMENDATION_SRV/$metadata Yes. For more information, search for extensibility in Get Of fers [page 928]. Integration Guide Integration APIs PUBLIC 923 Error Messages If the API encounters an error, the following HTTP status codes are returned: Code 429 400 Cause The API has reached the maximum number of allocated API calls. The maximum number of allocated API calls is 200 per second. A bad request was submitted. For example, the security string is invalid. Security String Parameters All function import calls must include the security string parameters. The Security String for a given recommendation scenario, can be obtained through the Recommendations Scenario application, in the Advanced tab. Parameter _L54AD1F204_ _K13_ _K14_ _V_ Required Yes Yes Yes Yes Data Type String Integer String Integer Description Encrypted key information (part of the security string). Secret key version (part of the security string). Generated HMAC string from the key information (part of the security string). Version of the validation (part of the security string) Secure User ID If you opt for using a recommendation scenario with the Secure User ID option, make sure that you enable this option in the Recommendation Scenarios application in your SAP Marketing Cloud system. This option affects your Security String for the scenario, so you need to copy the new value. The User ID Salt value (which needs to be passed along with the User ID in your HTTP request headers) can also be obtained in the same application. Technical Field Documentation and Payload Examples For function import technical field documentation and payload examples, see Function Imports [page 925]. 924 PUBLIC Integration Guide Integration APIs 5.6.1.1 Function Imports Function imports are used to perform custom operations on an entity, in addition to typical OData operations. This section contains technical field documentation and payload examples for the following function imports: Get Recommendations [page 925] GetRecommendations retrieves recommendations from either the SAP Business Technology Platform (cached recommendations) or the SAP Marketing Cloud. Get Offers [page 928] GetOfferRecommendations retrieves offer recommendations (offer content) from either SAP Business Technology Platform (cached recommendations) or SAP Marketing Cloud. Get Products [page 933] GetProducts retrieves product master data from either SAP Business Technology Platform (cached products) or SAP Marketing Cloud. Send Interactions [page 934] SendProductClickThrough and SendOfferClickThrough send interactions that occur between consumers and recommendations. 5.6.1.1.1 Get Recommendations GetRecommendations retrieves recommendations from either the SAP Business Technology Platform (cached recommendations) or the SAP Marketing Cloud. HTTP Method Function Import URL GET GetRecommendations Retrieves recommendations from either the SAP BTP (cached recommendations) or the SAP Mar keting Cloud. Depending on the Recommendation Scenario, the function import can either return product or offer (offer content GUID and score) recommendations. Each call to this service results in an impression being recorded for the scenario. When a recommen dation is retrieved from the SAP Marketing Cloud, the impression is recorded in the back-end sys tem. However, if the recommendation is retrieved from the cache, the impression is stored in a data base table in the SAP BTP. The impressions that are stored in the database table are periodically ag gregated and then posted to the SAP Marketing Cloud. https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ GetRecommendations Integration Guide Integration APIs PUBLIC 925 HTTP Request Header Fields Field _u_ _h_ Mandatory Data Type Optional Appears if Secure User ID check box is checked in Recommendation Scenarios app. String Optional Appears if Secure User ID check box is checked in Recommendation Scenarios app. String Max. Length N/A Description The user ID. N/A An SHA-256 crypto graphic hash of the user ID and the salt Request Parameters Field LeadingItemIds Mandatory Data Type Only for association al String gorithms. LeadingItemType BasketItemIds Only when LeadingItemIds is provided. No String String BasketItemType Only when BasketItemIds is provided ContextParameters No String String 926 PUBLIC Max. Length 1000 50 1000 50 1000 Description The comma-separated product IDs to be passed to the recom mendation scenario. The product type (ori gin) as defined in SAP Marketing Cloud. The comma-separated product IDs which are already in the cart. The product type (ori gin) as defined in SAP Marketing Cloud. The context parame ters as configured in SAP Marketing Cloud. For example, interac tion type, interaction contact type, or any of the other algorithm data source pre-filters (standard delivery or custom). For more in formation, see Algo rithm Data Source Pre filters and Recommen dation Data Source Pre-Filters. Integration Guide Integration APIs Field UserId UserType Mandatory No Data Type String Only when UserId is provided or when Secure User ID check box is checked in Recommendation Scenarios app. String Max. Length 71 50 Description The user ID, depending on the specified user type. This parameter is ig nored if the Secure User ID checkbox is checked in the custom Recommendation Scenarios app. The user facet, as de fined in SAP Marketing Cloud. Example of Request Sample Code https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ GetRecommendations ?LeadingItemIds='11100,10020' &LeadingItemType='SAP_COMMERCE_PRODUCT' &BasketItemIds='10013' &BasketItemType='SAP_COMMERCE_PRODUCT' &UserId='username@sap.com' &UserType='EMAIL' &ContextParameters='PARAM1_ID eq 123,PARAM2_ID eq xyz' &_L54AD1F204_='c2NlbmFyaW89UkVDTyZ0ZW5hbnQ9W215LXRlbmFudF0ub25kZW1hbmQuY29tJnJ lY29fc2NlbmFyaW89U0FQX0NST1NTX1NFTExfV0VCX1BST0RVQ1RfREVUQUlMUyZzZWN1cmVfdXNlc j0=' &_K13_=20 &_V_=2 &_K14_='7875919344b1bbf1970ae84c9a180828c84e6cda40c8873e4ed88abaac0aa7ba2' Note The scenario ID and the marketing tenant are encoded in the_L54AD1F204_parameter. For example, a decoded version of the parameter contained in the example request would be RECO&tenant=[mytenant].ondemand.com&reco_scenario=SAP_CROSS_SELL_WEB_PRODUCT_DETAILS&secure_user =. Integration Guide Integration APIs PUBLIC 927 Example of Response Sample Code <GetRecommendations xmlns="http://schemas.microsoft.com/ado/2007/08/ dataservices" xmlns:m=http://schemas.microsoft.com/ado/2007/08/dataservices/ metadata> <element m:type="API_MKT_RECOMMENDATION_SRV.Recommendation"> <ResultObjectId>10023</ResultObjectId> <ResultObjectType>SAP_HYBRIS_PRODUCT</ResultObjectType> <ResultObjectScore>1.00000</ResultObjectScore> </element> <element m:type="API_MKT_RECOMMENDATION_SRV.Recommendation"> <ResultObjectId>10024</ResultObjectId> <ResultObjectType>SAP_HYBRIS_PRODUCT</ResultObjectType> <ResultObjectScore>0.79831</ResultObjectScore> </element> </GetRecommendations> 5.6.1.1.2 Get Offers GetOfferRecommendations retrieves offer recommendations (offer content) from either SAP Business Technology Platform (cached recommendations) or SAP Marketing Cloud. HTTP Method Function Import URL Field Extensibility GET GetOfferRecommendations Retrieves offer recommendations from either SAP BTP (cached recommendations) or SAP Market ing Cloud. This function import returns offer content, as opposed to the offer content GUID and score returned by the GetRecommendations function import. https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ GetOfferRecommendations The OfferContent complex type supports field extensibility. For more information see, Custom Fields for Offer Header and Offer Content. HTTP Request Header Fields Field _u_ Mandatory Data Type Optional Appears if Secure User ID checkbox is checked in Recommendation Scenarios app. String 928 PUBLIC Description The user ID. Integration Guide Integration APIs Field _h_ Mandatory Data Type Optional Appears if Secure User ID checkbox is checked in Recommendation Scenarios app. String Description An SHA-256 cryptographic hash of the user ID and the salt Request Parameters Field LeadingItemIds Mandatory Data Type Only for association al String gorithms. LeadingItemType BasketItemIds Only when LeadingItemIds is provided. No String String BasketItemType Only when BasketItemIds is provided ContextParameters No String String Max. Length 1000 50 1000 50 1000 Description The comma-separated product IDs to be passed to the recom mendation scenario. The product type (ori gin) as defined in the SAP Marketing Cloud. The comma-separated product IDs which are already in the cart. The product type (ori gin) as defined in the SAP Marketing Cloud. The context parame ters as defined in the SAP Marketing Cloud, e.g.: Interaction Type, Interaction Contact Type. Note Additional request parameters that are not defined in the ContextParamet ers are appended. Integration Guide Integration APIs PUBLIC 929 Field UserId Mandatory No Data Type String UserType Language Only when UserId is provided or when Secure User ID check box is checked in Recommendation Scenarios app. String No String Position No String CommunicationMe No dium OfferContentType No String String Max. Length 71 50 Description The user ID, depending on the specified user type. This parameter is ig nored if the Secure User ID checkbox is checked in the custom Recommendation Scenarios app. The user facet, as de fined in SAP Marketing Cloud. 2 The ISO language code of the offer content. In a Web shop, the lan guage may correspond to the user's logon lan guage. If no language is passed to the OData service, the result con tains all available lan guages. 40 The position in the Web shop where offers are to be displayed, such as Top or Bottom. This informa tion must be main tained for the offer content in the SAP Marketing Cloud. 20 The communication medium as define in the SAP Marketing Cloud. The parameter filters the offer content by the communication medium. 2 The OfferContentType parameter filters offers by content type. 930 PUBLIC Integration Guide Integration APIs Field WithCoupon Mandatory No Data Type String MarketingArea No String Max. Length 1 40 Description The following WithCoupon parame ter values filter offers by whether or not they have a coupon as signed: 'X' retrieves offers with coupons as signed. ' ' retrieves offers without coupons assigned. Note Requests without the parameter re trieve offers with and without cou pons assigned. The marketing area as defined in the SAP Marketing Cloud. The parameter filters offers by marketing area. Example of Request Sample Code https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ GetOfferRecommendations ?LeadingItemIds='PRODUCT_ID_1' &LeadingItemType='SAP_HYBRIS_PRODUCT' &UserId='username@sap.com' &UserType='EMAIL' &_L54AD1F204_='c2NlbmFyaW89UkVDTyZ0ZW5hbnQ9W215LXRlbmFudF0uczRoYW5hLm9uZGVtYW5 kLmNvbSZyZWNvX3NjZW5hcmlvPVRPUF9PRkZFUlMmc2VjdXJlX3VzZXI9WA==' &_K13_=20 &_V_=2 &_K14_='343fd3e7f98cc3842765a4fe965685344560c05207075519ab2e5f9248b51810' Note The scenario ID and the marketing tenant are encoded in the_L54AD1F204_parameter. For example, a decoded version of the parameter contained in the example request would be RECO&tenant=[mytenant].ondemand.com&reco_scenario=SAP_CROSS_SELL_WEB_PRODUCT_DETAILS&secure_user =. Integration Guide Integration APIs PUBLIC 931 Example of Response Sample Code <?xml version='1.0' encoding='utf-8'?> <GetOfferRecommendations xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <element m:type="API_MKT_RECOMMENDATION_SRV.OfferContent"> <MarketingOffer>32</MarketingOffer> <MarketingOfferContent>00001</MarketingOfferContent> <OfferContentType>01</OfferContentType> <OfferContentTypeName>Image</OfferContentTypeName> <CommunicationMedium>EMAIL</CommunicationMedium> <CommunicationMediumName>Email</CommunicationMediumName> <LanguageISOCode>EN</LanguageISOCode> <MarketingArea>CXXGLOBAL</MarketingArea> <OfferContentPosition>Home</OfferContentPosition> <OfferContentSourceURL>https://img.freepik.com/free-vector/colorfulshopping-sale-banner-template_1201-1308.jpg?size=338&ext=jpg</ OfferContentSourceURL> <OfferContentSourceURLDesc>50% Special Offer</OfferContentSourceURLDesc> <OfferContentTargetURL>https://img.freepik.com/free-vector/colorfulshopping-sale-banner-template_1201-1308.jpg?size=338&ext=jpg</ OfferContentTargetURL> <OfferContentTargetURLDesc>50% Special Offer</OfferContentTargetURLDesc> <CouponUUID></CouponUUID> <ExternalOffers></ExternalOffers> </element> </GetOfferRecommendations > Note The same parameters could be used with the getRecommendations function import and result in the following the response: Sample Code <?xml version='1.0' encoding='utf-8'?> <GetRecommendations xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <element m:type="API_MKT_RECOMMENDATION_SRV.Recommendation"> <ResultObjectId>00163E2C7B391ED8AB8B78EE6425E6A0</ResultObjectId> <ResultObjectType>CUAN_OFFER</ResultObjectType> <ResultObjectScore>1.00000</ResultObjectScore> </element> </GetRecommendations> 932 PUBLIC Integration Guide Integration APIs 5.6.1.1.3 Get Products GetProducts retrieves product master data from either SAP Business Technology Platform (cached products) or SAP Marketing Cloud. HTTP Method Function Import URL GET GetProducts Retrieves product master data from either SAP BTP (cached products) or SAP Marketing Cloud. https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ GetProducts Request Parameters Field ProductIds Mandatory Yes Data Type String ProductOrigin Yes String Language Yes String Note All of the parameters in the table are query strings. Max. Length 2000 50 2 Description The comma-separated product IDs to be passed to the recom mendation scenario. The product type (ori gin) as defined in SAP Marketing Cloud. The Language of the master data. Example of Request Sample Code https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ GetProducts ?ProductIds='PRODUCT1,PRODUCT2' &ProductOrigin='SAP_COMMERCE_PRODUCT' &Language='EN' &_L54AD1F204_='c2NlbmFyaW89UkVDTyZ0ZW5hbnQ9W01ZLU1LVC1URU5BTlRdLnM0aGFuYS5vbmR lbWFuZC5jb20mcmVjb19zY2VuYXJpbz1TQVBfVE9QX1NFTExFUl9IT01FX1BBR0U=' &_K13_=1 &_V_=2 &_K14_='9fd60e90b810e9c24fbabd44d2158d564333b4a5f13fc597b343c5bdafc50ea4' Integration Guide Integration APIs PUBLIC 933 Example of Response Sample Code <GetProducts xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <element m:type="com.sap.cec.mkt.recommendation.ProductStructure"> <ProductId>PRODUCT1</ProductId> <ProductDescription>Product One Description Text</ProductDescription> <ProductName>Product 1 Name</ProductName> <ProductTargetUrl> https://[some_host]/.../PRODUCT_DETAILS/PRODUCT1.html </ProductTargetUrl> <ProductImageUrl> https://[some_host]/sap/files/PRODUCT_BRAND/PRODUCT_CATEGORY/ PRODUCT1.jpg </ProductImageUrl> </element> <element m:type="com.sap.cec.mkt.recommendation.ProductStructure"> <ProductId>PRODUCT2</ProductId> <ProductDescription>Product Two Description Text</ProductDescription> <ProductName>Product 2 Name</ProductName> <ProductTargetUrl> https://[some_host]/.../PRODUCT_DETAILS/PRODUCT1.html </ ProductTargetUrl> <ProductImageUrl> https://[some_host]/sap/files/ PRODUCT_BRAND/PRODUCT_CATEGORY/PRODUCT2.jpg </ProductImageUrl> </element> </GetProducts> 5.6.1.1.4 Send Interactions SendProductClickThrough and SendOfferClickThrough send interactions that occur between consumers and recommendations. Send Product Click-Throughs HTTP Method Function Import URL GET SendProductClickThrough Send interactions that occur between consumers and the products that are recommended. https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ SendProductClickThrough 934 PUBLIC Integration Guide Integration APIs Request Parameters Field ItemId Mandatory Yes ItemType Yes UserId No Data Type String String String UserType TargetUrl Only when UserId is provided or when Secure User ID check box is checked in Recommendation Scenarios app. String No String CommunicationMedi Yes um String SourceObjectId Yes String SourceObjectType Yes String Max. Length 50 30 71 50 2000 20 50 30 Description The comma-separated item IDs to be passed to the recommenda tion scenario. The item type as de fined in SAP Marketing Cloud. The user ID, depending on the specified user type. This parameter is ig nored if the Secure User ID checkbox is checked in the custom Recommendation Scenarios app. The User Type configured for the recom mendation scenario in SAP Marketing Cloud. The target URL to be used for the redirec tion. The Communication Medium configured for the recommendation scenario in SAP Mar keting Cloud. The ID of the object that triggered the in teraction. For example, a session or sales or der ID. A custom defined string that describes the type of object passed as the SourceObjectId. Integration Guide Integration APIs PUBLIC 935 Field SourceSystemId Mandatory No Data Type String SourceSystemType Required with SourceSystemId String Max. Length 255 20 Description The ID of the system that is receiving the recommendations, and providing interaction data. For example, a commerce webshop (www.xyz.com). The type of system that is receiving the recommendations and providing interaction data. For example, SAP _Commerce. Example of Request Sample Code https://recow62890cfa.cert.int.sap.hana.ondemand.com/reco/api/ API_MKT_RECOMMENDATION_SRV/SendProductClickThrough ?CommunicationMedium='EMAIL' &SourceObjectId='mySourceObjectId' &SourceObjectType='mySourceObjectType' &itemID='myItemId' &ItemType='SAP_PRODUCT' &_L54AD1F204_='c2NlbmFyaW89UkVDTyZ0ZW5hbnQ9bXkzMDA0NzAuczRoYW5hLm9uZGVtYW5kLmN vbSZyZWNvX3NjZW5hcmlvPUFMTE9GRkVSUw==' &_K13_=1 &_V_=2 &_K14_='1f18e01b8c3ceac1bf6669203d4f60a5a137cc2142ce01165b8297b62400c9f9' Example of Response Sample Code <?xml version='1.0' encoding='utf-8'?> <SendProductClickThrough xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">true </SendProductClickThrough> Send Offer Click-Throughs HTTP Method Function Import GET SendOfferClickThrough Send interactions that occur between consumers and the offers that are recommended. 936 PUBLIC Integration Guide Integration APIs URL https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ SendOfferClickThrough Request Parameters Field MarketingOffer Mandatory Yes Data Type String MarketingOfferCon Yes tent ExternalOffer No ExternalOfferOrig in Only when ExternalOffer is provided. Coupon No UserId No String String String String String UserType Only when UserId is provided or when Secure User ID check box is checked in Recommendation Scenarios app. String CommunicationMedi Yes um String SourceObjectId Yes String SourceObjectType Yes String Max. Length 10 5 60 30 32 71 50 Description The comma-separated offer IDs to be passed to the recommenda tion scenario. The Marketing Offer Content ID External Offer ID External Offer Origin Marketing Coupon ID The user ID, depending on the specified user type. This parameter is ig nored if the Secure User ID checkbox is checked in the custom Recommendation Scenarios app. The user facet, as de fined in SAP Marketing Cloud. 20 The Communication Medium configured for the recommendation scenario in SAP Mar keting Cloud. 50 The ID of the object that triggered the in teraction. For example, a session or sales or der ID. 30 A custom defined string that describes the type of object passed as the SourceObjectId. Integration Guide Integration APIs PUBLIC 937 Field SourceSystemId Mandatory No Data Type String SourceSystemType Required with SourceSystemId String Max. Length 255 20 Description The ID of the system that is receiving the recommendations, and providing interaction data. For example, a commerce webshop (www.xyz.com). The type of system that is receiving the recommendations and providing interaction data. For example, SAP _Commerce. Example of Request Sample Code https://[Recommendation Scenario URL]/api/API_MKT_RECOMMENDATION_SRV/ SendOfferClickThrough ?CommunicationMedium='EMAIL' &SourceObjectId='mySourceObjectId' &SourceObjectType='mySourceObjectType' &MarketingOffer='32' &MarketingOfferContent='00001' &_L54AD1F204_='c2NlbmFyaW89UkVDTyZ0ZW5hbnQ9bXkzMDA0NzAuczRoYW5hLm9uZGVtYW5kLmN vbSZyZWNvX3NjZW5hcmlvPUFMTE9GRkVSUw==' &_K13_=1 &_V_=2 &_K14_='1f18e01b8c3ceac1bf6669203d4f60a5a137cc2142ce01165b8297b62400c9f9' Example of Response Sample Code <?xml version='1.0' encoding='utf-8'?> <SendOfferClickThrough xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">true </SendOfferClickThrough> 938 PUBLIC Integration Guide Integration APIs 5.6.2 Recommendations The PROD_RECO_RUNTIME_SRV OData service enables customer channels to receive recommendations generated by Recommendation. Prerequisites You have assigned the Marketing - Recommendation Integration communication scenario to your communication user in Maintain Communication Users. You have setup the communication system by doing the following: 1. From the SAP Fiori launchpad, choose Communication Management Communication Systems . 2. Create a communication system, and enter an ID and a system name. 3. Under Technical Data, enter the Host Name of the SAP Cloud Integration system to be connected. 4. Choose Save and return back to the SAP Fiori launchpad. You have setup the communication arrangement by doing the following: 1. From the SAP Fiori launchpad, choose the Communication Arrangements app. 2. Create a communication arrangement for the scenario SAP_COM_0019 (Marketing - Recommendation Integration), and enter an arrangement name. 3. In the Communication Arrangement for Marketing - Recommendation Integration, choose the communication system that you created earlier. 4. Under Inbound Communication, enter your communication user name, and choose an authentication method. 5. Under Inbound Services, the system provides the relevant services from the communication scenario. 6. Choose Save and return back to the SAP Fiori launchpad. To receive the recommendations, call the service using the deep insert functionality of OData. For more information about the deep insert functionality of OData, see https://help.sap.com/viewer/ product/SAP_GATEWAY/2.0/en-US. Choose Developer's Guide OData Channel Advanced Features Deep Insert . Details of Service Entity Root URL: https://<Server>:<Port>/sap/opu/odata/sap/PROD_RECO_RUNTIME_SRV/ RecommendationScenarios Request Mode: POST Entity Data Model: RecommendationScenarios The nested structure of the entities that can be navigated to from the RecommendationScenarios entity are as follows: RecommendationScenarios Scenarios Integration Guide Integration APIs PUBLIC 939 LeadingObjects BasketObjects ContextParams ScenarioHashes ResultObjects RecommendationScenario Entity Parameters The following table contains the parameters of the RecommendationScenario entity: Property Description Edm Core Type UserId The ID of the user who performs the in teraction, for exam ple, customer ID or contact ID. Edm.String UserType The type of user who performs the interac tion, for example, SAP Commerce Con sumer or SAP Mar keting Interaction Contact. Edm.String ExternalTracking A flag that implies ex ternal tracking of im pressions using the PostImpressions function import (Op tional). Edm.Boolean Max Length 50 20 1 Scenario Entity Parameters The following table contains the parameters of the Scenario entity: Key TRUE TRUE FALSE Property ScenarioId Description Edm Core Type The scenario ID rep resents a model type and related usage in formation, for exam ple, promotion model type and user type. Edm.String Max Length 50 Key TRUE 940 PUBLIC Integration Guide Integration APIs Property HashId Description Edm Core Type A hash associated to Edm.String a specific user. The hash accelerates re trieving recommen dations from the cache of an optimized algorithm. Max Length 32 Key FALSE Note You can use the ProductRecoScenario entity to enable your customer channel to choose ScenarioId from a value help. For more information, see Value Help Enabling Entities [page 952]. LeadingObject Entity Parameters The following table contains the parameters of the LeadingObject entity: Property Description Edm Core Type LeadingObjectId The ID of the leading object, for example, material number. Edm.String LeadingObjectTyp e A recommendation data source type that is defined to an ITEM data source class, for example, SAP Commerce Product. Edm.String Max Length 50 Key TRUE 30 TRUE Note You can use the ItemSourceTypes entity to enable your customer channel to choose LeadingObjectType from a value help. For more information, see Value Help Enabling Entities [page 952]. BasketObject Entity Parameters The following table contains the parameters of the BasketObjectid entity: Property BasketObjectId Description Edm Core Type The ID of the leading object, for example, material number. Edm.String Max Length 50 Key TRUE Integration Guide Integration APIs PUBLIC 941 Property Description Edm Core Type BasketObjectType A recommendation data source type that is defined to an ITEM data source class, for example, SAP Commerce Product. Edm.String Max Length 30 Key TRUE Note You can use the ItemSourceTypes entity to enable your customer channel to choose BasketObjectType from a value help. For more information, see Value Help Enabling Entities [page 952]. ContextParam Entity Parameters The following table contains the parameters of the ContextParam entity: Property ContextId ContextParamId Value ValueType Description Edm Core Type The prefilter parame Edm.Int32 ter ID. The parent prefilter parameter ID. Edm.Int32 The value of the pre Edm.String filter parameter. The value type of the Edm.String prefilter parameter. Max Length n.a. n.a. 100 32 ScenarioHash Entity Parameters The following table contains the parameters of the ScenarioHashes entity: Key TRUE FALSE FALSE FALSE Property ScenarioId HashID Description Edm Core Type The recommendation Edm.String scenario ID. A hash returned by the system that is as sociated to a specific user. The hash accel erates retrieving rec ommendations from the cache of an opti mized algorithm. Edm.String Max Length 50 32 Key TRUE TRUE 942 PUBLIC Integration Guide Integration APIs Property ExpiresOn ResultScope Description Edm Core Type Expiry date of HashID. Edm.DateTime The scope of the re sult. For example, Ge neric, Restricted, or Personalized. Edm.String Max Length 1 ResultObject Entity Parameters The following table contains the parameters of the ResultObject entity: Property Description Edm Core Max Length Type ScenarioId The recommendation scenario ID. Edm.String 50 ResultObjectType A recommendation data source type that is defined to an ITEM data source class. For example, SAP Commerce Product. Edm.String 30 Note The ResultObjectType (Recom mendation Type) parameter is defined in the Recommendation Model Types app. The Recommendation Type re flects either offers or the products contained in the system receiving the recommendations. Example To enable an SAP Commerce Web shop to receive recommendations; SAP Commerce Product is defined as the Recommendation Type. Only Rec ommendation objects of type SAP Commerce Product will be returned by the API. ResultObjectId The ID of the result object, for example, material number. ResultObjectScor The score of the result object. e Edm.String 50 Edm.Deci 10.5 mal PostImpressions Function Import Parameters Key FALSE FALSE Key TRUE TRUE TRUE FALSE Integration Guide Integration APIs PUBLIC 943 The following table contains the parameters of the PostImpressions function import: Property ScenarioId TimeStamp ImpressionCount ItemCount Description Edm Core Type The recommendation sce Edm.String nario ID. The timestamp of the im pression. Edm.DateTimeOffset The total number of im pressions performed. Edm.Int16 The total number of Item recommended. Edm.Int16 Max Length 50 30 If the ExternalTracking parameter in the RecommendationScenario entity is set to TRUE, as it is in the HTTP post request example, SAP Marketing Cloud does not count the impressions for the recommendation scenario that is being solicited. To keep the number of impressions in SAP Marketing Cloud accurate, it is necessary for the external system to convey the impression count. To do so, an additional separate call must be made to increase the impression count. For example, if the scenario INT_TEST returns 3 items that were consumed once; the additional call would contain the following: https://[sap -marketing-server]/sap/opu/odata/sap/PROD_RECO_RUNTIME_SRV/ PostImpressions?ScenarioId=' INT_TEST'&TimeStamp=datetimeoffset'2016-12-03T12:45:29Z'&ImpressionCount=1&ItemCoun t=3&saml2=disabled JSON Examples HTTP Post Request Using Deep Insert Functionality of OData in JSON Encoding { "UserId" : "40F2E9306E391ED59BDE581AFE71F329 ", "UserType" : "COOKIE_ID", "ExternalTracking" : true, "Scenarios" : [{ "ScenarioId" : "INT_TEST", "HashId" : "D33DD1F71615D50334FB2F1043365430", "LeadingObjects" : [{ "LeadingObjectType" : "SAP_ERP_MATNR", "LeadingObjectId" : "M-01" }], "BasketObjects" : [{ "BasketObjectType" : "SAP_ERP_MATNR", "BasketObjectId" : "100-100" }] }], "ContextParams" : [], "ScenarioHashes" : [], "ResultObjects" : [] } 944 PUBLIC Integration Guide Integration APIs HTTP Post Response Payload in JSON Encoding { "d": { "__metadata": { "id": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(UserId='',UserType='')" "uri": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(UserId='',UserType='')" "type": "PROD_RECO_RUNTIME_SRV.RecommendationScenario" } "UserId": "" "UserType": "" "ExternalTracking": true, "ScenarioHashes": { "results": [ { "__metadata": { "id": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ScenarioHashes('SAP_TOP_SELLERS_EMAIL_CAMPAIGN')", "uri": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ScenarioHashes('SAP_TOP_SELLERS_EMAIL_CAMPAIGN')", "type": "PROD_RECO_RUNTIME_SRV.ScenarioHash" }, "ScenarioId": "SAP_TOP_SELLERS_EMAIL_CAMPAIGN" "HashId": "D33DD1F71615D50334FB2F1043365429", "ExpiresOn": "/Date(1478180969524)/", "ResultScope": "G" }, ] }, "ResultObjects": { "results": [3] 0: { "__metadata": "__metadata":{ "id": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='INT_TEST',ResultObjectType='SAP_ERP_MATNR',ResultObjectI d='100-100')" "uri": "https://[sap\f -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='INT_TEST',ResultObjectType='SAP_ERP_MATNR',ResultObjectI d='100-100')" "type": "PROD_RECO_RUNTIME_SRV.ResultObject" } "ScenarioId": "INT_TEST" "ResultObjectType": "SAP_ERP_MATNR" "ResultObjectId": "100-100" "ResultObjectScore": "1.00000" } 1: { "__metadata": { "id": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='INT_TEST',ResultObjectType='SAP_ERP_MATNR',ResultObjectI d='P-102')" "uri": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ Integration Guide Integration APIs PUBLIC 945 ResultObject(ScenarioId='INT_TEST',ResultObjectType='SAP_ERP_MATNR',ResultObjectI d='P-102')" "type": "PROD_RECO_RUNTIME_SRV.ResultObject" } "ScenarioId": "INT_TEST" "ResultObjectType": "SAP_ERP_MATNR" "ResultObjectId": "P-102" "ResultObjectScore": "0.01906" } 2: { "__metadata": { "id": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='INT_TEST',ResultObjectType='SAP_ERP_MATNR',ResultObjectI d='P-100')" "uri": "https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='INT_TEST',ResultObjectType='SAP_ERP_MATNR',ResultObjectI d='P-100')" "type": "PROD_RECO_RUNTIME_SRV.ResultObject" } "ScenarioId": "INT_TEST" "ResultObjectType": "SAP_ERP_MATNR" "ResultObjectId": "P-100" "ResultObjectScore": "0.00554" } } } } XML Examples HTTP Post Request Payload in XML Encoding <?xml version="1.0" encoding="utf-8" standalone="yes"?> <entry xml:base="https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/" xmlns:m="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/ 2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns="http://www.w3.org/2005/Atom"> <id>https://[sap -marketing-server]/sap/opu/odata/sap/PROD_RECO_RUNTIME_SRV/ RecommendationScenarios(0)</id> <title type="text">RecommendationScenarios</title> <link rel="self" href="RecommendationScenarios" title="RecommendationScenarios(0)"/> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ Scenarios" type="application/atom+xml;type=feed" title="Scenarios" href="RecommendationScenarios(0)/Scenarios"> <m:inline> <feed> <title type="text">Scenarios</title> <id>https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(0)/Scenarios</id> <link rel="self" title="Scenarios" href="RecommendationScenarios(0)/Scenarios" /> <entry> 946 PUBLIC Integration Guide Integration APIs <id>https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/Scenarios(0)</id> <title type="text">Scenarios</title> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/ related/Scenarios" type="application/atom+xml;type=entry" title="Scenarios" href="RecommendationScenarios(0)/ Scenarios"/> <category term="PROD_RECO_RUNTIME_SRV.Scenario" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> <content type="application/xml"> <m:properties> <d:ScenarioId>[Scenario ID]</d:ScenarioId> <d:HashId></d:HashId> </m:properties> </content> </entry> </feed> </m:inline> </link> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ ScenarioHashes" type="application/atom+xml;type=feed" title="ScenarioHashes" href="RecommendationScenarios(0)/ScenarioHashes"> <m:inline> <feed> <title type="text">Scenarios</title> <id>https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(0)/ScenarioHashes</id> <link rel="self" title="ScenarioHashes" href="RecommendationScenarios(0)/ScenarioHashes" /> <entry> <id>https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ScenarioHashes(0)</id> <title type="text">ScenarioHashes</title> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/ related/ScenarioHashes" type="application/atom+xml;type=entry" title="ScenarioHashes" href="RecommendationScenarios(0)/ ScenarioHashes"/> <category term="PROD_RECO_RUNTIME_SRV.ScenarioHashes" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> <content type="application/xml"> <m:properties> </m:properties> </content> </entry> </feed> </m:inline> </link> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ ResultObjects" type="application/atom+xml;type=feed" title="ResultObjects" href="RecommendationScenarios(0)/ResultObjects"> <m:inline> <feed> <title type="text">ResultObjects</title> <id>https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(0)/ResultObjects</id> <link rel="self" title="ResultObjects" href="RecommendationScenarios(0)/ResultObjects" /> <entry> Integration Guide Integration APIs PUBLIC 947 <id>https://[sap -marketing-server]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ResultObjects(0)</id> <title type="text">ResultObjects</title> <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/ related/ResultObjects" type="application/atom+xml;type=entry" title="ResultObjects" href="RecommendationScenarios(0)/ ResultObjects"/> <category term="PROD_RECO_RUNTIME_SRV.ResultObjects" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> <content type="application/xml"> <m:properties> </m:properties> </content> </entry> </feed> </m:inline> </link> <category term="PROD_RECO_RUNTIME_SRV.RecommendationScenario" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <content type="application/xml"> <m:properties> <d:UserId m:type="Edm.String"></d:UserId> <d:ExternalTracking m:type="Edm.Boolean">false</ d:ExternalTracking> </m:properties> </content> </entry> HTTP Post Response Payload in XML Encoding <?xml version="1.0" encoding="utf-8"?> <entry xml:base="https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/" xmlns="http://www.w3.org/2005/Atom" xmlns:m="http:// schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http:// schemas.microsoft.com/ado/2007/08/dataservices"> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(UserId='',UserType='')</id> <title type="text">RecommendationScenarios(UserId='',UserType='')</title> <updated>2019-05-27T14:51:16Z</updated> <category term="PROD_RECO_RUNTIME_SRV.RecommendationScenario" scheme="http:// schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="RecommendationScenarios(UserId='',UserType='')" rel="self" title="RecommendationScenario"/> <link href="RecommendationScenarios(UserId='',UserType='')/ScenarioHashes" rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ ScenarioHashes" type="application/atom+xml;type=feed" title="ScenarioHashes"> <m:inline> <feed xml:base="https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/ odata/sap/PROD_RECO_RUNTIME_SRV/"> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(UserId='',UserType='')/ ScenarioHashes</id> <title type="text">ScenarioHashes</title> <updated>2019-05-27T14:51:16Z</updated> <author> <name/> </author> <link href="RecommendationScenarios(UserId='',UserType='')/ ScenarioHashes" rel="self" title="ScenarioHashes"/> <entry> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ScenarioHashes('SAMPLE_TOPN_SCENARIO')</id> 948 PUBLIC Integration Guide Integration APIs <title type="text">ScenarioHashes('SAMPLE_TOPN_SCENARIO')</ title> <updated>2019-05-27T14:51:16Z</updated> <category term="PROD_RECO_RUNTIME_SRV.ScenarioHash" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ScenarioHashes('SAMPLE_TOPN_SCENARIO')" rel="self" title="ScenarioHash"/> <content type="application/xml"> <m:properties> <d:ScenarioId>SAMPLE_TOPN_SCENARIO</d:ScenarioId> <d:HashId>85075A5D2C02E7FEAC9AE8090C798F95</d:HashId> <d:ExpiresOn>2019-05-28T08:40:44.1074560</ d:ExpiresOn> <d:ResultScope>G</d:ResultScope> </m:properties> </content> </entry> </feed> </m:inline> </link> <link href="RecommendationScenarios(UserId='',UserType='')/Scenarios" rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Scenarios" type="application/atom+xml;type=feed" title="Scenarios"> <m:inline> <feed xml:base="https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/ odata/sap/PROD_RECO_RUNTIME_SRV/"> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(UserId='',UserType='')/ Scenarios</id> <title type="text">Scenarios</title> <updated>2019-05-27T14:51:16Z</updated> <author> <name/> </author> <link href="RecommendationScenarios(UserId='',UserType='')/ Scenarios" rel="self" title="Scenarios"/> </feed> </m:inline> </link> <link href="RecommendationScenarios(UserId='',UserType='')/ContextParams" rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ ContextParams" type="application/atom+xml;type=feed" title="ContextParams"/> <link href="RecommendationScenarios(UserId='',UserType='')/ResultObjects" rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ ResultObjects" type="application/atom+xml;type=feed" title="ResultObjects"> <m:inline> <feed xml:base="https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/ odata/sap/PROD_RECO_RUNTIME_SRV/"> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/RecommendationScenarios(UserId='',UserType='')/ ResultObjects</id> <title type="text">ResultObject</title> <updated>2019-05-27T14:51:16Z</updated> <author> <name/> </author> <link href="RecommendationScenarios(UserId='',UserType='')/ ResultObjects" rel="self" title="ResultObject"/> <entry> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS_PRODU CT',ResultObjectId='01_TTPRODW2')</id> <title type="text">ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_ HYBRIS_PRODUCT',ResultObjectId='01_TTPRODW2')</title> <updated>2019-05-27T14:51:16Z</updated> Integration Guide Integration APIs PUBLIC 949 <category term="PROD_RECO_RUNTIME_SRV.ResultObject" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS _PRODUCT',ResultObjectId='01_TTPRODW2')" rel="self" title="ResultObject"/> <content type="application/xml"> <m:properties> <d:ScenarioId>SAMPLE_TOPN_SCENARIO</d:ScenarioId> <d:ResultObjectType>SAP_HYBRIS_PRODUCT</ d:ResultObjectType> <d:ResultObjectId>01_TTPRODW2</d:ResultObjectId> <d:ResultObjectScore>0.82353</d:ResultObjectScore> </m:properties> </content> </entry> <entry> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS_PRODU CT',ResultObjectId='01_TTACPRODW2')</id> <title type="text">ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_ HYBRIS_PRODUCT',ResultObjectId='01_TTACPRODW2')</title> <updated>2019-05-27T14:51:16Z</updated> <category term="PROD_RECO_RUNTIME_SRV.ResultObject" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS _PRODUCT',ResultObjectId='01_TTACPRODW2')" rel="self" title="ResultObject"/> <content type="application/xml"> <m:properties> <d:ScenarioId>SAMPLE_TOPN_SCENARIO</d:ScenarioId> <d:ResultObjectType>SAP_HYBRIS_PRODUCT</ d:ResultObjectType> <d:ResultObjectId>01_TTACPRODW2</d:ResultObjectId> <d:ResultObjectScore>0.41176</d:ResultObjectScore> </m:properties> </content> </entry> <entry> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS_PRODU CT',ResultObjectId='02_TTACPRODW2')</id> <title type="text">ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_ HYBRIS_PRODUCT',ResultObjectId='02_TTACPRODW2')</title> <updated>2019-05-27T14:51:16Z</updated> <category term="PROD_RECO_RUNTIME_SRV.ResultObject" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS _PRODUCT',ResultObjectId='02_TTACPRODW2')" rel="self" title="ResultObject"/> <content type="application/xml"> <m:properties> <d:ScenarioId>SAMPLE_TOPN_SCENARIO</d:ScenarioId> <d:ResultObjectType>SAP_HYBRIS_PRODUCT</ d:ResultObjectType> <d:ResultObjectId>02_TTACPRODW2</d:ResultObjectId> <d:ResultObjectScore>0.41176</d:ResultObjectScore> </m:properties> </content> </entry> <entry> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS_PRODU CT',ResultObjectId='07_TTACPRODW2')</id> 950 PUBLIC Integration Guide Integration APIs <title type="text">ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_ HYBRIS_PRODUCT',ResultObjectId='07_TTACPRODW2')</title> <updated>2019-05-27T14:51:16Z</updated> <category term="PROD_RECO_RUNTIME_SRV.ResultObject" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS _PRODUCT',ResultObjectId='07_TTACPRODW2')" rel="self" title="ResultObject"/> <content type="application/xml"> <m:properties> <d:ScenarioId>SAMPLE_TOPN_SCENARIO</d:ScenarioId> <d:ResultObjectType>SAP_HYBRIS_PRODUCT</ d:ResultObjectType> <d:ResultObjectId>07_TTACPRODW2</d:ResultObjectId> <d:ResultObjectScore>0.41176</d:ResultObjectScore> </m:properties> </content> </entry> <entry> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS_PRODU CT',ResultObjectId='03_TTPRODW2')</id> <title type="text">ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_ HYBRIS_PRODUCT',ResultObjectId='03_TTPRODW2')</title> <updated>2019-05-27T14:51:16Z</updated> <category term="PROD_RECO_RUNTIME_SRV.ResultObject" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS _PRODUCT',ResultObjectId='03_TTPRODW2')" rel="self" title="ResultObject"/> <content type="application/xml"> <m:properties> <d:ScenarioId>SAMPLE_TOPN_SCENARIO</d:ScenarioId> <d:ResultObjectType>SAP_HYBRIS_PRODUCT</ d:ResultObjectType> <d:ResultObjectId>03_TTPRODW2</d:ResultObjectId> <d:ResultObjectScore>0.41176</d:ResultObjectScore> </m:properties> </content> </entry> <entry> <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS_PRODU CT',ResultObjectId='02_TTPRODW2')</id> <title type="text">ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_ HYBRIS_PRODUCT',ResultObjectId='02_TTPRODW2')</title> <updated>2019-05-27T14:51:16Z</updated> <category term="PROD_RECO_RUNTIME_SRV.ResultObject" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS _PRODUCT',ResultObjectId='02_TTPRODW2')" rel="self" title="ResultObject"/> <content type="application/xml"> <m:properties> <d:ScenarioId>SAMPLE_TOPN_SCENARIO</d:ScenarioId> <d:ResultObjectType>SAP_HYBRIS_PRODUCT</ d:ResultObjectType> <d:ResultObjectId>02_TTPRODW2</d:ResultObjectId> <d:ResultObjectScore>0.41176</d:ResultObjectScore> </m:properties> </content> </entry> <entry> Integration Guide Integration APIs PUBLIC 951 <id>https://[SAP_MARKETING_CLOUD_SYSTEM]/sap/opu/odata/sap/ PROD_RECO_RUNTIME_SRV/ ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS_PRODU CT',ResultObjectId='07_TTPRODW2')</id> <title type="text">ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_ HYBRIS_PRODUCT',ResultObjectId='07_TTPRODW2')</title> <updated>2019-05-27T14:51:16Z</updated> <category term="PROD_RECO_RUNTIME_SRV.ResultObject" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ResultObject(ScenarioId='SAMPLE_TOPN_SCENARIO',ResultObjectType='SAP_HYBRIS _PRODUCT',ResultObjectId='07_TTPRODW2')" rel="self" title="ResultObject"/> <content type="application/xml"> <m:properties> <d:ScenarioId>SAMPLE_TOPN_SCENARIO</d:ScenarioId> <d:ResultObjectType>SAP_HYBRIS_PRODUCT</ d:ResultObjectType> <d:ResultObjectId>07_TTPRODW2</d:ResultObjectId> <d:ResultObjectScore>0.41176</d:ResultObjectScore> </m:properties> </content> </entry> </feed> </m:inline> </link> <content type="application/xml"> <m:properties> <d:UserId/> <d:UserType/> <d:ExternalTracking>false</d:ExternalTracking> </m:properties> </content> </entry> 5.6.2.1 Value Help Enabling Entities Entities that enable you to choose recommendation scenario and item source type parameters from a value help. The PROD_RECO_RUNTIME_SRV OData service enables customer channels to receive recommendations generated by Recommendation. The RecommendatioRecoScenarios and ItemSourceTypes entities enable customer channels to choose ScenarioID, LeadingObjectType, or BasketObjectType parameters from a value help. Prerequisites You have assigned the Marketing - Recommendation Integration communication scenario to your communication user in Maintain Communication Users. 952 PUBLIC Integration Guide Integration APIs ProductRecoScenarios Entity Root URL: https://<Server>:<Port>/sap/opu/odata/sap/PROD_RECO_RUNTIME_SRV/ ProductRecoScenarios Request Mode: GET ProductRecoScenario Entity Parameters The following table contains the parameters of the ProductRecoScenario entity: Property Description Edm Core Type ScenarioId The ID of the sce nario. Edm.String ScenarioDescript The description of the Edm.String ion scenario. Language The language of the Edm.String scenario description. Max Length 50 255 30 Key TRUE FALSE FALSE ItemSourceTypes Entity Root URL: https://<Server>:<Port>/sap/opu/odata/sap/PROD_RECO_RUNTIME_SRV/ ItemSourceTypes Request Mode: GET ItemSourceTypes Entity Parameters The following table contains the parameters of the ItemSourceTypes entity: Property Description Edm Core Type ItemSourceId The ID of the item source. Edm.String ItemSourceTypeDe The description of the Edm.String scription item source type. ItemSourceObject Type The object type of the Edm.String item source. Max Length 2 255 30 Key TRUE FALSE FALSE Integration Guide Integration APIs PUBLIC 953 5.6.3 External Recommendations Use the public OData API API_MKT_EXTERNAL_RECMDN_SRV to upload (import) recommendations from external sources. Overview This OData API provides functionality to import product and offer recommendations that have been calculated using external tools. External recommendations can be used in the recommendation processes for products and offers. OData Version Root URI Service Metadata URI Authorizations Communication Scenario ID Component for Incidents 2.0 https://<server>:<port>/sap/opu/odata/sap/ API_MKT_EXTERNAL_RECMDN_SRV https://<server>:<port>/sap/opu/odata/sap/ API_MKT_EXTERNAL_RECMDN_SRV/$metadata A copy of the following business catalog role is required: SAP_COM_CSR_0300. Read-only access is provided using the SAP_BCR_CEC_MKT_API_EXTRECO_PC business catalog role. SAP_COM_0300 CEC-MKT-PRI (Recommendation) Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Support of OData Features Feature $top query option Support When performing GET calls on entity sets for this API, the $top query option is mandatory to restrict resource consumption in the system. 5.6.3.1 Basic Concepts The public API_MKT_EXTERNAL_RECMDN_SRV OData API upload (import) recommendations from external sources. 954 PUBLIC Integration Guide Integration APIs Processing Information The API can perform all supported operations either as a single operation or as a batch request. 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. Note There are no eligibility or validity checks performed on offers. Offer content is determined using the following value help entities of the CUAN_OFFER_DISCOVERY_SRV API: Communication Medium Content Type Content Position Marketing Area Languages Coupon For more information, see Discover Offers [page 1008]. Error Messages By default, data processing for external recommendation is synchronous and an OK response or error messages are returned as soon as data processing finishes. If the OData service isn't accessible, for example due to missing authorization, or because the system isn't available, a corresponding HTTP status code is returned. You can change the default setting to asynchronous with the Sap-Cuan-AsynchronousProcessing property. Using asynchronous processing, an OK response is returned almost immediately. If data uploads contain severe errors, such as parse or format errors, they produce an error message and the data is placed in a staging area, where it's then further processed. To view the processing status and check for errors or success messages when data is processed asynchronously, you must launch the Import Monitor app. If errors occur, you can restart or discard the import in the app. For more information, see Structure of OData Service API_MKT_EXTERNAL_RECMDN_SRV [page 956]. Related Information Import Monitor [page 404] External Algorithms Integration Guide Integration APIs PUBLIC 955 5.6.3.2 Structure of OData Service API_MKT_EXTERNAL_RECMDN_SRV This document describes the structure of the Public OData API serviceAPI API_MKT_EXTERNAL_RECMDN_SRV. Be sure to read the Basic Concepts topic before you start. Request Header The request header contains the additional header fields listed in the table. Property Example Sap-cuan- X asynchronousPr ocessing Sap-cuan- HYBRIS SourceSystemId Description Edm Core Type This property ena Edm.Boolean bles uploaded data to be processed asynchronously. For more informa tion, see Basic Concepts [page 954]. This free text field identifies the source system. Edm.String Note This property is only useful if property SapCuanAsynchronou sProcessing is enabled. Max. Length n/a 255 Mandatory No No 956 PUBLIC Integration Guide Integration APIs Property Example Sap-cuanSourceSystemTy pe EXTERNAL Description Edm Core Type This free text field identifies the source system type. Edm.String Note This property is only useful if property SapCuanAsynchronou sProcessing is enabled. Max. Length 20 Mandatory No Entity Data Model Integration Guide Integration APIs PUBLIC 957 Entity Sets The External Recommendations OData API provides the following entity sets: Entity Set ExternalRecommendations ExternalRecmdnVersions RecommendationClusters ContactToRecmdnClstrAssgmts RecmdnClusterItemAssignments RecmdnClusterForLeadingItems Description Path This entity set contains a list of external /ExternalRecommendations recommendation data sets. This entity set contains a list of versions /ExternalRecommenda of an external recommendation data tions(guid'<ExternalRecommendatio set. nUUID >')/ to_ExternalRecmdnVersion This entity set contains a list of clusters of a version of an external recommen dation data set. /ExternalRecmdnVer sions(guid'<ExtRecommendationVer sionUUID>')/ to_Recommenda tionCluster This entity set contains a list of con tacts that are assigned to a recommen dation cluster. /RecommendationClus ters(guid'<RecommendationCluster UUID>')/to_CntctToRecmdnCl strAssgmt This entity set contains a list of ranked recommendation result items (prod ucts, offers). /RecommendationClus ters(guid'<RecommendationCluster UUID>')/to_RecmdnClstrItemAssgmt This entity set contains a list of tuples of recommendation leading items (products, product categories, items of interest, offers) and result items (prod ucts, offers). /RecommendationClus ters(guid'<RecommendationCluster UUID>')/to_RecmdnClstrLeadingItm ExternalRecommendations The ExternalRecommendations entity set represents the header of an external recommendations data set. Its data controls the behavior of the dependent subnodes in the data model. Resource Path: /ExternalRecommendations You can perform the following operations on the ExternalRecommendations entity set: HTTP Method GET Operation URI Get a list of external recommendations. This method supports standard OData parameters, such as $filter, $select, $top, $skip, $count, $inlinecount, $or derby and $expand. / ExternalRecommendations? $top=1 958 PUBLIC Integration Guide Integration APIs HTTP Method POST PATCH Operation Get the details of a specific external recommendation URI / ExternalRecommendations( guid'<ExternalRecommenda tionUUID>') Create an external recommendation data set Update an external recommendation data set /ExternalRecommendations / ExternalRecommendations( guid'<ExternalRecommenda tionUUID>') More information about the fields in the ExternalRecommendations entity set: The field ExternalRecommendation is a 32 character free-text field that identifies the data set. The field ExternalRecommendationName is a 120 character free-text field that describes the data set. The field ExternalRecommendationType is a 2 character field that must use the values'01' or `02'. This field controls whether the data set contains a simple ranked list of recommendation result items (see the entity set RecmdnClusterItemAssignments) or a list of ranked leading and result item tuples (see the entity set RecmdnClusterForLeadingItems). The field RecommendationResultItemType controls whether the recommendation result items are products (value `13') or offer content items (value `15'). Offers aren't subject to any eligibility or validity checks. Note During the import process of external recommendations, enclose multiple changes within a single changeset. Doing so ensures a higher throughput in the import process. ExternalRecmdnVersions The ExternalRecmdnVersions entity set represents a version of an external recommendations data set. Several versions of each data set can be uploaded to the system in parallel. The recommendation engine determines which version is used at runtime based on the value of the field ValidityStartDateTime. This timestamp controls the point in time at which the data within a version becomes active. The recommendation engine uses the version for which the value of ValidityStartDateTime is in the past and closest to the current point in time. If two versions have the same value for ValidityStartDateTime, the version with the most recent LastChangedDateTime timestamp is used at runtime. The IsDeleted field indicates that an internal cleanup job deleted an obsolete data set version. The following criteria must be met for the data set to be deemed obsolete and to enable the internal job to delete the version: The version isn't active and won't be active later. For example, another version with a more recent ValidityStartDateTime is active. The version isn't used by a recommendation model that has a status of Active or Activation Pending. For more information, see Understanding Model Statuses. Resource Path: /ExternalRecmdnVersions Integration Guide Integration APIs PUBLIC 959 You can perform the following operations on the ExternalRecmdnVersions entity set: HTTP Method GET Operation URI Get a list of external recommendation versions for an external recommenda tion. This method supports standard OData parameters such as $filter, $se lect, $top, $skip, $count, $inlinecount, $orderby and $expand. / ExternalRecommendations( guid'<ExternalRecommenda tionUUID>')/ to_ExternalRecmdnVersion Get the details of a specific external recommendation version / ExternalRecmdnVersions(g uid'<ExtRecommendationVe rsionUUID>') POST Create an external recommendation version for an external recommenda tion data set / ExternalRecommendations( guid'<ExternalRecommenda tionUUID>')/ to_ExternalRecmdnVersion PATCH Update an external recommendation version / ExternalRecmdnVersions(g uid'<ExtRecommendationVe rsionUUID>') RecommendationClusters The RecommendationClusters entity set represents a cluster of recommendation data in a version of an external recommendation data set. A cluster in the recommendation contains a list to contacts assigned to this cluster (entity set ContactToRecmdnClstrAssgmts), and either a list of ranked recommendation items (entity set RecmdnClusterItemAssignments) or a list of ranked leading and result item tuples (entity set RecmdnClusterForLeadingItems). See also the field ExternalRecommendationType in the ExternalRecommendations entity type. Resource Path: /RecommendationClusters You can perform the following operations on the RecommendationClusters entity set: HTTP Method GET Operation URI Get a list of recommendation clusters for a recommendation version. This method supports standard OData pa rameters such as $filter, $select, $top, $skip, $count, $inlinecount, $orderby and $expand. / ExternalRecmdnVersions(g uid'<ExtRecommendationVe rsionUUID>')/ to_RecommendationCluster 960 PUBLIC Integration Guide Integration APIs HTTP Method POST PATCH DELETE Operation URI Get the details of a specific recommen dation cluster / RecommendationClusters(g uid'<RecommendationClust erUUID>') Create a recommendation cluster / ExternalRecmdnVersions(g uid'<ExtRecommendationVe rsionUUID>')/ to_RecommendationCluster Update a recommendation cluster / RecommendationClusters(g uid'<RecommendationClust erUUID>') Delete a recommendation cluster / RecommendationClusters(g uid'<RecommendationClust erUUID>') One cluster in the list of clusters of a version can be a fallback cluster. If the contact for which the recommendation was called was either anonymous or couldn't be found in any other cluster, the recommendation runtime uses the recommendation items from this cluster. Only one fallback cluster is allowed. It's identified by the IsFallbackRecmdnCluster field with the value true. Fallback clusters don't need any contacts in the ContactToRecmdnClstrAssgmts entity set. ContactToRecmdnClstrAssgmts The ContactToRecmdnClstrAssgmts entity set represents the assignment of interaction contacts to a recommendation cluster. Resource Path: /ContactToRecmdnClstrAssgmts You can perform the following operations on the ContactToRecmdnClstrAssgmtsentity entity set: HTTP Method GET Operation URI Get a list of interaction contacts in a recommendation cluster. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, $orderby and $expand. / RecommendationClusters(g uid'<RecommendationClust erUUID>'/ to_CntctToRecmdnClstrAss gmt Get the details of a specific contact to cluster assignment / ContactToRecmdnClstrAssg mts(guid'<CntctToRecmdnC lstrAssgmtUUID>') Integration Guide Integration APIs PUBLIC 961 HTTP Method POST DELETE Operation URI Create a contact to cluster assignment / RecommendationClusters(g uid'<RecommendationClust erUUID>'/ to_CntctToRecmdnClstrAss gmt Delete a contact to cluster assignment / ContactToRecmdnClstrAssg mts(guid'<CntctToRecmdnC lstrAssgmtUUID>') When creating a ContactToRecmdnClstrAssgmts entity using a POST call, the interaction contact is provided using the fields InteractionContactId and InteractionContactOrigin. The system determines the corresponding InteractionContactUUID automatically. The field RecommendationCluster is inherited from the RecommendationClusters entity. The field RecmdnInteractionContactType is determined internally. RecmdnClusterItemAssignments The RecmdnClusterItemAssignments entity set represents the assignment of ranked result items to a recommendation cluster. Resource Path: /RecmdnClusterItemAssignments You can perform the following operations on the RecmdnClusterItemAssignments entity set: HTTP Method GET Operation URI Get a list of recommendation items in a recommendation cluster. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, $orderby and $expand. / RecommendationClusters(g uid'<RecommendationClust erUUID>'/ to_RecmdnClstrItemAssgmt Get the details of a specific recommen dation item to cluster assignment / RecmdnClusterItemAssignm ents(guid'<Recommendatio nItemUUID>') POST Create a recommendation item to clus ter assignment / RecommendationClusters(g uid'<RecommendationClust erUUID>'/ to_RecmdnClstrItemAssgmt 962 PUBLIC Integration Guide Integration APIs HTTP Method DELETE Operation URI Delete a recommendation item to clus ter assignment / RecmdnClusterItemAssignm ents(guid'<Recommendatio nItemUUID>') When creating a recommendation item to cluster assignment using a POST call, the field RecommendationResultItemType is automatically inherited from the corresponding ExternalRecommendations entity. The field RecommendationCluster is inherited from the RecommendationClusters entity. If the RecommendationResultItemType is "13" for products, recommendation result items can be identified using the combination of RecommendationResultItem and RecommendationResultItemOrigin or using RecommendationResultItemUUID. If all values are provided in the POST call, they're cross-checked. If the RecommendationResultItemType is "15" for SAP Marketing Cloud Offer Content, result items are identified using RecommendationResultItemUUID. For more information, see Read Offers [page 1002]. The RecommendationItemScore value must be greater than 0. RecmdnClusterForLeadingItems The RecmdnClusterForLeadingItems entity set represents the assignment of ranked leading and result item tuples to a recommendation cluster. Resource Path: /RecmdnClusterForLeadingItems You can perform the following operations on the RecmdnClusterForLeadingItems entity set: HTTP Method GET Operation URI Get a list of recommendation leading item/result item tuples in a recommen dation cluster. This method supports standard OData parameters such as $filter, $select, $top, $skip, $count, $inlinecount, $orderby and $expand. / RecommendationClusters(g uid'<RecommendationClust erUUID>'/ to_RecmdnClstrLeadingItm Get the details of a specific recommen dation leading item/result item tuple to cluster assignment / RecmdnClusterForLeadingI tems(guid'<Recommendatio nItemUUID>') POST Create a recommendation leading item/result item tuple to cluster assign ment / RecommendationClusters(g uid'<RecommendationClust erUUID>'/ to_RecmdnClstrLeadingItm DELETE Delete a leading item/result item tuple to cluster assignment / RecmdnClusterForLeadingI tems(guid'<Recommendatio nItemUUID>') Integration Guide Integration APIs PUBLIC 963 When creating a recommendation item to cluster assignment using a POST call, the field RecommendationResultItemType is automatically inherited from the corresponding ExternalRecommendations entity. The field RecommendationCluster is inherited from the RecommendationClusters entity. If the RecommendationResultItemType is "13" for products, recommendation result items can be identified using the combination of RecommendationResultItem and RecommendationResultItemOrigin or using RecommendationResultItemUUID. If all values are provided in the POST call, they're cross-checked. If the RecommendationResultItemType is "15" for SAP Marketing Cloud Offer Content, result items are identified using RecommendationResultItemUUID. For more information, see Read Offers [page 1002]. The RecommendationtItemScore value must be greater than 0. The following leading item types are supported: "11" for items of interest The POST call expects RecommendationLeadingItem and/or RecommendationLeadingItemUUID which are checked for correctness and eventually converted into each other. "13" for products The POST call expects RecommendationLeadingItem and RecommendationLeadingItemOrign or RecommendationLeadingItemUUID which are checked for correctness and eventually converted into each other. "15" for SAP Marketing Cloud Offer Content The POST call expects RecommendationLeadingItemUUID which is checked for correctness. "19" for product categories The POST call expects the category UUID in RecommendationLeadingItemUUID or the category ID in RecommendationLeadingItem and hierarchy ID in RecommendationLeadingItemOrigin. General comment on create (POST): The system generates the key for the entities. The POST payload doesn't provide the key. General comment on update (PATCH): Certain fields (for example RecommendationResultItemType in the ExternalRecommendations entity set) can be updated while there are no child entities. As soon as child nodes exist, the fields can no longer be updated, and update requests return an error when trying to update these fields. Entities from the ContactToRecmdnClstrAssgmts, RecmdnClusterItemAssignments, RecmdnClusterForLeadingItems entity sets, can only be created or deleted. The entities can't be updated. General comment on error handling: If errors occur when using the default synchronous data processing, they're directly reported using the response to the OData request. Any errors that occur during create or update operations are also recorded in the application log. The application log object is "Recommendations" (PRI) with the subobject "External Recommendations" (EXT_DATA). A system administrator can analyze entries in the application log in the corresponding SAP Fiori UI. If errors occur when using the asynchronous data processing feature, you must launch the Import Monitor app to view the processing status and check for errors or success messages. If errors occur, you can restart or discard the import using the app. 964 PUBLIC Integration Guide Integration APIs 5.6.3.3 Payload Examples The following are examples of how you can use the External Recommendations API. Example 1 External offer recommendation with one contact, the tuple of a leading product, and an offer (content) result item. The leading product and the offer (content) are identified by their UUIDs. Sample Code { "ExternalRecommendation": "EXTERNAL_OFFER", "ExternalRecommendationName": "External Offer", "ExternalRecommendationType": "02", "RecommendationResultItemType": "15", "to_ExternalRecmdnVersion": [ { "ExtRecmdnExternalVersion": "EXTERNAL_OFFER_V1", "ValidityStartDateTime": "2017-02-12T09:00:00.0000000", "to_RecommendationCluster": [ { "RecommendationCluster": "EXTERNAL_OFFER_C1", "IsFallbackRecmdnCluster": false, "to_CntctToRecmdnClstrAssgmt": [ { "InteractionContactId": "test_user@test.test", "InteractionContactOrigin": "EMAIL" } ], "to_RecmdnClstrLeadingItm": [ { "RecommendationLeadingItemUUID": "2DA602C04DD61C1516006102FF7A1A39", "RecommendationLeadingItemType": "13", "RecommendationResultItemUUID": "941882831C7D1ED88AF4C61864181AE7", "RecommendationItemScore": 1.0 } ] } ] } ] } Integration Guide Integration APIs PUBLIC 965 Example 2 External offer recommendation with one contact, two tuples of leading products, and offer (content) result items. The offer (content) result item is identified by its UUID. The leading product is identified once by its origin and ID, and once by its UUID. Sample Code { "ExternalRecommendation": "EXTERNAL_OFFER", "ExternalRecommendationName": "External Offer", "ExternalRecommendationType": "02", "RecommendationResultItemType": "15", "to_ExternalRecmdnVersion": [ { "ExtRecmdnExternalVersion": "EXTERNAL_OFFER_V1", "ValidityStartDateTime": "2017-02-15T09:00:00.0000000", "to_RecommendationCluster": [ { "RecommendationCluster": "EXTERNAL_OFFER_C1", "IsFallbackRecmdnCluster": false, "to_CntctToRecmdnClstrAssgmt": [ { "InteractionContactId": "test_user@test.test", "InteractionContactOrigin": "EMAIL" } ], "to_RecmdnClstrLeadingItm": [ { "RecommendationLeadingItem": "P-12345", "RecommendationLeadingItemOrign": "SAP_PRODUCT", "RecommendationLeadingItemType": "13", "RecommendationResultItemUUID": "941882831C7D1ED88AF4C61864181AE7", "RecommendationItemScore": 1.0 }, { "RecommendationLeadingItemUUID": "31A602C04DD61C1516006102FF7A1A39", "RecommendationLeadingItemType": "13", "RecommendationResultItemUUID": "941882831C7D1EE888AF07DF4D1A0094", "RecommendationItemScore": 1.0 } ] } ] } ] } 966 PUBLIC Integration Guide Integration APIs Example 3 External offer recommendation without contacts (uses the fallback cluster), two tuples of leading products, and offer (content) result items. The leading products and the offer (content) result item are identified by their UUIDs. Sample Code { "ExternalRecommendation": "EXTERNAL_OFFER", "ExternalRecommendationName": "External Offer", "ExternalRecommendationType": "02", "RecommendationResultItemType": "15", "to_ExternalRecmdnVersion": [ { "ExtRecmdnExternalVersion": "EXTERNAL_OFFER_V1", "ValidityStartDateTime": "2017-02-15T09:00:00.0000000", "to_RecommendationCluster": [ { "RecommendationCluster": "EXTERNAL_OFFER_CFB", "IsFallbackRecmdnCluster": true, "to_RecmdnClstrLeadingItm": [ { "RecommendationLeadingItemUUID": "2DA602C04DD61C1516006102FF7A1A39", "RecommendationLeadingItemType": "13", "RecommendationResultItemUUID": "941882831C7D1ED88AF4C61864181AE7", "RecommendationItemScore": 1.0 }, { "RecommendationLeadingItemUUID": "31A602C04DD61C1516006102FF7A1A39", "RecommendationLeadingItemType": "13", "RecommendationResultItemUUID": "941882831C7D1EE888AF07DF4D1A0094", "RecommendationItemScore": 1.0 } ] } ] } ] } Example 4 External offer recommendation without contact (uses the fallback cluster) and a single offer result item identified by its UUID. Sample Code { "ExternalRecommendation": "EXTERNAL_OFFER", "ExternalRecommendationName": "External Offer", Integration Guide Integration APIs PUBLIC 967 "ExternalRecommendationType": "01", "RecommendationResultItemType": "15", "to_ExternalRecmdnVersion": [ { "ExtRecmdnExternalVersion": "EXTERNAL_OFFER_V1", "ValidityStartDateTime": "2017-11-01T00:00:00.0000000", "to_RecommendationCluster": [ { "RecommendationCluster": "EXTERNAL_OFFER_CFB", "IsFallbackRecmdnCluster": true, "to_RecmdnClstrItemAssgmt": [ { "RecommendationResultItemUUID": "941882831C7D1ED88AF4C61864181AE7", "RecommendationItemScore": 1.0 } ] } ] } ] } Example 5 Same as example 4, but the request is redirected to asyncronous processing. POST https://server:port/sap/opu/odata/sap/API_MKT_EXTERNAL_RECMDN_SRV/ ExternalRecommendations Header Sample Code Content-Type:application/json sap-cuan-asynchronousprocessing: x sap-cuan-sourcesystemid: bat1 sap-cuan-sourcesystemtype: ERP Body Sample Code { "ExternalRecommendation": "EXTERNAL_OFFER", "ExternalRecommendationName": "External Offer", "ExternalRecommendationType": "02", "RecommendationResultItemType": "15", "to_ExternalRecmdnVersion": [ { "ExtRecmdnExternalVersion": "EXTERNAL_OFFER_V1", "ValidityStartDateTime": "2017-02-15T09:00:00.0000000", "to_RecommendationCluster": [ { "RecommendationCluster": "EXTERNAL_OFFER_CFB", "IsFallbackRecmdnCluster": true, 968 PUBLIC Integration Guide Integration APIs "to_RecmdnClstrLeadingItm": [ { "RecommendationLeadingItemUUID": "2DA602C04DD61C1516006102FF7A1A39", "RecommendationLeadingItemType": "13", "RecommendationResultItemUUID": "941882831C7D1ED88AF4C61864181AE7", "RecommendationItemScore": 1.0 }, { "RecommendationLeadingItemUUID": "31A602C04DD61C1516006102FF7A1A39", "RecommendationLeadingItemType": "13", "RecommendationResultItemUUID": "941882831C7D1EE888AF07DF4D1A0094", "RecommendationItemScore": 1.0 } ] } ] } ] } Example 6 A batch request using asynchronous processing. This sample request includes the following: A deletion of a cluster. A deep creation of a cluster. A patch to a leading item node. POST https://server:port/sap/opu/odata/sap/API_MKT_EXTERNAL_RECMDN_SRV/$batch Header Sample Code Content-Type:multipart/mixed; boundary=batchtest Body Sample Code --batchtest Content-Type: multipart/mixed; boundary=changeset_9970-5898-d67d --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary PATCH RecmdnClusterForLeadingItems(guid'6c0b84b7-5523-1ee9-b8a4fa24838b7e95') HTTP/1.1 Content-Type: application/json Content-Length: 168 Integration Guide Integration APIs PUBLIC 969 sap-cuan-asynchronousprocessing: x sap-cuan-sourcesystemid: bat1 sap-cuan-sourcesystemtype: ERP { "RecommendationLeadingItem": "TEAMTD_PRD_06_01", "RecommendationLeadingItemType": "13", "RecommendationLeadingItemOrign": "SAP_HYBRIS_PRODUCT", "RecommendationResultItem": "TEAMTD_PRD_03_02", "RecommendationResultItemType": "13", "RecommendationResultItemOrigin": "SAP_HYBRIS_PRODUCT", "RecommendationItemScore": 9 } --changeset_9970-5898-d67d content-type: application/http content-transfer-encoding: binary DELETE RecommendationClusters(guid'6c0b84b7-5523-1ed8-bf8d-be1ac978dc2d')? saml2=disabled HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en-US DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 Content-Type: application/json Content-Length: 728 sap-cuan-asynchronousprocessing: x sap-cuan-sourcesystemid: bat1 sap-cuan-sourcesystemtype: ERP --changeset_9970-5898-d67d Content-Type: application/http Content-Transfer-Encoding: binary POST ExternalRecmdnVersions(guid'6c0b84b7-5523-1ed8-bf8d-be1ac92e7c2d')/ to_RecommendationCluster?saml2=disabled HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en-US DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 Content-Type: application/json Content-Length: 728 sap-cuan-asynchronousprocessing: x sap-cuan-sourcesystemid: bat1 sap-cuan-sourcesystemtype: ERP { "RecommendationCluster": "100", "IsFallbackRecmdnCluster": false, "to_CntctToRecmdnClstrAssgmt": [ { "InteractionContactId": "0000045000", "InteractionContactOrigin": "SAP_CRM_BUPA" } ], "to_RecmdnClstrItemAssgmt": [ { "RecommendationResultItem": "000000000000001510", "RecommendationResultItemOrigin": "SAP_ERP_MATNR", "RecommendationItemScore": 1 } ] } 970 PUBLIC Integration Guide Integration APIs --changeset_9970-5898-d67d---batchtest-- 5.6.4 Recommendations Interaction Data OData service (PROD_RECO_RUNTIME_SRV) for posting interactions to an SAP HANA database. The PROD_RECO_RUNTIME_SRV OData service enables host systems to post interactions to an SAP HANA database and then consume the information in a recommendation model. An interaction can be any event performed by a consumer on a Web shop. Prerequisites You have assigned the Marketing - Recommendation Integration communication scenario to your communication user in Maintain Communication Users. To post interactions, you must call the service using the deep insert functionality of OData. For more information about the deep insert functionality of OData, see http://www.help.sap.com . Choose Technology SAP Gateway. Choose a release and then Application Help. In SAP Library, choose SAP NetWeaver Gateway Developer Guide OData Channel Advanced Features Deep Insert Details of Service Entity Root URL: https://<Server>:<Port>/sap/opu/odata/sap/PROD_RECO_RUNTIME_SRV/ Interactions Request Mode: POST Entity Data Model: Interaction The following table contains the parameters of the Interaction Entity: Name Is Key Scenario TRUE Id UserId TRUE Edm Core Type Edm.String Max Length Creatable Updata ble Sortable Nullable Filterable Complex Type Name 50 FALSE FALSE FALSE TRUE FALSE n.a. Edm.String 255 FALSE FALSE FALSE FALSE FALSE n.a. Integration Guide Integration APIs PUBLIC 971 Name Is Key Interact TRUE ionType UserType FALSE SourceOb FALSE jectId Time Stamp TRUE Edm Core Type Edm.String Max Length Creatable Updata ble Sortable Nullable Filterable Complex Type Name 20 FALSE FALSE FALSE FALSE FALSE n.a. Edm.String 20 Edm.String 50 FALSE FALSE FALSE FALSE FALSE n.a. FALSE FALSE FALSE TRUE FALSE n.a. Edm.DateTi n.a. meOffset FALSE FALSE FALSE TRUE FALSE n.a. Parameter Descriptions ScenarioId The recommendation scenario ID represents a model type and related usage information, for example, promotion model type and user type. UserId The ID of the user who performs the interaction, for example, customer ID or contact ID. UserType The type of the user who performs the interaction, for example, COOKIE_ID or SAP_ERP_CONTACT. InteractionType The interaction type, for example, click through and conversion. SourceObjectId The ID of the session the user performed the interaction in. TimeStamp The coordinated universal time (UTC) stamp of when the interaction happened. Entity Data Model: InteractionItems The following table contains the parameters of the InteractionItems entity: Name Is Key ItemType TRUE ItemId TRUE ItemNavU FALSE rl Edm Core Type Edm.String Edm.String Edm.String Max Length Creatable Updata ble Sortable Nullable Filterable Complex Type Name 30 FALSE FALSE FALSE TRUE FALSE n.a. 50 FALSE FALSE FALSE FALSE FALSE n.a. 1333 FALSE FALSE FALSE FALSE FALSE n.a. Parameter Descriptions Item_type One of the following standard delivery item types: SAP_CUAN_PRODUCT 972 PUBLIC Integration Guide Integration APIs SAP_HYBRIS_PRODUCT CUAN_PROD_CATEGORY_HIERARCHY ItemId The ID of the item, for example, material number. ItemNavUrl The url to navigate to the item, for example, https://<Server>:<Port>/yacceleratorstorefront/ electronics/en/Open-Catalogue/Cameras/Digital-Cameras/Digital-Compacts/DSC-N1/p/ M-10 Example Payload in JSON Format: { "ScenarioId" : "INT_TEST", "UserType" : "COOKIE_ID", "UserId" : "ccef655202caec49", "InteractionType": "CLICK_THROUGH", "TimeStamp": "2015-11-23T01:00:00Z", "SourceObjectId":"17FE2EA62DB2154594CC1FCEEB58C691", "InteractionItems" : [{ "ItemType" : "SAP_ERP_MATNR", "ItemId" : "M-10", "ItemNavUrl" : "https://localhost:9002/yacceleratorstorefront/electronics/en/ Open-Catalogue/Cameras/Digital-Cameras/Digital-Compacts/DSC-N1/p/M-10" }] } The HTTP post response does not contain any entity. 5.6.5 Import Offers Use the public OData API CUAN_OFFER_IMPORT_SRV to upload (import) offers from external sources. Note The offer import API supports the importation of offers with assigned object references, such as products, marketing locations and coupons. Furthermore, the service supports basic read functionality to read an imported offer when specifying the offer key (consisting of external id and external origin). It is not possible to query all offers or all imported offers with functionality such as search and filtering. For such usecases, please use the Read Offers API [page 1002]. Technically, HTTPS GET operations on entities, such as Offers, ProductAssignments, and TargetGroupAssignments, only return data when providing the fully qualified key. Overview Offer data can be maintained using the corresponding maintenance app in the system, but it can also be imported from other systems using this public OData application programming interface (API). You can use the Integration Guide Integration APIs PUBLIC 973 OData service CUAN_OFFER_IMPORT_SRV to upload (import) external offers and offer content with extensibility, assign dependent objects like marketing locations, products, and product categories and read the offer information. Imported offers are assigned an external reference and origin and initially have the status In Preparation. You cannot change the offer data, but you can, for example, change the contents and the status. The ability to import the offer content entity allows for a complete end-to-end integration without any manual steps in SAP Marketing Cloud. OData Version Root URI Service Metadata URI Authorizations Communication Scenario ID Component for Incidents 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ CUAN_OFFER_IMPORT_SRV/ https://<Server>:<Port>/sap/opu/odata/SAP/ CUAN_OFFER_IMPORT_SRV//$metadata The following business catalog role is required: SAP_COM_CSR_0020 SAP_COM_0020 CEC-MKT-OFM (Offers) Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Support of OData Features Feature Support Query options for value help entities The current implementation of the value help entities sup ports the following query options, which can be passed as query or path parameters: $top and $skip $select $orderby $count and $inlinecount Bulk processing using deep-create on entity ImportHeader The service supports both bulk processing using deep-cre ate on the ImportHeader entity as well as single access to the entities. If the ImportHeader is used, an application log protocol en try is written. 974 PUBLIC Integration Guide Integration APIs Entity Data Model The following figure shows the entity data model (EDM) for the offer import service: Service Metadata URI: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ $metadata?sap-documentation=all 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/ CUAN_OFFER_IMPORT_SRV;v=0003/$ metadata?sap-documentation=all Only for internal access. You need to provide the server and port names. Marketing Offer Import 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. Import Offers API General access link takes you directly to the Import Offers metadata file. Onetime registration or logon is required. Integration Guide Integration APIs PUBLIC 975 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 Resources The service consists of the following types of resources: Read-Only Value Help Entities Value help entities to provide values for certain code and identifiers used in other entities. These entities are read-only and support HTTP GET operation to read the values defined in the system. Resource ExternalOfferStatus MarketingArea ProductOrigin MarketingLocationOrigin OfferContentType CommunicationMedium Description Path Read-only value help entity to retrieve all possible external offer status val ues. /ExternalOfferStatus Read-only value help entity to retrieve all active marketing areas in the sys tem. /MarketingAreas Read-only value help entity to retrieve all active product origins in the sys tem. /ProductOrigins Read-only value help to retrieve all ac /MarketingLocationOrigins tive marketing location origins defined in the system. Read-only value help entity to retrieve all active offer content types in the system. /OfferContentTypes Read-only value help entity to retrieve all active communication mediums in the system. /CommunicationMediums 976 PUBLIC Integration Guide Integration APIs Resource Language OfferContentPosition Description Path Read-only value help entity to retrieve /Languages all languages defined in the system. Read-only value help entity to retrieve all positions currently defined in any offer content. /OfferContentPositions Import Entities Entities used for importing offers with their assignment. These entities support multiple operations and are described in more detail in the OData operations sections below. Resource Description Path ImportHeader [page 978] Starting point when importing offers using deep-create. /ImportHeaders Offer [page 979] Supports basic CRUD with single read, create, update, and delete of im ported offers /Offers OfferContent [page 981] Supports basic CRUD with single read, expanded read of all content for an imported offer, create, update and deletion of offer content. /OfferContents OfferDateRulesType [page 982] Supports basic CRUD with single read, expanded read of all validity rules for an imported offer, create, up date and deletion of validity rules. /OfferDateRules MarketingLocationAssignment [page Assign or remove the assignment of 983] marketing locations to offers. /MarketingLocationAssignments ProductAssignment [page 984] Assign or remove the assignment of products to offers. /ProductAssignments ProductCategoryAssignment [page 985] Assign or remove the assignment of product categories to offers. /ProductCategoryAssignments TargetGroupAssignment [page 986] Assign or remove the assignment of target groups to offers. /TargetGroupAssignments CouponAssignment [page 987] Assign or remove the assignment of coupons to offers. /CouponAssignments Integration Guide Integration APIs PUBLIC 977 OData Resource: ImportHeader Helper entity representing import metadata, such as the importing system. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ ImportHeaders Permissions: Business Role SAP_COM_CSR_0020 Operations Only deep-create and single read is support on this helper resource. HTTP Method Operation URI POST GET Bulk import multiple offers with their assignments to Marketing Locations, Products, and Product Categories and Validity Rules. /ImportHeaders Read import header metadata of a spe /ImportHeaders(<id>) cific import run, identified by its Id. Properties Id: A technical ID of one import service execution. If no value is provided by the caller, an ID is generated by the system. Timestamp: Timestamp of the import run. If no value is provided by the caller, a timestamp is generated by the system. UserName: Name of the user who started the import. If no value is provided by the caller, the system uses the system name. SourceSystemType: The type of source system (can be freely defined, could be, for example, CRM or ERP). SourceSystemId: The ID of the source system. Can be freely defined. ImportMode: Mode in which the offers are imported. The following status values are available: "U" for Upsert: Non-existing offers are created with dependent child objects and already existing ones are updated. For existing ones, the offer header properties not given in the request or not changeable are ignored (works like a PATCH request). We recommend to always send the whole offer with all assigned objects and all offer header properties. For updating single values or assignments, the "Offer" entity or the offer assignment entitysets can be used. The offer child entities (like products, marketing locations, etc.) are replaced with the new entered ones (works like a PUT request). Assigned marketing locations or content will be deleted if not in the payload available. For Example: An offer has two validity rules. The request for update contains only offer header data with start date and end date. The two validity rules will be deleted and a new validity rule with the start date and end date of the offer header data will be created. "F" (Default) for Full: Only creates offers. Does not update. ProcessAllOrNothing: If an error occurs, this flag defines, whether all imported offers are discarded (response code 201) or only the ones that contain an error (response code 400, the error messages can be found in the response header). If the import mode is "U", the flag is always considered to have the value "true". If the import mode is "F", the flag can have values "true" and "false" (default). 978 PUBLIC Integration Guide Integration APIs OData Resource: Offer Represents an imported offer. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/Offers Operations The Offer resource provides basic offer header attributes that can be imported, for example offer name and validity start and end date. Note If an OfferDateRuleType entity is assigned, then no start or end date are allowed in the payload. Otherwise the excecution will fail and an error message will be produced. If you have enabled extension fields for the import service using the Custom Fields app, these extension attributes are also available to the offer resource to be imported. HTTP Method GET PUT MERGE PATCH DELETE Operation URI Single read an imported offer and its assigned objects. /Offers(<key>) /Offers(<key>)/ MarketingLocations /Offers(<key>)/Products /Offers(<key>)/ ProductCategories /Offers(<key>)/Rules Update an already imported offer, for example change the external status. /Offers(<key>) Delete an imported offer /Offers(<key>) Properties OfferIdExt: The unique offer ID provided by the external system that is used as part of the internal offer key in the import scenario. OfferIdOrigin: A unique identifier of the origin of the external offer. This origin ID is also used as part of the internal offer key in the import scenario. It should logically match the SourceSystemId and SourceSystemType of the ImportHeader entity type. Name: Name of the external offer (freetext). Description: Description of the external offer (freetext). MarketingAreaDescription: The description of the marketing area, which must be known to the system. Based on the description, the import system determines the ID of the marketing area. Note that either the marketing area description or the marketing area ID has to be provided. Integration Guide Integration APIs PUBLIC 979 MarketingAreaID: The ID of the marketing area, which must be known to the system. Note that either the marketing area description or the marketing area ID has to be provided. StartDate: The validity start date of the offer (timestamp with timezone offset). Not allowed together with OfferDateRuleType entity. Either offer dates or validity rules must be filled. EndDate: The validity end date of the offer (timestamp with timezone offset). Not allowed together with OfferDateRuleType entity. Either offer dates or validity rules must be filled. ExternalStatus: Status of the offer that can be defined by the external system (optional). Admissible values can be retrieved by the ExternalOfferStatus entity. If the ExternalStatus property is used, it is possible to control the internal lifecycle status of the offer under certain conditions. If the conditions are met, the internal offer status corresponds with the external status. . In an integrated environment, it is then no longer necessary to release the imported offer manually in the SAP Marketing Cloud system. The release can instead be triggered by the importing system. The conditions under which the external status is mapped to the internal status are met if the offer is completely managed externally. This is the case if: TargetGroupManagedExternally was set to true during offer creation and CouponManagedExternally was either set to `E' or left blank when the offer was imported and ContentManagedExternally was set to true during offer creation. The following status values are available: 00 for In Preparation 01 for Released 02 for Paused The following status transitions are possible: From 00 to 01. From 01 to 00 if the offer start date is in the future. From 01 to 02 if the offer start date is in the past. From 02 to 01. It is possible to create or import an offer with the status Released directly without having to import it with the In Preparation status first and then update it to Released. However, this will only succeed if all prerequisites for releasing an offer are met (such as offer content must be available; if it is an offer with coupon, a released coupon must be assigned; and so on). OfferContentManagedExternally: Defines whether the offer content is managed by the consumer of this API (=true) or by the Manage Offers application in SAP Marketing Cloud (=false). If you want to import offer content, you must set the property to true. The value for this property cannot be changed during a subsequent update to the offer and retains its original value. ExternalStatusDescription: Status description of the offer that can be defined by the external system (optional). Admissible values can be retrieved by the ExternalOfferStatus entity. TargetGroupManagedExternally: Defines if the target group assignments to externally created offers is managed by the import service (= true) or by the Manage Offers app (= false). In case you want to import target group assignments with this OData Service, this property must be set to true for the respective offer. If you later update the offer, the value for this property cannot be changed and will keep its original value. CouponManagedExternally: Defines if the coupon assignment to externally created offers is managed by the import service (= E) or by the Manage Offers app (= blank (I)) or if there is no coupon assignment to the offer at all (= ' '). In the latter case, the offer will be created without the coupon feature. In case you want to import a coupon assignment with this OData Service, this property must be set to E for the respective offer. If you later update the offer, the value for this property cannot be changed and will keep its original value. 980 PUBLIC Integration Guide Integration APIs OfferIsFundedBySupplier: A boolean flag that indicates if the offer is funded by a supplier or vendor of the offered products. ProjectedGrossMarginInPercent: The projected or calculated gross margin in percent, for example, for an offer. Note Marketing Area When assigning additional objects to an offer like target groups or coupons, the corresponding marketing area of the assigned objects need to match the marketing area of the offer. Keep in mind that also related marketing areas can taken into account when the enhancement option Allowed Marketing Areas has been implemented. For more information, see Allowed Marketing Areas. OData Resource: OfferContent Represents an imported offer content. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ OfferContents Operations The OfferContent resource provides offer content attributes that can be imported, such as the image URL and target link URL for offer content with the type Image. If you have enabled offer content extension fields for the import service using the Custom Fields app, these extension attributes are also available to the offer content resource to be imported. HTTP Method GET PUT MERGE PATCH DELETE Operation URI Single read a specific offer content or read all content defined for a given of fer. /OfferContents(<key>) /Offers(<key>)/OfferContent Update an offer content entity that has already been imported, for example change the URL of an image. /OfferContents(<key>) Delete an offer content instance. /OfferContents(<key>) Properties OfferIdExt: The unique offer ID provided by the external system that is used as part of the internal offer key in the import scenario. OfferIdOrigin: A unique identifier of the origin of the external offer. This origin ID is also used as part of the internal offer key in the import scenario. It should logically match the SourceSystemId and SourceSystemType of the ImportHeader entity type. Integration Guide Integration APIs PUBLIC 981 MarketingOfferContent: A consecutive number generated in the backend to identify a single offer content instance of an offer, such as 00001. LanguageISOCode: The language ISO code defining the language of the offer content, such as EN or DE. OfferContentType: The identifier of the offer content type, such as 01. OfferContentTypeName: The language-dependent name of the offer content type, such as Image. CommunicationMedium: The identifier of a communication medium to which the offer content is to apply, such as EMAIL. CommunicationMediumName: The language-dependent name of communication medium, such as Email. OfferContentPosition: The position of the offer content. This is an additional key field to define different offer contents of the same type for the same language and communication medium. In the case of offer content displayed on a webpage of an online shop, positions might be TOP or BOTTOM. The position can be freely defined by the consumer of the API. OfferContentSourceURL: The URL of an image. OfferContentSourceURLDesc: A description for the image URL. OfferContentTargetURL: The URL of a target link mostly used to define the target of a click action on the image. OfferContentTargetURLDesc: A description for the target link URL. OData Resource: OfferDateRulesType Represents an imported validity rule. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ OfferContents Operations The OfferDateRulesType resource provides validty rule attributes that can be imported, such as visibility, recurence, start date, and end date. If you have enabled extension fields for the import service using the Custom Fields app, these extension attributes are also available to the OfferDateRulesType resource to be imported. Note When importing Validity Rules, please familiarize yourself with the Special behavior for importing and updating validity rules [page 996] at the end of this page. HTTP Method GET Operations URI Single read a specific offer validity rule or read all validity rules defined for a given offer. /OfferDateRules(<key>) /Offer(<key>)/Rules 982 PUBLIC Integration Guide Integration APIs HTTP Method PUT MERGE PATCH POST Delete Operations URI Update an offer validity rule that has al ready been imported. For example, change the start date or end date of the validity rule. /OfferDateRules(<key>) Creates one or more additional offer validity rules entities for an offer that has already been imported. /OfferDateRules Delete an offer validity rule instance. /OfferDateRules(<key>) Properties OfferIdExt: The unique offer ID provided by the external system that is used as part of the internal offer key import scenario. OfferIdOrigin: A unique identifier of the origin of the external offer. This origin ID is also used as part of the internal offer key in the import scenario. It should logically match the SourceSystemId and SourceSystemType of the ImportHeader entity type. OfferDateRule: A consecutive number generated in the backend to identify a single offer validity rule instance of an offer, such as 00001. OfferDateRuleType: Use the offer validity rule type to define the rule visibility and validity in the specified time period, e.g. 01 to make the rule only visible for the contact in this period, 02 to make the rule visible for the contact and valid for business processes in this period, and 03 to make the rule only valid for business processes in this period. OfferDateRuleStartDateTime: The start date of the validity rule (timestamp with timezone offset). OfferDateRuleEndDateTime: The end date of the validity rule (timestamp with timezone offset). OData Resource: MarketingLocationAssignment Represents a marketing location assignment to an offer. The resource only contains the key fields for the offer and the marketing location. To import and read marketing locations, please use the corresponding import service. For more information, see Marketing Locations [page 710]. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ MarketingLocationAssignments Operations The MarketingLocationAssignment resource provides the necessary attributes to add, remove, and read marketing location assignments from existing offers. Integration Guide Integration APIs PUBLIC 983 HTTP Method GET POST DELETE Operation URI Query of all marketing locations as signed to a specific offer. /Offers(<key>)/ MarketingLocations / MarketingLocationAssignments(< key>) Add new assignment of a marketing lo cation to an existing offer. The location must not be obsolete. /MarketingLocationAssignments Delete existing marketing location as signment from an existing offer. / MarketingLocationAssignments(< key>) Properties OfferIdExt: The unique offer ID provided by the external system that is used as part of the internal offer key in the import scenario. OfferIdOrigin: A unique identifier of the origin of the external offer. This origin ID is also used as part of the internal offer key in the import scenario. It should logically match the SourceSystemId and SourceSystemType of the ImportHeader entity type. MarketingLocationId: Unique marketing location ID provided by the external system. With the MarketingLocationOrigninId, it is the external identifier of the master data object Marketing Location. In the import scenario, it is part of the key used to assign marketing locations to an offer. MarketingLocationOrigninId: A unique identifier of the origin of the external marketing location. In the import scenario, this origin ID is part of the key used to assign marketing locations to an offer. OData Resource: ProductAssignment Represents the product assignment to an offer. The resource only contains the key fields for the offer and the product. To import and read products, please use the corresponding import service. For more information, see Products [page 582]. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ ProductAssignment Operations The ProductAssignment resource provides the necessary attributes to add, remove, and read products from existing offers. 984 PUBLIC Integration Guide Integration APIs HTTP Method GET POST DELETE Operation URI Query of all products assigned to a spe /Offers(<key>)/Products cific offer. /ProductAssignments(<key>) Add new assignment of a product to an /ProductAssignments existing offer. Delete existing product assignment from an existing offer. /ProductAssignments(<key>) Properties OfferIdExt: The unique offer ID provided by the external system that is used as part of the internal offer key the import scenario. OfferIdOrigin: A unique identifier of the origin of the external offer. This origin ID that is also used as part of the internal offer key in the import scenario. It should logically match the SourceSystemId and SourceSystemType of the ImportHeader entity type. ProductId: Unique product ID provided by the external system. With the ProductOrigninId, it is the external identifier of the master data object Product. In the import scenario it is part of the key used to assign a product to an offer. ProductOrigninId: A unique identifier of the origin of the external product. In the import scenario, this origin ID is part of the key used to assign a product to an offer. OData Resource: ProductCategoryAssignment Represents the product category assignment to an offer. The resource only contains the key fields for the offer and the product category. To import and read product categories, please use the corresponding import service. For more information, see Product Hierarchies and Categories [page 604]. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ ProductCategoryAssignments Operations The ProductCategoryAssignment resource provides the necessary attributes to add, remove, and read product categories from existing offers. HTTP Method GET Operation URI Query to get all product categories as /Offers(<key>)/ signed to a specific offer. ProductCategories /ProductCategoryAssignments (<key>) Integration Guide Integration APIs PUBLIC 985 HTTP Method POST DELETE Operation URI Add new assignment of a product cate /ProductCategoryAssignments gory to an existing offer. Delete existing product category as signment from an existing offer. / ProductCategoryAssignments(<ke y>) Properties OfferIdExt: The unique offer ID provided by the external system that is used as part of the internal offer key in the import scenario. OfferIdOrigin: A unique identifier of the origin of the external offer. This origin ID that is also used as part of the internal offer key in the import scenario. It should logically match the SourceSystemId and SourceSystemType of the ImportHeader entity type. CategoryId: The unique category ID provided by the external system. Together with the HierarchyId, it is the external identifier of the master data object Product Category. In the import scenario, it is part of the key used to assign a product category to an offer. HierarchyId: A unique identifier external identifier of the product category Hierarchy. In the import scenario, this HierarchyID is part of the key used to assign a product category to an offer. OData Resource: TargetGroupAssignment Represents a target group assignment to an offer. The resource only contains the key fields for the offer and the target group. To import and read target groups, please use the corresponding import service. For more information, see Target Groups [page 755]. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ TargetGroupAssignments Operations The TargetGroupAssignment resource provides the necessary attributes to add, remove, and read target group assignments from existing offers. HTTP Method GET POST Operation URI Query of all target groups assigned to a /Offers(<key>)/TargetGroups specific offer. /TargetGroupAssignments(<key>) Add new assignment of a target group to an existing offer. The target group must be in status Released and the cat egory must not be Live. Only static or dynamic target groups are allowed. /TargetGroupAssignments 986 PUBLIC Integration Guide Integration APIs HTTP Method DELETE Operation URI Delete existing target group assignment / from an existing offer. TargetGrouopAssignments(<key>) Properties OfferIdExt: The unique offer ID provided by the external system that is used as part of the internal offer key in the import scenario. OfferIdOrigin: A unique identifier of the origin of the external offer. This origin ID is also used as part of the internal offer key in the import scenario. It should logically match the SourceSystemId and SourceSystemType of the ImportHeader entity type. TargetGroupKey: Unique target group key provided by the external system. Note that this key is a GUID which must be known to the caller. OData Resource: CouponAssignment Represents a coupon assignment to an offer. The resource only contains the key fields for the offer and the coupon. Note that in difference to all other assignments, the coupon represents a 1:1 releationship to the offer, for example, only a single coupon can be assigned to an offer. To import and read coupons, please use the corresponding import service. For more information, see Coupons [page 1026]. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ CouponAssignments Operations The CouponAssignment resource provides the necessary attributes to add, remove, and read coupon assignments from existing offers. HTTP Method GET POST DELETE Operation URI Query of the coupon assigned to a spe /Offers(<key>)/Coupons cific offer. /CouponAssignments(<key>) Add new assignment of a coupon to an existing offer and implicitly delete the old one. The coupon must not be as signed to another offer already. /CouponAssignments Delete existing coupon assignment from an existing offer. /CouponAssignments(<key>) Properties OfferIdExt: The unique offer ID provided by the external system that is used as part of the internal offer key in the import scenario. Integration Guide Integration APIs PUBLIC 987 OfferIdOrigin: A unique identifier of the origin of the external offer. This origin ID is also used as part of the internal offer key in the import scenario. It should logically match the SourceSystemId and SourceSystemType of the ImportHeader entity type. CouponUUID: Unique coupon identifier provided by the external system. Note that this key is a GUID which must be known to the caller. Coupon: Unique user-assigned coupon identifier. Can be used to identify which coupon should be assigned to the offer. If both CouponUUID and Coupon are provided, the system will use CouponUUID and ignore Coupon. Common HTTP Headers Common request and response headers used by the service operations. Common Request Headers Header Required Description Content-Type No X-CSRF-Token Yes Describes the format of the request body, for example, application/ json. All examples in this document use JSON format for the payloads. A security token that must be passed with every request. Common Response Headers Header Required Description SAP-Messages No If a request is successful, messages can be returned to the service consumer in this HTTP header. For example, in the case of deep-create offers with the property ProcessAllOrNothing set to false, this header contains potential errors occurred during the creation. However, the response shows the ac tual data created in the system. Common Status and Error Codes Code Reason 400 Bad request, for example, an offer with the same key already exists. 404 Not found, for example, an offer with the given key cannot be found in the system. 988 PUBLIC Integration Guide Integration APIs Code 201 Reason Offer successfully imported. OData Operation: Bulk Import Offers Import offers using the resource ImportHeader to create multiple offers with their assignments collectively (OData deep-create). Request URI: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ImportHeaders HTTP Method: POST Request Example: [POST] https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ ImportHeaders Request Payload Example Import exactly one offer using the ImportHeader resource. Sample Code { "UserName" : "IMPORT_USER", "SourceSystemType" : "SGC", "SourceSystemId" : "Gateway Client", "ProcessAllOrNothing" : true, "Offers" : [{ "OfferIdExt" : "0000000001", "OfferIdOrigin" : "SAP_PMR", "Name" : "PMR Offer Name", "Description" : "Offer Description ", "MarketingAreaDescription" : "Global", "StartDate" : "\/Date(1432634400000)\/", "EndDate" : "\/Date(1441872000000)\/" }] } Request Example: [POST] https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ ImportHeaders Request Payload Example Complex payload example of creating two offers, each offer including: Two Marketing Locations Two Validity Rules Two Products Two Product Categories Two Target Groups One Offer Integration Guide Integration APIs PUBLIC 989 Sample Code { "UserName" : "IMPORT_USER", "SourceSystemType" : "SGC", "SourceSystemId" : "Gateway Client", "ProcessAllOrNothing" : true, "CouponManagedExternally" : "E", "Offers" : [{ "OfferIdExt" : "OFFER_0057", "OfferIdOrigin" : "SAP_PMR", "Name" : "PMR Offer 0057", "Description" : "Offer 0057 from Gateway Test Client", "MarketingAreaDescription" : "Global", "MarketingLocations" : [{ "MarketingLocationOriginId" : "SAP_HYBRIS_COMMERCE_POS", "MarketingLocationId" : "99998" }, { "MarketingLocationOriginId" : "SAP_HYBRIS_COMMERCE_POS", "MarketingLocationId" : "99985" }], "Rules" : [ { "OfferDateRule":"0001", "OfferDateRuleType":"01", "OfferDateRuleStartDateTime":"\/Date(1530900780000)\/", "OfferDateRuleEndDateTime":"\/Date(1531772000000)\/", }, { "OfferDateRule":"0002", "OfferDateRuleType":"01", "OfferDateRuleStartDateTime":"\/Date(1531000780000)\/", "OfferDateRuleEndDateTime":"\/Date(1531572000000)\/", } ], "Products" : [{ "ProductOriginId" : "SAP_ERP_MATNR", "ProductId" : "887749052850" }, { "ProductOriginId" : "SAP_ERP_MATNR", "ProductId" : "887749052848" } ], "ProductCategories" : [{ "HierarchyId" : "GENERATED_HIERARCHY_ID", "CategoryId" : "Fleece2" }, { "HierarchyId" : "GENERATED_HIERARCHY_ID", "CategoryId" : "Fleece3" }], "TargetGroups" : [{ "TargetGroupKey":"6C0B84B7-5523-1ED7-8BFB-CFE77A316EC7"}, { "TargetGroupKey":"6C0B84B7-5523-1ED7-8AB7-D828EE609B8D" } ], "Coupons": { "OfferIdExt":"OFFER_0057", "OfferIdOrigin":"SAP_PMR", "CouponUUID":"6C0B84B7-5523-1ED7-8BFB-CFE77A316EC7", } }, 990 PUBLIC Integration Guide Integration APIs { "OfferIdExt" : "OFFER_0058", "OfferIdOrigin" : "SAP_PMR", "Name" : "PMR Offer 0058", "Description" : "Offer 0058 from Gateway Test Client", "MarketingAreaDescription" : "Global", "MarketingLocations" : [{ "MarketingLocationOriginId" : "SAP_HYBRIS_COMMERCE_POS", "MarketingLocationId" : "99998" }, { "MarketingLocationOriginId" : "SAP_HYBRIS_COMMERCE_POS", "MarketingLocationId" : "99985" }], "Rules":[ { "OfferDateRule":"0001", "OfferDateRuleType":"01", "OfferDateRuleStartDateTime":"\/Date(1530900780000)\/", "OfferDateRuleEndDateTime":"\/Date(1531772000000)\/", }, { "OfferDateRule":"0002", "OfferDateRuleType":"03", "OfferDateRuleStartDateTime":"\/Date(1531000780000)\/", "OfferDateRuleEndDateTime":"\/Date(1531572000000)\/", } ], "Products" : [{ "ProductOriginId" : "SAP_ERP_MATNR", "ProductId" : "887749052850" }, { "ProductOriginId" : "SAP_ERP_MATNR", "ProductId" : "887749052848" }], "ProductCategories" : [{ "HierarchyId" : "GENERATED_HIERARCHY_ID", "CategoryId" : "Fleece2" }, { "HierarchyId" : "GENERATED_HIERARCHY_ID", "CategoryId" : "Fleece3" }], "TargetGroups":[{ "TargetGroupKey":"6C0B84B7-5523-1ED7-8BFB-CFE77A316EC7" }, { "TargetGroupKey":"6C0B84B7-5523-1ED7-8AB7-D828EE609B8D" } ], "Coupons": { "CouponKey":"6C0B84B7-5523-1ED7-8BFB-CFE77A316EC7", } } ] } OData Operation: Update an Offer That Has Already Been Imported Update field values in an existing offer. The values of the following properties can be changed: Name Description Integration Guide Integration APIs PUBLIC 991 StartDate EndDate ExternalStatus ExternalStatusDescription System response is defined by the HTTP method used: MERGE or PATCH: It is possible to update a single value, for example the value for the description. All other fields won't be changed. No mandatory fields. POST: It is possible to add an additional value, for example TargetGroupAssignments. All other fields won't be changed. No mandatory fields. PUT: All fields will be updated, fields not mentioned in the request payload will be initialized. Update won't be performed if not all mandatory fields are included in the request payload. Request URI: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/Offers HTTP Method: POST, MERGE, PATCH, or PUT. Request Example: Example of changing the external status of an already imported offer to "released". [PATCH] https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ Offers(<key) Request Payload Example Sample Code { "ExternalStatus": "01" "ExternalStatusDescription": "" } Request Example: Example of changing an offer using HTTP PUT. Properties not included in the payload will be set to their initial value. [PUT] https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/Offers(<key) Request Payload Example Sample Code { "Name" : "Offer_0120_new", "Description" : "brand new Text for Offer 120", "StartDate" : "\/Date(1432634400000)\/", "EndDate" : "\/Date(1432734400000)\/", "ExternalStatus" : "02" } OData Operation: Delete Existing Offer An existing offer will be deleted including all assigned marketing location, products, and product categories. 992 PUBLIC Integration Guide Integration APIs Request URI: https://<Server>:<Port>/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/Offers HTTP Method: DELETE Request Example: [DELETE] https://<Server>:<Port>/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/ Offers(<key>) OData Operation: Read Offer Details Read offer details of an existing offer. Request URI: https://<Server>:<Port>/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/Offers(<offer key>) HTTP Method: GET Request Example: Read the offer header data only. [GET] https://<Server>:<Port>/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/ Offers(OfferIdExt='EXT_ID_0001', OfferIdOrigin='SAP_PMR') Response Payload Example Sample Code { "OfferIdExt" : "EXT_ID_0001", "OfferIdOrigin" : "SAP_PMR", "Name" : "PMR Offer Name", "Description" : "PMR Offer Description ", "MarketingAreaId" : "Global", "MarketingAreaDescription" : "Global", "StartDate" : "\/Date(1432634400000)\/", "EndDate" : "\/Date(1441872000000)\/", "ExternalStatus" : "01", "ExternalStatusDescription" : "Externally Released" } Request Example: Read the offer header data and all of the assignment information in one request. [GET] https://<Server>:<Port>/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/ Offers(OfferIdExt='EXT_ID_0001', OfferIdOrigin='SAP_PMR')? $expand=Prodcuts,ProductCategories,MarketingLocations Response Payload Example Sample Code { "OfferIdExt" : "EXT_ID_0001", "OfferIdOrigin" : "SAP_PMR", "Name" : "PMR Offer Name", Integration Guide Integration APIs PUBLIC 993 "Description" : "PMR Offer Description ", "MarketingAreaId" : "Global", "MarketingAreaDescription" : "Global", "StartDate" : "\/Date(1432634400000)\/", "EndDate" : "\/Date(1441872000000)\/", "ExternalStatus" : "01", "ExternalStatusDescription" : "Externally Released", "Products" : [{ "ProductOriginId" : "SAP_ERP_MATNR", "ProductId" : "887749052850" }], "ProductCategories" : [{ "HierarchyId" : "GENERATED_HIERARCHY_ID", "CategoryId" : "Fleece2" }], "MarketingLocations" : [{ "MarketingLocationOriginId" : "SAP_HYBRIS_COMMERCE_POS", "MarketingLocationId" : "99998" }] } OData Operation: Assign Marketing Location for an Existing Offer Create single marketing location assignment to an existing offer. Request URI: https://<Server>:<Port>/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/ MarketingLocationAssignments HTTP Method: POST Request Example: [POST] https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_IMPORT_SRV/ MarketingLocationAssignments Response Payload Example Add exactly one marketing location to an existing offer. Sample Code { "OfferIdExt" : "OFFER_0020", "OfferIdOrigin" : "SAP_PMR", "MarketingLocationOriginId" : "SAP_HYBRIS_COMMERCE_POS", "MarketingLocationId" : "99998" } OData Operation: Remove Marketing Location Assignment from an Existing Offer Remove assignment of a single marketing location assignment from an existing offer. Request URI: https://<Server>:<Port>/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/ MarketingLocationAssignments(<offer_key><mkt_location_key) HTTP Method: DELETE 994 PUBLIC Integration Guide Integration APIs Request Example: [DELETE] https://<Server>:<Port>/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/ MarketingLocationAssignments(OfferIdExt='OFFER_0020', OfferIdOrigin='SAP_PMR',MarketingLocationOriginId='SAP_HYBRIS_COMMERCE_POS', MarketingLocationId='99998') OData Operation: Create, Remove Assignment, and Get Operation for Products, Product Categories, Target Groups, Coupons, and Validity Rules. Create, remove assignment, and get operations for products, product categories, target groups, coupons, and validity rules (only create and get, remove is different) are similar to the operations for marketing locations described above. Note When removing validity rules, the offer must contain at least one remaining validity rule. For create and remove assignment operations replace MarketingLocationAssignments in the URI with ProductAssignments, ProductCategoryAssignments, TargetGroupAssignments, CouponAssignments, or OfferDateRules. Within the create request payload example replace the marketing location specific properties with product-, product-category-, target-group-, coupon-, or validity-rules-specific properties. To perform the GET operation, replace MarketingLocations with Products, ProductCategories, TargetGroups, Coupons, or OfferDateRules. OData Operation: Post New Offer with 2 Validity Rules Post a single offer with two validity rules. Request URI: https://<Server>:<Port/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/ImportHeaders HTTP Method: POST Request Example: [POST] https://<Server>:<Port/sap/opu/odata/sap/CUAN_OFFER_IMPORT_SRV/ImportHeaders Request Payload Example Sample Code { "Id":"", "Timestamp":null "UserName":"", "SourceSystemType":"SGC", "SourceSystemId":"Gateway Client", "ProcessAllOrNothing":true, "ImportMode":"U", "Offers":[ {"OfferIdExt":"EXT_OFFER_W_RULES", "OfferIdOrigin":"GENERIC", "Name":" EXT_OFFER_W_RULES ", "Description":"Offer From Gateway Test Client", "MarketingAreaDescription":"Global", Integration Guide Integration APIs PUBLIC 995 "StartDate":"\/Date(1530800780000)\/", "EndDate":"\/Date(1531872000000)\/", "TargetGroupManagedExternally":true, "OfferContentManagedExternally":true, "OfferContent":[ { "MarketingOfferContent":"00001", "LanguageISOCode":"EN", "OfferContentType":"01", "CommunicationMedium":"EMAIL", "OfferContentPosition":"HOME", "OfferContentSourceURL":"https://bild1.jpg", "OfferContentSourceURLDesc":"SourceBild1", "OfferContentTargetURL":"https://bild1.jpg", "OfferContentTargetURLDesc":"TargetBild1", "__metadata":{"type" : "CUAN_OFFER_IMPORT_SRV.OfferContent"} }], "Rules":[ { "OfferDateRule":"0001", "OfferDateRuleType":"01", "OfferDateRuleStartDateTime":"\/Date(1530900780000)\/", "OfferDateRuleEndDateTime":"\/Date(1531772000000)\/", "__metadata":{"type" : "CUAN_OFFER_IMPORT_SRV.OfferDateRulesType"} }, { "OfferDateRule":"0002", "OfferDateRuleType":"03", "OfferDateRuleStartDateTime":"\/Date(1531000780000)\/", "OfferDateRuleEndDateTime":"\/Date(1531572000000)\/", "__metadata":{"type" : "CUAN_OFFER_IMPORT_SRV.OfferDateRulesType"} } ], "__metadata":{"type":"CUAN_OFFER_IMPORT_SRV.Offer"} }], "__metadata":{"type":"CUAN_OFFER_IMPORT_SRV.ImportHeader"} } Special behavior for importing and updating Validity Rules Import Validity Rules Start Date Included End Date Included ImportHeaders Enti No No tyset No No Yes No Yes No Number of Validity Rules in Request 0 >0 0 >0 Result "Either offer dates or validity rules must be filled." Success "End date must be filled." "Not allowed to import offer dates and rules." 996 PUBLIC Integration Guide Integration APIs Import Validity Rules No Yes 0 No Yes >0 Yes Yes 0 Yes Yes >0 Offers Entityset - No No - Patch Yes No - No Yes - Yes Yes - Offers Entityset - Put No No - Yes No - No Yes - Integration Guide Integration APIs "Start date must be filled." "Not allowed to import offer dates and rules." Success "Not allowed to import offer dates and rules." Success If offer has only 1 rule assigned, change the start date of the rule and the offer. If >1 rule is assigned: "Start date of offers with more than one rule assigned cannot be changed." If offer has only 1 rule assigned, change the end date of the rule and the offer. If >1 rule is assigned: "End date of offers with more than one rule assigned cannot be changed." If offer has only 1 rule assigned, change the start and end dates of the rule and the offer. If >1 rule is assigned: "Start and end dates of offers with more than one rule assigned can not be changed." "Offer start and end dates are not filled." "Offer end date is not filled." "Offer start date is not filled." PUBLIC 997 Import Validity Rules Yes Update Offer Validity Start Date ImportHeaders No Entityset No Yes Yes Yes - If offer has only 1 rule assigned, change the start and end dates of the rule and the offer. If >1 rule is assigned: "Start and end dates of offers with more than one rule assigned can not be changed." End Date No No No No Number of Valid ity Rules in the Request Offer Status 0 In Preparation >0 In Preparation 0 In Preparation >0 In Preparation Result "Either offer dates or validity rules must be filled." Replace the exist ing rules with new ones. If only one rule is assigned, update start date, keep the end date. If >1 rule is assigned: "Start and end dates of offers with more than one rule assigned cannot be changed." "Not allowed to im port offer dates and rules." 998 PUBLIC Integration Guide Integration APIs Update Offer Validity No Yes 0 No Yes >0 Yes Yes 0 Yes Yes >0 ImportHeaders No No 0 Entityset No No >0 In Preparation In Preparation In Preparation In Preparation Paused Paused If only one rule is assigned, update end date, keep the start date. If >1 rule is assigned: "Start and end dates of offers with more than one rule assigned cannot be changed." "Not allowed to im port offer dates and rules." Delete all assigned rules and create a new one with the given start and end dates. "Not allowed to im port offer dates and rules." "Either offer dates or validity rules must be filled." If any stored or im ported rules have any dates in the past, then an error is raised. If all stored and imported rules have all dates in the future, then re place the existing rules with new ones. Integration Guide Integration APIs PUBLIC 999 Update Offer Validity Yes No 0 Yes No >0 No Yes 0 Paused Paused Paused If only one rule is assigned and start date is in the fu ture, then update the start date and keep the end date. Otherwise, an er ror message is produced: "Start date is in the past and cannot be changed." If >1 Rule is stored, then an error mes sage is produced: "Start and end dates of offers with more than one rule assigned cannot be changed." "Not allowed to im port offer dates and rules." If only one rule is stored and end date is in the fu ture, then update the end date and keep the start date (also if it is in the past). Otherwise, an error message is produced: "End date is in the past and cannot be changed." If >1 rule is stored, then an error mes sage is produced: "Start and end dates of offers with more than one rule assigned cannot be changed." 1000 PUBLIC Integration Guide Integration APIs Update Offer Validity No Yes >0 Yes Yes 0 Yes Yes >0 Related Information Custom Fields Paused Paused Paused "Not allowed to im port offer dates and rules." If >1 rule is stored and any date is in the past, then an error message is produced: "Start and end dates of offers with more than one rule as signed cannot be changed." If all stored rules start in the future, then delete all as signed rules and create a new one with the given start and end dates. If only one rule is assigned, then send dates to BOPF (tests), change existing rule and same be havior < 1902. "Not allowed to im port offer dates and rules." Integration Guide Integration APIs PUBLIC 1001 5.6.6 Read Offers Public OData API (API_MKT_OFFER_SRV) for Offers Technical Data The public API for Offers supports operations on the Offers Business Object. OData Version Root URI Service Metadata URI Authorizations Communication Scenario ID Component for Incidents 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_OFFER_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_OFFER_SRV/$metadata The following business catalog is required: SAP_CEC_BC_MKT_API_OFR_PC SAP_COM_0306 CEC-MKT-OFM (Offers) Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Field Extensibility Supported Yes You can view sample payloads and test the API at https://api.sap.com . 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 https:// <Server>:<Port>/sap/opu/ odata/SAP/API_MKT_OFFER_SRV/ $metadata?sapdocumentation=all Remarks Only for internal access. You need to provide the server and port names. 1002 PUBLIC Integration Guide Integration APIs Access Link Marketing - Offers Details Page Read Offers API Remarks 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. General access link takes you directly to the Offers metadata file. One-time regis tration 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 Entity Sets The Offers OData API provides the following entities: Entity Set Description Path Offers This entity contains a list of /Offers offers. OfferContents This entity contains the contents of an offer. /Offers(guid'<Offer UUID>')/OfferContents OfferCoupons This entity contains offer /Offers(guid'<Offer UUID>')/OfferCoupons coupons. OfferMarketingLocations This entity contains the marketing locations of of fers. /Offers(guid'<Offer UUID>')/ OfferMarketingLocations OfferProducts This entity contains the /Offers(guid'<Offer UUID>')/OfferProducts products that are on offer. OfferProductCategories This entity contains the /Offers(guid'<Offer UUID>')/ categories of products that OfferProductCategories are on offer. OfferTargetGroups This entity contains the /Offers(guid'<Offer UUID>')/OfferTargetGroups target groups to which you want to send the offers. Integration Guide Integration APIs PUBLIC 1003 Entity Set OfferFeatures OfferFacets Description Path This entity contains the features of offers. /Offers(guid'<Offer UUID>')/OfferFeatures This entity contains exter /Offers(guid'<Offer UUID>')/OfferFacets nal offers. Offers Resource Path: /Offers You can perform the following operations on the Offers entity set: Operations on Offers entity set HTTP Method Description GET Get a list of offers Get the details of a specific offer Path /Offer?$top /Offers(guid'<Offer UUID>') OfferContents Resource Path: /Offers(guid'<Offer UUID>')/OfferContents You can perform the following operations on the OfferContents entity set: Operations on OfferContents entity set HTTP Method Description Path GET Get all contents of an offer /Offers(guid'<Offer UUID>')/ OfferContents Get a specific offer content /OfferContents(guid'<Offer Contents UUID>') Get the offer or offers in which a specific offer con tent is used / OfferCoupons(CouponUUID=guid'<Coupon UUID>',MarketingOfferUUID=guid'<Mark eting Offe rUUID>')/Offer OfferCoupons Resource Path: /Offers(guid'<Offer UUID>')/OfferCoupons You can perform the following operations on the OfferCoupons entity set: Operations on OfferCoupons entity set HTTP Method Description GET Get all coupons of an offer Path /Offers(guid'<Offer UUID>')/ OfferCoupons 1004 PUBLIC Integration Guide Integration APIs HTTP Method Description Path Get a specific coupon of an offer / OfferCoupons(MarketingOfferUUID=guid '<Marketing Offer UUID>',CouponUUID=guid'<Coupon UUID>') Get the offer or offers in which a specific coupon is used / OfferCoupons(CouponUUID=guid'<Coupon UUID>',MarketingOfferUUID=guid'<Mark eting Offer UUID>')/Offer OfferMarketingLocations Resource Path: /Offers(guid'<Offer UUID>')/OfferMarketingLocations You can perform the following operations on the OfferMarketingLocations entity set: Operations on OfferMarketingLocations entity set HTTP Method Description Path GET Get all marketing locations of an offer /Offers(guid'<Offer UUID>')/ OfferMarketingLocations Get a specific marketing location of an offer / OfferMarketingLocations(MarketingOff erUUID=guid'<Marketing Offer UUID>',MarketingLocationUUID=guid'<M arketing Location UUID>') Get the offer or offers in which a specific marketing location is used / OfferMarketingLocations(MarketingLoc ationUUID=guid'<Marketing Location UUID>',MarketingOfferUUID=guid'<Mark eting Offer UUID>')/Offer OfferProducts Resource Path: /Offers(guid'<Offer UUID>')/OfferProducts You can perform the following operations on the OfferProducts entity set: Operations on OfferProducts entity set HTTP Method Description GET Get all products of an offer Path /Offers(guid'<Offer UUID>')/ OfferProducts Integration Guide Integration APIs PUBLIC 1005 HTTP Method Description Path Get a specific product of an offer / OfferProducts(MarketingOfferUUID=gui d'<Marketing Offer UUID>',ProductUUID=guid'<Product UUID>') Get the offer or offers in which a specific product is used / OfferProducts(ProductUUID=guid'<Prod uct UUID>',MarketingOfferUUID=guid'<Mark eting Offer UUID>')/Offer OfferProductCategories Resource Path: /Offers(guid'<Offer UUID>')/OfferProductCategories You can perform the following operations on the OfferProductCategories entity set: Operations on OfferProductCategories entity set HTTP Method Description GET Get all product categories of an offer Get a specific product category of an offer Get the offer or offers in which a specific product category is used Path /Offers(guid'<Offer UUID>')/ OfferProductCategories / OfferProductCategories(MarketingOffe rUUID=guid'<Marketing Offer UUID>',ProductCategoryUUID=guid'<Pro duct Category UUID>') /OfferProductCategories(Product Category UUID=guid'<ProductCategoryUUID>',Mar ketingOfferUUID=guid'<Marketing Offer UUID>')/Offer OfferTargetGroups Resource Path: /Offers(guid'<Offer UUID>')/OfferTargetGroups You can perform the following operations on the OfferTargetGroups entity set: Operations on OfferTargetGroups entity set HTTP Method Description GET Get all target groups of an offer Path /Offers(guid'<Offer UUID>')/ OfferTargetGroups 1006 PUBLIC Integration Guide Integration APIs HTTP Method Description Get a specific target group of an offer Get the offer or offers in which a specific target group is used Path / OfferTargetGroups(MarketingOfferUUID =guid'<Marketing Offer UUID>',TargetGroupUUID=guid'<Target Group UUID>') / OfferTargetGroups(TargetGroupUUID=gu id'<Targe tGroup UUID>',MarketingOfferUUID=guid'<Mark eting Offer UUID'>)/Offer OfferFeatures Resource Path: /Offers(guid'<Offer UUID>')/OfferFeatures You can perform the following operations on the OfferFeatures entity set: Operations on OfferFeatures entity set HTTP Method Description Path GET Get all features of an offer /Offers(guid'<Offer UUID>')/ OfferFeatures Get a specific feature of an offer / OfferFeatures(MarketingOfferUUID=gui d'<Marketing Offer UUID>',OfferFeature='<Offer Feature>') Get the offer or offers in which a specific feature is used / OfferFeatures(MarketingOfferUUID=gui d'<Marketing Offer UUID>',OfferFeature=guid'<Offer Feature>')/Offer OfferFacets Resource Path: /Offers(guid'<Offer UUID>')/OfferFacets You can perform the following operations on the OfferFacets entity set: Operations on OfferFacets entity set HTTP Method Description GET Get all external offers Path /Offers(guid'<Offer UUID>')/ OfferFacets Integration Guide Integration APIs PUBLIC 1007 HTTP Method Description Get a specific external offer Get the offer or offers for a given offer facet Path / OfferFacets(ExternalOffer=guid'<Exte rnal Offer>',ExternalOfferOrigin=guid'<Ex ternal Offer Origin>') / OfferFacets(ExternalOffer=guid'<Exte rnalOffer>',ExternalOfferOrigin=guid '<External Offer Origin>')/Offer 5.6.7 Discover Offers Use the API OData service CUAN_OFFER_DISCOVERY_SRV for SAP Marketing Cloud Offers to find suitable offers for a consumer. Overview The public OData service CUAN_OFFER_DISCOVERY_SRV can be used to retrieve suitable offer content to consumers for a specific context. For example in a Web shop, such as SAP Commerce, the service can be used to determine offer content, such as a banner, to be displayed on a Web page in the shop. To find the most relevant offer content, a number of context parameters can be passed to the service. Possible contexts for a Web shop scenario include the following: Current user logged on to the Web shop to show personalized offers Browser language to determine offer content (such as images) in the correct language When requesting the OData with an Offer Recommendation Scenario ID, the rule based Offer Recommendation Intelligence will include recommended offers. Without the Scenairo ID a simple solution will recommend offers based on solely on the eligibilty. OData Version Root URI Service Metadata URI Authorizations 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ CUAN_OFFER_DISCOVERY_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ CUAN_OFFER_DISCOVERY_SRV/$metadata The following business catalog role is required: SAP_COM_CSR_0021 1008 PUBLIC Integration Guide Integration APIs Component for Incidents CEC-MKT-OFM (Offers) Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. You can view sample payloads and test the API at https://api.sap.com . Support of OData Features See the following chapters for implementation details and search behavior of the OData services. Feature Support Query options for value help entities http GET on OfferContents entity set The current implementation of the value help entities sup ports the following query options, which can be passed as query or path parameters: $top and $skip $select $orderby $count and $inlinecount Exception: the entity set ItemSourceTypes supports only $orderby, the entity set ItemValueHelps does not sup port $inlinecount. This API can be used to retrieve Offer Content objects from the system using the input parameters provided. This API supports the retrieval of an offer without Offer Recommen dation Intelligence (ORI) and with ORI with a subset of the available ORI functionality. http POST with deep-create on Recommendations entity set This API is the preferred method to retrieve Offer Content Recommendations using Offer Recommendation Intelli gence (ORI). It supports enhanced capabilities for use with the ORI. http GET on function GetCouponCode This API endpoint can be used to retrieve coupon codes. Entity Data Model The following graphic shows the available entity sets and their relationships to each other. Integration Guide Integration APIs PUBLIC 1009 Service Metadata URI: https://<Server>:<Port>/sap/opu/odata/SAP/ CUAN_OFFER_DISCOVERY_SRV/$metadata 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/ CUAN_OFFER_DISCOVERY_SRV;v=000 3/$metadata?sapdocumentation=all Only for internal access. You need to provide the server and port names. Marketing Offer Discovery Service De tails 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. Discover Offers API General access link takes you directly to the Offer Discovery Service 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: 1010 PUBLIC Integration Guide Integration APIs Metadata Value in XML sap:updatable sap:creatable nullable Meaning When FALSE read-only field read-only field mandatory field Resources The service consists of the following resource: Value help entities to provide values for certain code and identifiers used in other entities. These entities are read-only and support HTTP GET operation on the corresponding entity set to read the values defined in the system. Navigational entities, that cannot be called directly, but are used in combination with another entity. The API hub documentation shows these entities only as collections in the model description of the corresponding request of its parent entity set. Entities to retrieve offer content objects from the system. These entities are described in more detail in the OData Resource section of this document. Read-Only Value Help Entities Resource CommunicationMedium ContentPosition ContentType CustomerOrigin ItemSourceType ItemValueHelp Language MarketingLocation Description Path Value help entity to retrieve available communication me diums. /CommunicationMediums Value help entity to retrieve available content position val ues. /ContentPositions Value help entity to retrieve available offer content type values /ContentTypes Value help entity to retrieve available customer origins /CustomerOrigins Value help entity to retrieve available item source types for BasketObject and LeadingOb ject. /ItemSourceTypes Value help entity to retrieve available items for BasketOb ject and LeadingObject. /ItemValueHelps Value help entity to retrieve /Languages available language ISO codes Value help entity to retrieve available marketing location UUIDs. /MarketingLocations Integration Guide Integration APIs PUBLIC 1011 Resource OfferRecommendationScenario Description Value help entity to retrieve available offer recommenda tion scenario IDs. Path /OfferRecommendationScenarios Read-Only Navigational Property Entities Resource Description Path BasketObject Navigational property of the Recommendation entity to provide BasketObjects in the deep-create call. /Recommendations/BasketObjects ContentTypeField Navigational property of the ContentType entity to read the available fields of offer content types. /ContentTypes/ContentTypeFields ContextParam Navigational property of the Recommendation entity to provide free context parame ters in the deep-create call. /Recommendations/ContextParams LeadingObject Navigational property of the Recommendation entity to provide LeadingObjects in the deep-create call. /Recommendations/LeadingObjects Result Navigational property of the Recommendation entity to re turn results in the deep-create call. /Recommendations/Results AssignedCoupon Navigational property of the Result entity to provide Cou pon data in the deep-create call. /Recommendations/Results/ AssignedCoupon Offer Content Retrieval Entities Resource Description Path OfferContent Entity to retrieve offer content objects from the system using a GET call on the correspond ing entity set OfferContents with search parameters pro vided via the complex type Of ferContentSearch. /OfferContents 1012 PUBLIC Integration Guide Integration APIs Resource Recommendation Description Path Entity to retrieve offer content /Recommendations objects from the system using a POST call on the correspond ing entity set Recommenda tions and providing the input parameters in a deep-create call using the navigational properties LeadingObjects, BasketObjects and Context Params of the entity. The re sults are returned using the navigational property Results. OData Resource: OfferContent The entity to retrieve offer content objects from the system using a GET call on the corresponding entity set. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/ OfferContents Permissions: Business catalog role SAP_COM_CSR_0021 Operations CRUD Operations The entity supports only GET on its entity set. HTTP Method GET Operation URI Read a list of offer content objects that adhere to the provided search parame ters. /OfferContents The retrieval of OfferContent entities in the OData service CUAN_OFFER_DISCOVERY_SRV is done by requesting the entity set OfferContents using a GET operation, using a $filter operator with the available parameters for the complex type OfferContentSearch. A direct retrieval of individual OfferContent entities using the key fields is not implemented. The following request parameters can be used as filter properties in the $filter-clause: CustomerId: The user or customer or consumer ID of the user logged on to the Web shop. If this parameter is not used in $filter or used with an empty string, the parameter CustomerOriginId is ignored. CustomerOriginId: The origin ID for interaction contacts defined in Customizing. If this parameter is not used in $filter or used with an empty string and the CustomerId is also used, the parameter value is defaulted to the delivered value SAP_HYBRIS_CONSUMER internally. CommunicationMediumId: The ID of a communication medium. If a CommunicationMediumId is passed to the OData service as a filter, only offer contents for that communication medium are retrieved. Integration Guide Integration APIs PUBLIC 1013 LanguageId: The ISO language code of the offer content. In a Web shop, this might correspond to the user's logon language. If no language is passed to the OData service, the result contains all available languages. Position: Position in the Web shop where offers are to be displayed, such as Top or Bottom. This information must have been entered for the offer content. RecommendationScenarioId: This field is not supported. ContentMediumTypeId: The ID of a content type, such as. "01" for content type "Image". If this parameter is not used in $filter the value is defaulted to "01" internally. Only offer contents matching the specified content medium type ID are retrieved. MarketingLocationKey: One or more marketing location identifiers (UUIDs) to search for offers that either have no marketing location assigned or have one of the specified marketing locations assigned. If offers without marketing locations are requested, a filter on MarketingLocationKey for example `' must be supplied in the query. When not using the MarketingLocationKey property as filter, the returned offers can have zero to multiple marketing locations assigned. Extensibility and Offer Content Types The OData service CUAN_OFFER_DISCOVERY_SRV supports both "Offer Header Data" and "Offer Content Data" extensibility using the Custom Fields app. For more information, see Custom Fields for Offer Header and Offer Content. It is possible to read the values of extensibility fields when reading OfferContent entities. However, it is not possible to define filters for these extension fields. For any content type defined in the app Manage your Solution, associated fields can be defined in the app User Interface Adaptation. For more information, see User Interface Adaptation. The service provides the information about which fields belong to which offer content type in the following two ways: The value help entity type ContentType has a navigational property AvailableFields to read the list of available fields in the entity type OfferContent. Field-control fields are part of the entity type OfferContent. These fields control the visibility of the corresponding data field in the following way: If the corresponding data field is part of the returned content type the value is 1 (meaning read-only) If the corresponding data field is not part of the returned content type the value is 0 (meaning hidden) Search Behavior The CustomerId and CustomerOriginId parameters can only accept a single value for the filter operation $filter with the operator EQ. Additional filters using these parameters are ignored. Other operators are ignored and set to EQ. If a range operator (for example BT) is used, the lower boundary value is used. The higher boundary value is ignored. The search result contains 0-n OfferContent entities which are active on the date and time of the actual request and have only valid marketing location assignments. If a coupon is assigned to the offer, an offer is only returned if the redemption limit for the coupon has not been reached. The Redemption Limit and the Redemption Limit for Each Contact are taken into account. For more information, see Manage Coupons. An offer is active at a particular point in time if the status is Released and if the point in time is found during one of the offer visibility (valid or visible) ranges. A marketing location assigned to an offer is valid with respect to this offer if, and only if the following is true: The marketing location is not closed (deleted). The offer end date, in UTC, is found during the validity period of the location. 1014 PUBLIC Integration Guide Integration APIs The result set is sorted internally using a ranking that is based on the filterable properties CustomerId: Offers are assigned the highest ranking if the CustomerId is part of any assigned target group that is assigned to the offer. Conversely, offers with no target group are assigned the lowest ranking. These offers are valid for any customer. Additional sorting parameters can be passed to the service using $orderby, but are applied to the internal sorting after the logic described above. OData Operation: GET OfferContent Request URI: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/OfferContents Operation Type: R (Read) HTTP Method: GET Permissions: Business catalog role SAP_COM_CSR_0021 The OData API is only to be called using $batch, so that the query can be encrypted in the HTTP request body and to avoid URL overflows. A request to the OData service to retrieve up to ten OfferContent entities with filters on CustomerId, CommunicationMedium Language and Position could then be as follows: Example HTTP request for offer content retrieval Note To improve readability, the following example HTTP requests and responses do not show all the details. Some metadata information is for example omitted in the JSON responses and URLs are shown without encoding. For example, spaces are not replaced by %20. POST /sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/$batch Request Headers: accept application/json content-type multipart/mixed;boundary=batch_1e29-6867-0e8e Request Body: --batch_1e29-6867-0e8e Content-Type: application/http Content-Transfer-Encoding: binary GET OfferContents?$top=10&$filter=Search/CustomerId eq 'demo@hybris.com' and Search/CommunicationMediumId eq 'ONLINE_SHOP' and Search/LanguageId eq 'FR' and Search/Position eq 'TOP' HTTP/1.1 Accept: application/json Accept-Language: en-US DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 --batch_1e29-6867-0e8e-- Response Format: JSON { Integration Guide Integration APIs PUBLIC 1015 "d": { "results": [{ "Search": { "CustomerId": "", "CustomerOriginId": "", "CommunicationMediumId": "", "ContentMediumTypeId": "", "LanguageId": "", "Position": "", "RecommendationScenarioId": "" "MarketingLocationKey": "" }, "OfferId": "0000004711", "Offer": "Offer 4711", "CustomerId": "demo@hybris.com", "ContentId": "00001", "CommunicationMediumId": "ONLINE_SHOP", "CommunicationMedium": "Online-shop", "LanguageId": "FR", "Language": "French", "Postion": "TOP", "ContentMediumTypeId": "01", "ContentMediumType": "Image", "ContentDescription": "Buy 2 get 1 free", "ContentSource": "http://assets.mycompany.com/offer4711.png", "TargetDescription": "Link for offer 4711", "TargetLink": "http://www.mycompany.com/offer4711.html" }, { "Search": { "CustomerId": "", "CustomerOriginId": "", "CommunicationMediumId": "", "ContentMediumTypeId": "", "LanguageId": "", "Position": "", "RecommendationScenarioId": "" "MarketingLocationKey": "" }, "OfferId": "0000004712", "Offer": "Offer 4712", "CustomerId": "", "ContentId": "00001", "CommunicationMediumId": "ONLINE_SHOP", "CommunicationMedium": "Online-shop", "LanguageId": "FR", "Language": "French", "Postion": "TOP", "ContentMediumTypeId": "01", "ContentMediumType": "Image", "ContentDescription": "20% off for order values > 100", "ContentSource": "http://assets.mycompany.com/offer4712.png", "TargetDescription": "Link for offer 4712", "TargetLink": "http://www.mycompany.com/offer4712.html" }] } } This response contains two OfferContent entities. The first entity was found because the customer (with id demp@hybris.com) was found in a target group that is assigned to offer 4711 and both the language, the communication medium and the position of the entity match the search query. The second OfferContent 1016 PUBLIC Integration Guide Integration APIs entity was found because the offer has no target group assigned and the language, the communication medium and the position match the corresponding filter values of the entity. The content of offer 4711 is ranked first according to the sorting rules described above. OData Resource: Recommendations As of Release 1705, a new API has been introduced in the offer discovery service that provides enhanced capabilities to use in combination with the Offer Recommendation Intelligence (ORI). This API is based on the new Recommendation entity in the offer discovery service and allows the caller to specify leading items, basket items and free context parameters to be used in the defined rules in an ORI model. Since this functionality could not be provided using the existing GET OfferContent API, this new API was introduced which uses a POST call on the Recommendations entity set. All input parameters are provided in the HTTP body of the request, similar to a deep create of an OData entity. Remark: The GET OfferContent continues to work with the release 1705, with some minor changes regarding the search behavior when using a MarketingLocationKey filter and the sorting behavior of the result set. Resource Path: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/ Recommendations Permissions: Business catalog role SAP_COM_CSR_0021 Operations CRUD Operations The entity supports only PUT on its entity set. HTTP Method POST Operation URI Deep-create on the Recommendations entity set to retrieve offer content ob jects process by the ORI /Recommendations Input and output of the API is defined by the structure of the Recommendation entity (see also the $metadata XML definition of the offer discovery service and the API hub documentation). The Recommendation entity has three properties (CustomerId, CustomerOriginId and RecommendationScenarioId that are used as input values when calling the API. To call the recommendation API for anonymous contacts, provide the CustomerID and CustomerOriginId parameters and use blank/empty ("") values. Additional input values for leading items, basket items and free context parameters are provided using navigation properties with the respective entity types LeadingObject, BasketObject and ContextParam. The results are returned in the navigation property results. The entity result uses the same properties as the OfferContent entity for the GET OfferContent call and adds the property Score, which contains the score value for the offer content object as determined by the ORI and the external ID and origin for imported offer objects (InboundOriginIdExt and InboundOriginId). The service contains two additional value help entities ItemSourceType and ItemValueHelp for the properties of the LeadingObject and BasketObject entities. These are defined in the service metadata using ValueList annotations, similar to the value help entities for the OfferContent/Search in the GET call of the API. Integration Guide Integration APIs PUBLIC 1017 No value help entity is available for the the ContextParam entity. For a list of possible context parameter names, see the "Search Behavior" chapter of this section. Example of the Recommendation entity as JSON structure: Sample Code Recommendation: { // -> IN: fields that were previously used in complex type OfferContentSearch to perform the ORI call. // CustomerId is now UserId // CustomerOriginId is now UserOriginId // CommunicationMediumId -> is derived from the recommendation scenario! // ContentMediumTypeId, LanguageId, Position, MarketingLocationKey -> moved into the ContextParams navigation property UserId: "", UserOriginId: "", RecommendationScenarioId: "", // value list annotation to OfferRecommendationScenarios // -> IN: new LeadingObject entity type (same internal structure as BasketObject) LeadingObjects: [{ LeadingObjectType: "", // -> value list annotation to ItemSourceTypes LeadingObjectId: "" // -> value list annotation to ItemValueHelps (LeadingObjectType as input) }], // -> IN: new BasketObject entity type (same structure as LeadingObject) BasketObjects: [{ BasketObjectType: "", // -> value list annotation to ItemSourceTypes BasketObjectId: "" // -> value list annotation to ItemValueHelps (BasketObjectType as input) }], // -> IN: new ContextParam entity type ContextParams: [{ ContextId: 0 // Integer key Name: "", Value: "" }], // -> OUT: new Result entity type Results: [{ OfferId: "", Offer: "", InboundOriginId: "", InboundOriginIdExt: "", ContentId: "", CommunicationMediumId: "", CommunicationMedium: "", LanguageId: "", Language: "", Position: "", ContentMediumTypeId: "", ContentMediumType: "", ContentDescription: "", ContentSource: "", TargetDescription: "", TargetLink: "", FC_ContentPosition: "", FC_ContentMediumTypeId: "", FC_ContentDescription: "", FC_ContentSource: "", FC_TargetDescription: "", FC_TargetLink: "", Score: "", 1018 PUBLIC Integration Guide Integration APIs }] } Extensibility and Result Entity Type The Result entity responds in the same way as the OfferContent entity with regards to extensibility (see also the corresponding chapter above). Search Behavior The POST Recommendations API responds similarly to the GET OfferContents API, with the following differences: The call is performed using an HTTP POST, providing all input parameters in the request body. To call the API, a valid X-CSRF-Token must be supplied in the request header (this token can be retrieved by sending a GET request to /sap/opu/odata/sap/CUAN_OFFER_DISCOVERY_SRV with the HTTP header containing the attribute X-CSRF-Token with the value `fetch'. $skip/$top operations are not supported. The number of returned offer content objects in the Result property is restricted by the available number of valid objects in the system and the maximum number of results defined in the recommendation model. The API can only be used for use with ORI. Therefore, the RecommendationScenarioId is a mandatory input parameter. The chosen recommendation scenario must have a communication medium assigned. The communication medium is used during the selection of the relevant offer content. Using a recommendation scenario without a communication medium will lead to an error. LeadingObjects, BasketObjects and ContextParams are optional input parameters. The Results navigational property must be requested in the API call (see below for an example of calling the API) The ContentMediumTypeId, LanguageId, Position, MarketingLocationKey and CommunicationMediumId input parameters from the GET OfferContent API are provided using the ContextParams navigation property. When providing CommunicationMediumId in the ContextParams, the values are used in addition to the communication medium derived from the recommendation scenario. The available context parameters names are: P_LANGUAGE: for OfferContent/Search/LanguageId P_POSITION: for OfferContent/Search/Position P_COMM_MEDIUM: for OfferContent/Search/CommunicationMediumId P_CONT_MEDIUM_TYPE: for OfferContent/Search/ContentMediumTypeId P_ML_UUID32: for OfferContent/Search/MarketingLocationKey P_CURRENT_LONGITUDE: parameter no longer supported P_ CURRENT_LATITUDE: parameter no longer supported P_WITH_COUPON: parameter to filter offers with assigned coupons Parameter value = `X' delivers only offers with assigned coupons Parameter value = ` ' delivers only offers without assigned coupons Requests without parameter P_WITH_COUPON deliver offers with and without assigned coupons P_MARKETING_AREA: parameter to restrict the offers based on their assigned marketing area Context parameters that are not explicitly listed are ignored. Integration Guide Integration APIs PUBLIC 1019 OData Operation: POST Recommendations URI: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/ Recommendations Operation Type: C (Create) HTTP Method: POST Permissions: Business catalog role SAP_COM_CSR_0021 Request As previously mentioned, the Recommendation entity can only be called using an HTTP POST call. The call mimics an OData deep-create call. Other calls to the Recommendation entity are not supported. (such as GET entity/set, and so on). Note To improve readability, the following example HTTP requests and responses do not show all the details. Some metadata information is for example omitted in the JSON responses and URLs are shown without encoding. For example, spaces are not replaced by %20 Example Sample Code POST /sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/Recommendations Request Headers: accept application/json content-type application/json X-CSRF-Token _oHVBAS9m4E95kbxqVV2ww== Request Body: { "UserOriginId": "ONLINE_SHOP", "UserId": "demo@hybris.com", "RecommendationScenarioId": "ORI_SCENARIO", "BasketObjects": [], "LeadingObjects": [], "ContextParams": [{ "ContextId": 1, "Value": "EN", "Name": "P_LANGUAGE" }, { "ContextId": 2, "Value": "TOP", "Name": "P_POSITION" }], "Results": [] } Response Sample Code { "d": { "UserId": "", 1020 PUBLIC Integration Guide Integration APIs "UserOriginId": "", "RecommendationScenarioId": "", "BasketObject": null, "LeadingObjects": null, "ContextParams": null, "Results": { "results": [{ "OfferId": "0000004711", "Offer": "Offer 4711", "CustomerId": "demo@hybris.com", "ContentId": "00001", "CommunicationMediumId": "ONLINE_SHOP", "CommunicationMedium": "Online-shop", "LanguageId": "FR", "Language": "French", "Postion": "TOP", "ContentMediumTypeId": "01", "ContentMediumType": "Image", "ContentDescription": "Buy 2 get 1 free", "ContentSource": "http://assets.mycompany.com/ offer4711.png", "TargetDescription": "Link for offer 4711", "TargetLink": "http://www.mycompany.com/offer4711.html", "Score": "1.00" }, { "OfferId": "0000004712", "Offer": "Offer 4712", "CustomerId": "", "ContentId": "00001", "CommunicationMediumId": "ONLINE_SHOP", "CommunicationMedium": "Online-shop", "LanguageId": "FR", "Language": "French", "Postion": "TOP", "ContentMediumTypeId": "01", "ContentMediumType": "Image", "ContentDescription": "20% off for order values > 100", "ContentSource": "http://assets.mycompany.com/ offer4712.png", "TargetDescription": "Link for offer 4712", "TargetLink": "http://www.mycompany.com/offer4712.html", "Score": "0.80" } ] } } } Sample Code Example request with coupon-parameter: "P_WITH_COUPON" POST /sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/Recommendations Request Headers: accept application/atom xml content-type application/json X-CSRF-Token _oHVBAS9m4E95kbxqVV2ww== Request Body: { "UserOriginId": "ONLINE_SHOP", "UserId": "demo@hybris.com", "RecommendationScenarioId": "ORI_SCENARIO", "BasketObjects": [], "LeadingObjects": [], "ContextParams": [{ Integration Guide Integration APIs PUBLIC 1021 "ContextId": 1, "Value": "EN", "Name": "P_LANGUAGE" }, { "ContextId": 2, "Value": "TOP", "Name": "P_POSITION" }, { "ContextId": 3, "Value": "X", "Name": "P_WITH_COUPON" }], "Results": [{ "AssignedCoupon": {} }] } Example response with coupon data ... <title type="text">Coupons('COUPON_FOR_MOBILE')</title> <updated>2017-09-08T14:29:37Z</updated> <category scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/ scheme" term="CUAN_OFFER_DISCOVERY_SRV.CouponEntityType"/> <link title="CouponEntityType" rel="self" href="Coupons('COUPON_FOR_MOBILE')"/> -<content type="application/xml"> -<m:properties> <d:Coupon>COUPON_FOR_MOBILE</d:Coupon> <d:CouponType>SINGLE</d:CouponType> <d:CouponName/> <d:CouponDescription/> </m:properties> </content> </entry> </m:inline> </link> -<content type="application/xml"> -<m:properties> <d:OfferId>0000000709</d:OfferId> <d:Offer>Test_Coupon_Offer</d:Offer> <d:InboundOriginIdExt/> <d:InboundOriginId/> <d:ContentId>00001</d:ContentId> <d:CommunicationMediumId>MOBILE_APP</d:CommunicationMediumId> <d:CommunicationMedium>Mobile Anwendung</d:CommunicationMedium> <d:LanguageId>EN</d:LanguageId> <d:Language>Englisch</d:Language> <d:Position>Bottom</d:Position> <d:ContentMediumTypeId>01</d:ContentMediumTypeId> <d:ContentMediumType>Bild</d:ContentMediumType> <d:ContentDescription>http://i.imgur.com/crDskHz.png</d:ContentDescription> <d:ContentSource>http://i.imgur.com/crDskHz.png</d:ContentSource> <d:TargetDescription/> <d:TargetLink/> <d:FC_ContentPosition>0</d:FC_ContentPosition> <d:FC_ContentMediumTypeId>0</d:FC_ContentMediumTypeId> <d:FC_ContentDescription>0</d:FC_ContentDescription> <d:FC_ContentSource>0</d:FC_ContentSource> <d:FC_TargetDescription>0</d:FC_TargetDescription> <d:FC_TargetLink>0</d:FC_TargetLink> <d:Score>1.00000</d:Score> </m:properties> </content> </entry> ... 1022 PUBLIC Integration Guide Integration APIs Request Headers Recommendations Request Headers Header Content-Type Accept X-CSRF-Token Required Yes Yes Yes Description Recommended value: application/json Recommended value: application/json To be retrieved by the caller before calling the Recommendations API, for example using a GET call on https:// <Server>:<Port>/sap/opu/odata/SAP/ CUAN_OFFER_DISCOVERY_SRV/using the HTTP Header "X-CSRFToken" with the value "fetch" Recommendations Response Headers Header Content-Type Description Returned value: application/json Recommendations Status and Error Codes Code 201 400 Reason Recommendations call was successfully processed. There was an error processing the request. See the response for detailed error information. Discover Coupons OData Operation: GET GetCouponCode URI: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/GetCouponCode Operation Type: R (Read) HTTP Method: GET Permissions: Business catalog role SAP_COM_CSR_0021 When Discovery and Recommendation returns Offer with Coupon information, then the user receives just the Coupon root information. To get a redeemable coupon code a second request is necessary. Therefore, this OData Function Import has been defined. This OData API endpoint is used to fetch coupon codes for a coupon that was retrieved by a POST call on the Recommendations entity set using the "AssignedCoupon" navigational property in the request (see above). In order to retrieve coupon codes for anonymous contacts, the parameters UserId and UserOriginId must be provided with empty values (&UserId=''&UserOriginId=''). Integration Guide Integration APIs PUBLIC 1023 Note Anonymous contacts can only receive coupon codes of coupons with contact relationship type "No Contact Assigned". For more information, see Manage Coupons. Example Request GET /sap/opu/odata/sap/CUAN_OFFER_DISCOVERY_SRV/GetCouponCode? Coupon='COUPON_FOR_MOBILE'&UserId='demo@hybris.com'&UserOriginId='ONLINE_SHOP' Example Response (JSON) Sample Code { "d" : { "CouponCode" : "CODE_1234", "EANCodeImageUrl" : "https://yourdomain.com/url_to_eancode/1234", "QRCodeImageURL" : "https://yourdomain.com/url_to_qrcode/1234", "ValidityStartDateTime" : "\/Date(1527235508173)\/", "ValidityEndDateTime" : "\/Date(1527717599000)\/", "CouponCodeSerialNumber" : "1234" } } Request Headers Recommendations Request Headers Header Accept Required No Description Recommended value: application/json Recommendations Response Headers Header Content-Type Description Returned value: application/json Recommendations Status and Error Codes Code 200 4xx Reason Recommendations call was successfully processed. There was an error processing the request. See the response for detailed error information. OData Operation: POST GetCouponCodes URI: https://<Server>:<Port>/sap/opu/odata/SAP/CUAN_OFFER_DISCOVERY_SRV/ GetCouponCodes 1024 PUBLIC Integration Guide Integration APIs Operation Type: R (Read) HTTP Method: POST Permissions: Business catalog role SAP_COM_CSR_0021 This mass-enabled OData Coupon Code API is used to fetch redeemable coupon codes for multiple users. The number of users can be adjusted or may have to be reduced according to the system load, computing and storage capacity. Note Anonymous contacts can only receive coupon codes of coupons with contact relationship type No Contact Assigned. For more information, see Manage Coupons Example Request POST /sap/opu/odata/sap/CUAN_OFFER_DISCOVERY_SRV/GetCouponCodes Example Request Body (JSON) Sample Code { "Coupon": "Coupon_1", "to_CouponCodeContacts":[ { "UserId":" name.surname@company.com", "UserOriginId":"EMAIL" } ] } Example Response (JSON) Sample Code { "d" : { "Coupon" : "Coupon_1", "to_CouponCodeContacts" : { "results" : [ { "Coupon" : "Coupon_1", "CouponCodeSerialNumber" : "SERIAL-NUMBER-007", "ValidityEndDateTime" : "\/Date(1610578799000)\/", "ValidityStartDateTime" : "\/Date(1606728581000)\/", "QRCodeImageURL" : "https://yourdomain.com/url_to_qrcode/007", "EANCodeImageUrl" : "https://yourdomain.com/url_to_eancode/007", "CouponCode" : "SAMPLE-CODE-007", "UserOriginId" : "EMAIL", "UserId" : "name.surname@company.com" } ] } { Request Headers Recommendations Request Headers Integration Guide Integration APIs PUBLIC 1025 Header Accept Required No Description Recommended value: application/json Recommendations Response Headers Response Header contains error messages with information about users which could not receive coupon codes. There could be many reasons, for example a user is not in the offer target group, a user has already redeemed the coupon code, the coupon, the coupon code or the offer is no longer valid. Header Content-Type Description Returned value: application/json Recommendations Status and Error Codes Code 200 4xx Reason Coupon codes were retrieved successfully. There was an error processing the request. See the response for detailed error information. 5.6.8 Coupons Public OData API (API_MKT_COUPON_SRV) for Coupons. Overview [page 1026] Entity Sets Coupons [page 1028] CouponCodes [page 1029] CouponTexts [page 1030] CouponCodeUsages [page 1030] CouponCodeUsageIntactnCntcts [page 1031] Overview The public API for Coupons supports operations on the Coupons Business Object. OData Version Root URI Service Metadata URI 2.0 https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_COUPON_SRV https://<Server>:<Port>/sap/opu/odata/SAP/ API_MKT_COUPON_SRV/$metadata 1026 PUBLIC Integration Guide Integration APIs Authorizations Communication Scenario ID Component for Incidents Field Extensibility Supported The following business catalog is required: SAP_CEC_BC_MKT_API_COP_PC SAP_COM_0317 CEC-MKT-OFM-CPM (Coupons) Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. Yes 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=0003/$me tadata?sap-documentation=all Only for internal access. You need to provide the server and port names. Marketing - Coupons 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. Coupons API General access link takes you directly to the Coupons 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 Integration Guide Integration APIs PUBLIC 1027 Entity Sets The Coupons OData API provides the following entities: Entity Set Coupons CouponCodes CouponTexts CouponCodeUsages CouponCodeUsageIn tactnCntcts Description Path This entity contains cou pon data /Coupons This entity contains the /CouponCodes coupon codes of coupons This entity contains the coupon texts of coupons /CouponTexts This entity contains the /CouponCodeUsages coupon code usage of cou pons This entity contains the contact and contact origin of a coupon code usage /CouponCodeUsageIntactnCntcts The service supports OData deep create functionality to create a tree of related entities in a single POST request. The service also supports $batch to group any number of arbitrary requests into one request. You can view sample payloads and test the API at https://api.sap.com . Coupons Resource Path: /Coupons You can perform the following operations on the Coupons entity set: Operations on Coupons entity set HTTP Method Description GET Get a list of coupons Note The $top parameter is mandatory. You can get only 100 coupons with each request. Path /Coupons? $top=<Number_Of_Objects> POST Get the details of a specific coupon Create a coupon /Coupons(guid'<Coupon UUID>') /Coupons 1028 PUBLIC Integration Guide Integration APIs HTTP Method PUT Description Update a coupon Note The CouponCanExceedOfferPeriod property can be set to TRUE only for a Released offer. Path /Coupons(guid'<Coupon UUID>') DELETE Delete a coupon /Coupons(guid'<Coupon UUID>') CouponCodes Resource Path: /CouponCodes You can perform the following operations on the CouponCodes entity set: Operations on CouponCodes entity set HTTP Method Description GET Get all the coupon codes for a specific coupon Note The $top parameter is mandatory. You can get only 100 coupons codes with each re quest. Path /Coupons(guid'<Coupon UUID>')/ CouponCodes Get the coupon codes of a specific coupon Get a list of coupon codes Get the coupon of a specific coupon code POST Create a coupon code PUT Update a coupon code DELETE Delete a coupon code /CouponCodes(guid'<Coupon Code UUID>') /CouponCodes? $top=<Number_Of_Objects> /CouponCodes(guid'<Coupon Code UUID>')/to_Coupon /Coupons(guid'<Coupon UUID>')/ to_CouponCode /CouponCodes(guid'<Coupon Code UUID>') /CouponCodes(guid'<Coupon Code UUID>') Integration Guide Integration APIs PUBLIC 1029 CouponTexts Resource Path: /CouponTexts You can perform the following operations on the CouponTexts entity set: Operations on CouponTexts entity set HTTP Method Description GET Get all the coupon texts Note If the path is /CouponTexts, the $top parameter is mandatory. You can get only 100 coupons texts with each re quest. Path /Coupons(guid'<Coupon UUID>')/ CouponTexts Get the coupon texts of a specific coupon Get a list of coupon texts Get the coupon of a specific coupon text POST Create a coupon text PUT Update a coupon text DELETE Delete a coupon text /CouponTexts(guid'<Coupon Text UUID>') /CouponTexts? $top=<Number_Of_Objects> / CouponTexts(CouponUUID=guid'<Cou pon UUID>',Language=guid'<Language>' )/to_Coupon /Coupons(guid'<Coupon UUID>')/ to_CouponText /CouponTexts(guid'<Coupon Text UUID>') /CouponTexts(guid'<Coupon Text UUID>') CouponCodeUsages Resource Path: /CouponCodeUsages You can perform the following operations on the CouponCodeUsages entity set: 1030 PUBLIC Integration Guide Integration APIs Operations on CouponCodeUsages entity set HTTP Method Description GET Get all the coupon code usages for a coupon code Note The $top parameter is mandatory. You can get only 100 coupon code usages with each request. Path /CouponCodes(guid'<Coupon Code UUID>')/to_CouponCodeUsage Get a specific coupon code usage Get a list of coupon code usages Get the coupon code for a specific coupon code usage /CouponCodeUsages(guid'<Coupon Code Usage UUID>') /CouponCodeUsages? $top=<Number_Of_Objects> /CouponCodeUsages(guid'<Coupon Code Usage UUID>')/to_CouponCode CouponCodeUsageIntactnCntcts Resource Path:/CouponCodeUsageIntactnCntcts You can perform the following operations on the CouponCodeUsageIntactnCntcts entity set: Operations on CouponCodeUsageIntactnCntcts entity set HTTP Method Description GET Get all the contacts and contact origins for a specific cou pon code usage Path /CouponCodeUsages(guid'<Coupon Code UUID>')/to_Contacts Note The $top parameter is mandatory. You can get only 100 contacts and contact origins with each request. Get the contact and contact origin for a specific interaction contact / CouponCodeUsageIntactnCntcts(In teractionContactFacetUUID=guid' <Interaction Contact Facet UUID>',InteractionContactUUID=g uid'<Interaction Contact UUID>') Get a list of interaction contacts and contacts origins used in /CouponCodeUsageIntactnCntcts? coupon code origins $top=<Number_Of_Objects> Integration Guide Integration APIs PUBLIC 1031 Implementation Hints When calling this API, please observe the following recommendations: It is not possible to update a specific coupon or any of its child objects (codes, texts) using parallel requests because each update request locks the coupon object and all its child objects. Therefore it is not possible to upload coupon codes for the same coupon in parallel requests. The requests must be serialized by the caller. The recommended maximum package size for uploading multiple coupon codes in a single $batch request is 1,000. Larger package sizes can have a negative influence on other processes on the system. The preferred package size is 500 codes per $batch request. The expected average throughput for uploading coupon codes using these package sizes is between 1,200 and 1,800 codes/minute. Function Imports Function imports are used to perform custom operations on an entity, in addition to typical OData operations. This section contains function import payload examples for some functions of the process automation. HTTP Method POST Description Release a coupon. Sets the status from In Process (01) to Released (02). Reject a coupon. Sets the status from Released (02) to In Process (01). Deletes all codes of a coupon. To be used for efficient dele tion of all codes in large multi-code coupons. Trigger the replication of the coupon to an external system and request a number of coupon codes from the external system. 0 is a valid value for NumberOfCouponCodes and the value to be used for single-code coupons. Path /ReleaseCoupon? CouponUUID=guid'<Coupon UUID>' /RejectCoupon? CouponUUID=guid'<Coupon UUID>' /DeleteCodes? CouponUUID=guid'<Coupon UUID>' /ReplicateCoupon? CouponUUID=guid'<Coupon UUID>'&NumberOfCouponCodes=<Numb er of codes to be requested from external system> Related Information https://api.sap.com 5.7 Marketing Analytics 1032 PUBLIC Integration Guide Integration APIs 5.7.1 Import Analytical Data for Marketing Executive KPI You can import analytical data from an external system for Marketing Executive for specific KPIs, for example, market share, net promoter score, or brand awareness, which come from external marketing research and survey institutes. Note that the Marketing Executive Dashboard is obsolete as of release 2011. However you can use an OData API as described in the following sections to import the data and build custom CDS views, operational reports, or analytical stories.. Using the Web Service For the import, you can use the ODATA service CUAN_ANALYTIC_FND. The data model is structured in entity types as follows: KPIImport Provides administrative and logging information about the import MarketingEffectivenessData Enter the KPI data for the following KPIs: Brand Awareness Market Share Net Promoter Score (NPS) Leads Return on Marketing Investment (ROMI) Sales Forecast, Revenue Opportunities Sales Pipeline Converted Pipeline Pipeline Acceleration WebDownloadData Use it for KPI data about web downloads WebVisits Use it for KPI data about web visits For the import of KPI Data, specify the parent entity KPIImport. Use the depending entity of MarketingEffectivenessData, WebDownloads, or WebVisits to list your KPI Data. Using the OData API Use the OData API as follows: Request URI: /sap/opu/odata/sap/CUAN_ANALYTIC_FND_SRV/KPIImports Use HTTP Method: POST Integration Guide Integration APIs PUBLIC 1033 In addition, consider the following: See the next section for an example of an HTTP request body in the JSON format. To use this example in the POST request, set the HTTP header parameter Content-Type = application/json and Accept = application/json. You can also use different supported body formats. If the CSRF Token is necessary, you can request it from the web service using the HTTP method GET with the HTTP request header parameter X-CSRF-Token = Fetch set. Provide the user, and the password in the HTTP request header parameters. See the following source code in the JSON format about how to create two records for the analysis type "ROMI" Return on Marketing Investment: { "KPIImportGuid":"", "AnalysisTypeDescription":"", "FileName":"", "FileDescription":"", "ImportModeCode":"D", "ImportModeDescription":"", "ImportedById":"", "ImportedByName":"IMPORTUSER", "ImportedOn":"2015-06-10T00:00:00", "NumberOfImportedRecords":0, "MarketingEffectivenessData":[ { "AnalysisType":"ROMI", "Brand":"EST", "Audience":"Financial Services", "Country":"US", "Market":"", "Competitor":"", "ProductCategory":"", "Region":"", "Program":"", "Campaign":"", "SpendType":"", "CustomDimension1":"", "CustomDimension2":"", "CustomDimension3":"", "CustomDimension4":"", "CustomDimension5":"", "CustomDimension6":"", "CustomDimension7":"", "CustomDimension8":"", "CustomDimension9":"", "CustomDimension10":"", "KPIDate":"2015-04-01T00:00:00", "CurrentValue":"0.50", "TargetValue":"0", "Currency":"", "Factor":"1" }, { "AnalysisType":"ROMI", "Brand":"MON", "Audience":"Financial Services", "Country":"FR", "Market":"", "Competitor":"", "ProductCategory":"", "Region":"", "Program":"", "Campaign":"", "SpendType":"", "CustomDimension1":"", 1034 PUBLIC Integration Guide Integration APIs "CustomDimension2":"", "CustomDimension3":"", "CustomDimension4":"", "CustomDimension5":"", "CustomDimension6":"", "CustomDimension7":"", "CustomDimension8":"", "CustomDimension9":"", "CustomDimension10":"", "KPIDate":"2015-04-01T00:00:00", "CurrentValue":"0.50", "TargetValue":"0", "Currency":"", "Factor":"1" } ] } Entity Type KPIImport The entity type KPIImport describes the technical header of an import of marketing effectiveness data. The properties KPIImportGuid, ImportedById, ImportedByName, ImportedOn, and NumberOfImportedRecords are used for logging the external data request. Provide a new KPIImportGuid for every POST service request. Fill the ImportedByName property with a user ID. The ImportedOn, and NumberOfImportedRecords properties are maintained by default. The properties FIleName, and File Description are ignored. See the following table for the details of the structure of the entity type: Property Description Edm Core Type KPIImportGuid Guid created for every import re quest Edm.String AnalysisTypeId KPI specific Analysis Type Edm.String AnalysisTypeDe To be ignored scription Edm.String FileName To be ignored Edm.String FileDescription To be ignored Edm.String ImportModeCode Fill in the Code "D" for Delta Mode(Update + Insert) and "F" for Full Mode(Delete + Insert) Edm.String ImportModeDe scription To be ignored Edm.String ImportedById User Id Edm.String Max Length Key 32 X Nullable 50 50 255 1 60 12 Integration Guide Integration APIs PUBLIC 1035 Property Description Edm Core Type ImportedByName User name Edm.String ImportedOn Will be defaulted - Date and time which should be logged for the cur rent import. Example 1: 2002-10-10T17:00:00Z Edm.DateTimeOffset NumberOfImpor tedRecords Number of imported records will be calculated at import. Within the re quest, set it to "0" as it cannot be empty Edm.Int32 Max Length Key 80 Nullable FALSE Entity Type Marketing Effectiveness Data See the following table for the details of the structure of the marketing effectiveness data entity type: Property Description Edm Core Type AnalysisType KPI specific Analysis Type Edm.String Brand Brand of the data record Edm.String Audience Audience of the data record Edm.String Country Country of the data record Edm.String Market Market of the data record Edm.String Competitor Competitor of the data record Edm.String ProductCategory Product Category of the data record Edm.String Region Region of the data record Edm.String Program Program of the data record Edm.String Campaign Campaign of the data record Edm.String SpendType Spend Type of the data record Edm.String CustomDimen sion1 These attributes can be used for Edm.String Customer specific dimensions which are not part of the standard delivery Max Length Key X X X X X X X X X X X X 1036 PUBLIC Integration Guide Integration APIs Property Description Edm Core Type CustomDimen sion2 Edm.String CustomDimen sion3 Edm.String CustomDimen sion4 Edm.String CustomDimen sion5 Edm.String CustomDimen sion6 Edm.String CustomDimen sion7 Edm.String CustomDimen sion8 Edm.String CustomDimen sion9 Edm.String CustomDimen sion10 Edm.String KPIDate Date being used to assign the record to the time dimension, for example, calendar quarter. Example 1: 2002-10-10T17:00:00Z Edm.DateTime CurrentValue Represents numeric values with fixed precision and scale. Example 1: 2,345. Cannot be empty or null Edm.Decimal TargetValue Represents numeric values with fixed precision and scale. Example 1: 2,345. Cannot be empty or null Edm.Decimal Currency Should match the currency configured for SAP Marketing Cloud or it can be left empty Edm.String Max Length Key X X X X X X X X X X 18 18 Integration Guide Integration APIs PUBLIC 1037 Property Factor Description Edm Core Type Factor to quantify the weight of the data records for the calculation of the average value. A large value im plies that the value of this record has a high impact on the average. Can not be empty or null Edm.Decimal Max Length Key Entity Type Web Download Data See the following table for the details of the structure of the web download data entity type: Property Description Edm Core Type Country Country Edm.String Brand Brand Edm.String KPIDate Date being used to assign the record to the time dimension, for example, calen dar quarter. Example 1: 2002-10-10T17:00:00Z Edm.DateTime PDFs Number of PDFs Edm.Int32 Videos Number of Videos Edm.Int32 Audios Number of Audios Edm.Int32 Max Length Key X X X Entity Type Web Visit Data See the following table for the details of the structure of the web visit data entity type: Property Country Brand Description Country Brand Edm Core Type Edm.String Edm.String Max Length Key X X 1038 PUBLIC Integration Guide Integration APIs Property Description Edm Core Type KPIDate Date being used to assign the record to the time dimension, for example, calen dar quarter. Example 1: 2002-10-10T17:00:00Z Edm.DateTime Visits Number of Visits Edm.Int32 UniqueVisi Number of unique visits tory Edm.Int32 PageViews Number of Page views Edm.Int32 Max Length Key X AnalysisType See the following table for the values of the AnalysisType property that correlates to each KPI. KPI AnalysisType Property Other Recommended Properties Brand Aware ness BRAND_AWARENESS Country, Market, CustomDimensions, KPIDate, Current Value, Factor Brand Aware ness Competi tor BRAND_AWARENESS_COMPETITOR Country, Market, Competitor, CustomDimensions, KPI Date, CurrentValue, Factor Market Share MARKET_SHARE Country, Market, Brand, CustomDimensions, KPIDate, CurrentValue, Factor Market Share Competitor MARKET_SHARE_COMPETITOR Country, Market, Brand, Competitor, CustomDimensions, KPIDate, CurrentValue, Factor Net Promoter Score (NPS) NET_PROMOTER_SCORE Country, Market, CustomDimensions, KPIDate, Current Value, Factor Return on Mar keting Invest ment (ROMI) ROMI Country, Market, Audience, Brand, CustomDimensions, KPIDate, CurrentValue, Factor Leads DEMAND_GENERATION_LEADS Country, Market, Audience, Brand, CustomDimensions, KPIDate, CurrentValue, TargetValue Opportunities DEMAND_GENERATION_OPPORTUNITIES Country, Market, Audience, Brand, CustomDimensions, KPIDate, CurrentValue, TargetValue Integration Guide Integration APIs PUBLIC 1039 KPI AnalysisType Property Other Recommended Properties Pipeline Accel eration DEMAND_ACCELERATION Sales Pipeline PIPELINE_BUILD Converted Pipe PIPELINE_COVERAGE line Revenue REVENUE Sales Forecast SALES_FORECAST Web Downloads WEB_DOWNLOADS_2 Web Visits WEB_VISITS_2 Country, Market, Audience, Brand, CustomDimensions, KPIDate, CurrentValue, TargetValue Country, Market, Audience, Brand, CustomDimensions, KPIDate, CurrentValue, Targetvalue Country, Market, Audience, Brand, CustomDimensions, KPIDate, CurrentValue, TargetValue Country, Market, Audience, Brand, CustomDimensions, KPIDate, CurrentValue, TargetValue Country, Market, Audience, Brand, CustomDimensions, KPIDate, CurrentValue, TargetValue Brand, Country, KPIDate, PDFs, Videos, Audios Brand, Country, KPIDate, Visits, UniqueVisits, PageViews In addition to the property AnalysisType, provide the data for the properties relevant for the KPIs. The dimension Market is derived from the dimension Country. As an alternative, you can provide the dimension Market without an assignment to the dimension Country. You can specify 10 custom attributes as CUSTOM_FIELD1 ... CUSTOM_FIELD10, to enable custom dimensions for the drill-down and filtering in analytical reporting. Specify the values with a particular date. The date is relevant for the year-to-date calculation. For example, if the current date is 30.6, the analysis time frame of the year-to-date in 2015 is 01.01.2015 - 30.6.2015. In this case, only values with a date before or on 30.6. are considered. 5.8 Marketing Planning and Performance 1040 PUBLIC Integration Guide Integration APIs 5.8.1 Actual and Committed Spend Data You can upload actual and committed spend data from an external ERP system into SAP Marketing Cloud using the CUAN_ACTUAL_IMPORT_SRV OData service. Prerequisites You have assigned the Marketing - Business Data Integration communication scenario to your communication user in Maintain Communication Users. You have maintained the SICF node for the CUAN_ACTUAL_IMPORT_SRV external service name in SAP Marketing Cloud (which is either a back-end system or a remote gateway system, depending on your setup). Mass Import The OData protocol allows the import or update of one object record (one spend item) only. To achieve the mass create and mass update of records, a dummy entity (import header) is created by deep insert. You perform an insert on the ImportHeader entity and create actual spend items as subnodes of the import header. The metadata of the service is read by means of the OData call: Request URL: /sap/opu/odata/sap/CUAN_ACTUAL_IMPORT_SRV/$metadata HTTP Method: Get Structure of CUAN_ACTUAL_IMPORT_SRV OData Service The CUAN_IMPORT_SRV OData service consists of the following entity sets and entity types: Entity Set CampaignActual ImportHeader Entity Type CampaignActual ImportHeader Entity Type Description Actual Spends Technical Import Message Header ImportHeader Entity Type The ImportHeader entity type describes the technical header of an import of actual spends. The property ID is used as an external reference number to identify the associated application log. Integration Guide Integration APIs PUBLIC 1041 ImportHeader Meta Information Property Description Edm Core Type Maximum Length Mandatory Key ID Used as an exter Edm.String 100 No Yes nal reference num ber in the applica tion log CampaignActual Entity Type The CampaignActual entity type contains all attributes that are required to upload actual spend data. If the values for a combination of source ID, campaign ID, spend type, spend item ID, and reference date are being uploaded for the first time, the corresponding values for this combination (amounts and currency) from the HTTP request are uploaded. If they are being uploaded a subsequent time, the corresponding values for this combination are updated with the values from the HTTP request. Actual and committed spend can be created at any level. You are responsible to create data at the level that is relevant for your campaign and your business processes. For example, you can create data at the following levels: Campaign level Campaign and spend level Campaign and spend item level CampaignActual Meta Information Property Description Edm Core Type Maximum Length Mandatory Key SourceID The source ID indi Edm.String 30 No Yes cates the origin of the spend informa tion. CampaignID Campaigns have Edm.String 10 been created in the Campaigns, Programs, or Marketing Plans applications. Yes Yes SpendType Spend types have Edm.String 10 been defined in the Spend Type config- uration applica tion. No Yes 1042 PUBLIC Integration Guide Integration APIs Property Description Edm Core Type Maximum Length Mandatory Key SpendItemID If specified, the Edm.String 10 spend item ID must exist in the campaign and the spend type must match. If no spend type is specified, the spend type will be derived from the spend item of the campaign. No Yes ReferenceDate The date that is used for currency conversion. The reference date must be a valid date in the follow ing format "YYYYMMDDT00:00:00". Edm.DateTime Yes Yes WBSElementID The WBS Element Edm.String 24 No No ID is only used in ternally by SAP Currency Currency for the Edm.String 5 spend amount. Yes No ActualSpend Actual costs that Edm.Decimal 15,2 No No have been incurred from marketing activities. CommittedSpend The amount of al Edm.Decimal 15,2 No No ready known spend based on existing requests and orders for an item, for example, from a purchasing system. Integration Guide Integration APIs PUBLIC 1043 Importing Actual Spend Data Using OData Service For the input file, the following applies: If the values for a combination of source ID, campaign ID, spend type, spend item ID, and reference date are being uploaded for the first time, the corresponding values for this combination (amounts and currency) from the local file are uploaded. If they are being uploaded a subsequent time, the corresponding values for this combination are updated with the values from the new local file. A period (.) must be used to separate decimals in amounts. If a field is optional and you do not want to include a value for it in the file, you still need to insert a comma (,) in place of the excluded value. Actual and committed spend can be uploaded at any level. You are responsible for uploading data at the level that is relevant for your campaign and your business processes. For example, you can upload data at the following levels: Campaign level Campaign and spend level Campaign and spend item level If there is invalid data in the local file, no actual and committed spend amounts are uploaded and saved. To upload actual spend data, the ImportHeader and CampaignActual entity types are required. Example Request URL: /sap/opu/odata/sap/cuan_actual_import_srv/ImportHeaders HTTP Method: Post Example request: { "Id": "Example-01", "CampaignActuals": [ { "SourceId": "", "CampaignId": "40144", "SpendType": "", "SpendItemId": "1", "ReferenceDate": "2015-11-30T00:00:00", "Currency": "USD", "ActualSpend": "50000.00", "CommittedSpend": "30000.00" }, { "SourceId": "", "CampaignId": "40144", "SpendType": "", "SpendItemId": "2", "ReferenceDate": "2015-11-30T00:00:00", "Currency": "USD", "ActualSpend": "10000.00", "CommittedSpend": "10000.00" } ] } Success Message 1044 PUBLIC Integration Guide Integration APIs After a successful upload of the actual spend data, the status of the HTTP response is 201 Created and the following success message is provided: <?xml version="1.0" encoding="utf-8"?> <entry xml:base="https://wdciwe1.wdf.sap.corp:11100/sap/opu/odata/sap/ cuan_actual_import_srv/" xmlns="http://www.w3.org/2005/Atom" xmlns:m="http:// schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http:// schemas.microsoft.com/ado/2007/08/dataservices"> <id>https://wdciwe1.wdf.sap.corp:11100/sap/opu/odata/sap/ cuan_actual_import_srv/ImportHeaders('Example-01')</id> <title type="text">ImportHeaders('Example-01')</title> <updated>2015-12-01T13:44:21Z</updated> <category term="CUAN_ACTUAL_IMPORT_SRV.ImportHeader" scheme="http:// schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> <link href="ImportHeaders('Example-01')" rel="self" title="ImportHeader"/> <link href="ImportHeaders('Example-01')/CampaignActuals" rel="http:// schemas.microsoft.com/ado/2007/08/dataservices/related/CampaignActuals" type="application/atom+xml;type=feed" title="CampaignActuals"> <m:inline/> </link> <content type="application/xml"> <m:properties> <d:Id>Example-01</d:Id> <d:Timestamp>2015-12-01T13:44:21.5450340</d:Timestamp> <d:UserName>USERNAME</d:UserName> <d:SourceSystemType/> <d:SourceSystemId/> </m:properties> </content> </entry> Error Handling If the request fails due to some errors, the complete HTTP request is rejected and errors must be corrected before uploading again. In case of errors, the status of the HTTP response is 400 Bad Request. You can also find all messages using the Application Log application, entering CUAN_IMPORT as a category and CUAN_ACTUAL_IMPORT as a subcategory. Component for Incidents CEC-MKT-MSM 5.8.2 Marketing Programs Public OData API (API_MKT_PROGRAM) for reading, updating and creating marketing program data. Entity Data Model The following diagram shows the entity data model for program and its media type spend. Integration Guide Integration APIs PUBLIC 1045 Technical Data Name of the Service Authorizations 1046 PUBLIC API_MKT_PROGRAM The following business catalog role is required: SAP_BCR_CEC_MKT_API_PGM_PC Integration Guide Integration APIs Communication Scenario ID Component for Incidents OData Version Root URI Service Metadata URI Field Extensibility Supported SAP_COM_0320 CEC-MKT-PGM Note Not to be used for HTTP errors. For more information, see HTTP Response Status Codes [page 408]. 2.0 https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_PROGRAM_SRV/ https://<Server>:<Port>/sap/opu/ odata/SAP/API_MKT_PROGRAM_SRV/$metadata Only the Program entity is enabled for extension. 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_PROGRAM_SRV;v=0002/$metadata?sapdocumentation=all Marketing - Programs Details Page Marketing Programs API Remarks Only for internal access. You need to provide the server and port names. General access to the Details page of the service on SAP API Hub. One-time registration 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. General access to the Marketing Programs metadata file. One-time registration or logon is required. Please note the meaning of the following values in the file: Integration Guide Integration APIs PUBLIC 1047 Metadata Value in XML sap:updatable sap:creatable nullable Meaning When FALSE read-only field read-only field mandatory field 5.8.2.1 Basic Concepts The public API for Marketing Programs API_MKT_PROGRAM_SRV supports operations on the Marketing Program Business Object. Processing Info 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. 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. Best Practices You can view sample payloads and test the API at https://api.sap.com/ . 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 SAP Marketing Cloud, the HTTP status code 201 or 204 is returned. Field Extensibility In addition to the pre-delivered attributes, you can add customer-specific fields using the Custom Fields app. The Program entity is the only entity that is enabled for extension. For more information, see Custom Fields. 1048 PUBLIC Integration Guide Integration APIs Please enable the Data Source under UIs and Reports: API_MKT_PROGRAM_SRV 0002. 5.8.2.2 Structure of OData Service API_MKT_PROGRAM This document describes the structure of the Public OData API API_MKT_PROGRAM_SRV. Make sure you read the Basic Concepts topic before you start. Entity Sets The Programs OData API provides the following entities: Entity Program HeaderProposedSpend ProgramPhase MediaTypeSpend MediaTypeTimeSplit Description Path This entity contains program header data. Read and create functionalities are supported. /Programs This entity provides informa tion about the proposed spend entered at the program plan level. Only read functionalities are supported. /HeaderProposedSpends This entity provides informa tion about the name and the validity period of the program phase. Only read functionali ties are supported. /ProgramPhases This entity provides informa tion about the different media types used for the program, their validity period, and their possible assignment to a pro gram phase. Create, read, up date functionalities are sup ported. /MediaTypeSpends This entity provides the pro posed spend for each media type on a monthly level. Read and update functionalities are supported. /MediaTypeTimeSplits Integration Guide Integration APIs PUBLIC 1049 Program Resource Path:/Programs You can perform the following operations on the Program entity set: Operations on Program Entity Set HTTP Method Description GET Get a list of programs. Get specific program information. POST Create a program. PATCH Edit program entities. Path /Programs /Programs(<MarketingProgramUUID>) /Programs /Programs(<MarketingProgramUUID>) HeaderProposedSpend Resource:/HeaderProposedSpend You can perform the following operations on the HeaderProposedSpend entity set: Operations on HeaderProposedSpend Entity Set HTTP Method Description Path GET Get a list of header proposed spend. /HeaderProposedSpends Get specific header proposed spend in /HeaderProposedSpends(<Marketing formation. ProgramPlngDataUUID>) Get header proposed spend for a spe cific program. /Programs(<MarketingProgra mUUID>)/ProgramHeaderProposed Spend PATCH Edit header proposed spend entities. /HeaderProposedSpends(<Marketing ProgramPlngDataUUID>) ProgramPhase Resource Path:/ProgramPhases You can perform the following operations on the ProgramPhases entity set: 1050 PUBLIC Integration Guide Integration APIs Operations on ProgramPhases Entity Set HTTP Method Description Path GET Get a list of program phases. /ProgramPhase Get specific program phase informa tion. /ProgramPhases(<MarketingProgram PhaseUUID>) Get program phases for a specific pro /Programs(<MarketingProgra gram. mUUID>)/Phase MediaTypeSpend Resource Path:/MediaTypeSpends You can perform the following operations on the MediaTypeSpends entity set: Operations on MediaTypeSpends Entity Set HTTP Method Description Path GET Get a list of media type spends. /MediaTypeSpends Get specific media type spend informa /MediaTypeSpends(<MarketingProg tion. ramMediaTypeUUID>) Get media type spends for a specific program. /Programs(<MarketingProgra mUUID>)/ProgramMediaTypeSpend PUT/ PATCH/MERGE POST Update specific media type spend. /MediaTypeSpends(<MarketingProg ramMediaTypeUUID>) Create media type spend for a specific /MediaTypeSpends program. MediaTypeTimeSplit Resource Path:/MediaTypeTimeSplits You can perform the following operations on the MediaTypeTimeSplits entity set: Operations on MediaTypeTimeSplits Entity Set HTTP Method Description Path GET Get a list of media type time splits. /MediaTypeTimeSplits Integration Guide Integration APIs PUBLIC 1051 HTTP Method PUT/PATCH/MERGE Description Path Get media type time split information for a specific year and month. /MediaTypeTimeSplits(<Marketing ProgramMediaTypeUUID >,<Calendar Year>,<CalendarMonth>) Get media type time splits for a specific /MediaTypeSpends(<MarketingProg media type. ramMediaTypeUUID>)/TimeSplit Update media type time splits for a spe /MediaTypeTimeSplits(<Marketing cific media type. ProgramMediaTypeUUID>,<Calendar Year>,<CalendarMonth>) 5.8.2.3 Payload Examples The following examples show how you can use the Programs API. Update Monthly Proposed Spend MERGE and PATCH The following example is a request without batch: Sample Code MediaTypeTimeSplits(MarketingProgramMediaTypeUUID=guid'6C0B84B7-5523-1EE7A7B9-2CDC0AF8FECB',CalendarYear='2041',CalendarMonth='01') { "ProposedMktgSpendAmt" "MarketingProgramCurrency" } :"3000.00", :"USD" The following example is a request with batch: Sample Code --batch_d3de-e5db-e865 Content-Type: multipart/mixed; boundary=changeset_5cda-58b3-eea0 --changeset_5cda-58b3-eea0 Content-Type: application/http Content-Transfer-Encoding: binary MERGE MediaTypeTimeSplits(MarketingProgramMediaTypeUUID=guid'6C0B84B7-5523-1EE7A7B9-2CDC0AF8FECB',CalendarYear='2041',CalendarMonth='01') HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 1052 PUBLIC Integration Guide Integration APIs sap-cancel-on-close: true Content-Type: application/json Content-Length: 250 { "ProposedMktgSpendAmt" : "10000.00", "MarketingProgramCurrency" : "USD" } --changeset_5cda-58b3-eea0-- --batch_d3de-e5db-e865-- MERGE The following example is a request with batch: Sample Code --batch_d3de-e5db-e865 Content-Type: multipart/mixed; boundary=changeset_5cda-58b3-eea0 --changeset_5cda-58b3-eea0 Content-Type: application/http Content-Transfer-Encoding: binary MERGE MediaTypeTimeSplits(MarketingProgramMediaTypeUUID=guid'6C0B84B7-5523-1EE7- A7B9-2CDC0AF8FECB',CalendarYear='2041',CalendarMonth='01') HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true Content-Type: application/json Content-Length: 250 { "ProposedMktgSpendAmt" : "60000.00", "MarketingProgramCurrency" : "USD" } --changeset_5cda-58b3-eea0 Content-Type: application/http Content-Transfer-Encoding: binary MERGE MediaTypeTimeSplits(MarketingProgramMediaTypeUUID=guid'6C0B84B7-5523-1EE7- A7B9-2CDC0AF8FECB',CalendarYear='2041',CalendarMonth='02') HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true Content-Type: application/json Content-Length: 250 { "ProposedMktgSpendAmt" : "8000.00", "MarketingProgramCurrency" : "USD" } --changeset_5cda-58b3-eea0-- --batch_d3de-e5db-e865-- PUT The following example is a request without batch: Sample Code { Integration Guide Integration APIs PUBLIC 1053 "MarketingProgramMediaTypeUUID" : "6c0b84b7-5523-1ee7-a7b9-2cdc0af8fecb", "MarketingProgramUUID" : "6c0b84b7-5523-1ee7-a7b9-2cdc0af89ecb", "CalendarYear" : "2041", "CalendarMonth" : "01", "ProposedMktgSpendAmt" : "30000.00", "MarketingProgramCurrency" : "USD" } Create Program POST The following example is a request without batch: Sample Code { "MarketingProgramName" : "New Product Launch A", "MarketingProgramMarketingArea" : "GLOBAL", "MarketingProgramValidFromDate" : "2041-01-01T00:00:00", "MarketingProgramValidToDate" : "2041-02-06T00:00:00", "MarketingProgramCurrency" : "USD" } Create MediaTypeSpend POST The following example is a request without batch: Sample Code { "MarketingProgramUUID" : "6c0b84b7-5523-1ed8-accc-2c4f6f612f18", "MarketingProgramMediaType" : "TV", "MktgProgramMediaTypeStartDate" : "2018-09-08T00:00:00", "MktgProgramMediaTypeEndDate" : "2018-09-20T00:00:00" } Update MediaTypeSpend MERGE and GET The following example is a request with batch: Sample Code --batch_d3de-e5db-e865 1054 PUBLIC Integration Guide Integration APIs Content-Type: multipart/mixed; boundary=changeset_5cda-58b3-eea0 --changeset_5cda-58b3-eea0 Content-Type: application/http Content-Transfer-Encoding: binary MERGE MediaTypeSpends(MarketingProgramMediaTypeUUID=guid'6C0B84B7-5523-1EE7A7B9-2CDC0AF8FECB') HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true Content-Type: application/json Content-Length: 250 { "MarketingProgramMediaType" : "PRINT", "MktgProgramMediaTypeStartDate" : "2041-01-02T00:00:00", "MktgProgramMediaTypeEndDate" : "2041-02-08T00:00:00" } --changeset_5cda-58b3-eea0---batch_d3de-e5db-e865 Content-Type: application/http Content-Transfer-Encoding: binary GET MediaTypeSpends(guid'6C0B84B7-5523-1EE7-A7B9-2CDC0AF8FECB') HTTP/1.1 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true --batch_d3de-e5db-e865-- MERGE and PATCH The following example is a request without batch: Sample Code { "MarketingProgramMediaType" : "RADIO", "MktgProgramMediaTypeStartDate" : "2041-01-03T00:00:00", "MktgProgramMediaTypeEndDate" : "2041-02-07T00:00:00" } PUT The following example is a request without batch: Sample Code { "MarketingProgramMediaTypeUUID" : "6c0b84b7-5523-1ee7-a7b9-2cdc0af8fecb", "MarketingProgramUUID" : "6c0b84b7-5523-1ee7-a7b9-2cdc0af89ecb", "MarketingProgramMediaType" : "RADIO", "MktgProgramMediaTypeStartDate" : "2041-01-03T00:00:00", "MktgProgramMediaTypeEndDate" : "2041-02-07T00:00:00", "MarketingProgramPhaseUUID" : "6c0b84b7-5523-1ee7-a7b9-2cdc0af8decb" } Integration Guide Integration APIs PUBLIC 1055 Get MediaTypeSpend GET The following example is with batch: Sample Code --batch_d3de-e5db-e865 Content-Type: application/http Content-Transfer-Encoding: binary GET MediaTypeSpends(guid'6C0B84B7-5523-1EE7-A7B9-2CDC0AF8FECB') HTTP/1.1 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true --batch_d3de-e5db-e865 Content-Type: application/http Content-Transfer-Encoding: binary GET MediaTypeSpends(guid'6C0B84B7-5523-1EE7-A7B9-2CF31AC53ECB') HTTP/1.1 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true --batch_d3de-e5db-e865 Content-Type: application/http Content-Transfer-Encoding: binary GET MediaTypeSpends(guid'6C0B84B7-5523-1EE7-A7B9-2CF31ABADECB') HTTP/1.1 HTTP/1.1 sap-contextid-accept: header Accept: application/json Accept-Language: en DataServiceVersion: 2.0 MaxDataServiceVersion: 2.0 sap-cancel-on-close: true --batch_d3de-e5db-e865-- Get all MediaTypeSpend for a Phase GET The following is an example without batch: Sample Code { "d": { "results": [ { "MarketingProgramMediaTypeUUID": "01234567-89ab- cdef-0123-456789abcdef", "MarketingProgramUUID": "01234567-89ab-cdef-0123-456789abcdef", "MarketingProgramMediaType": "string", 1056 PUBLIC Integration Guide Integration APIs "MediaTypeName": "string", "MktgProgramMediaTypeStartDate": "/Date(1492098664000)/", "MktgProgramMediaTypeEndDate": "/Date(1492098664000)/", "MarketingProgramPhaseUUID": "01234567-89ab-cdef-0123-456789abcdef", "MarketingProgramPhaseName": "string", "TimeSplit": { "results": [ { "MarketingProgramMediaTypeUUID": "01234567-89ab- cdef-0123-456789abcdef", "MarketingProgramUUID": "01234567-89ab-cdef-0123-456789abcdef", "CalendarYear": "string", "CalendarMonth": "string", "MktgSpendCalendarMonthName": "string", "MarketingProgramCurrency": "string", "ProposedMktgSpendAmt": "0" } ] } } ] } } 5.9 Custom Business Objects 5.9.1 Import of Data into Custom Business Object Import data into a Custom Business Object by using an OData service Prerequisites You are assigned the following catalog roles: SAP_BCR_CORE_EXT SAP_BCR_CORE_COM You have created a communication user for your custom communication scenario. Context When creating a custom business object you have the possibility to generate an OData service. This OData service can be assigned to a custom communication scenario. With the custom communication scenario a communication arrangement can be setup. For more information, see How to Create Custom Business Integration Guide Integration APIs PUBLIC 1057 Objects.Once you have a communication user assigned to this communication arrangement, the required data can be imported into the custom business object. Call OData Service You find the URL of your Custom Business Object's OData service in your communication arrangement. You can call the metadata document by adding $metadata through the URL. You insert data by using the POST method. To update data use the PATCH method and to delete data use the DELETE method. If you want to upload multiple data sets send a batch request. Related Information https://blogs.sap.com/2017/05/12/usage-of-odata-service-of-custom-business-object/ 5.10 Business Users The following synchronous inbound SOAP services are provided for setting up business users in SAP Marketing Cloud. MANAGEBUSINESSUSERIN QUERYBUSINESSUSERIN 5.10.1 Business User Technical name: MANAGEBUSINESSUSERIN This synchronous inbound SOAP service enables you to create, update, and delete business users from your external data sources, such as an identity management system. Deleting business users doesn't mean you've actually deleted them yet. The user assigned to the business user is deleted and the MarkedForArchivingIndicator has been set. This is the prerequisite for the ILM process that physically deletes business users. You can assign business role IDs to the users at the node Role. We recommend processing blocks of 10 users to a maximum of 100 users. Otherwise, the target system may time out. This service supports the business users Employee (BUP003) and Agency User (AGC001). Caution This service directly influences the data and authorizations of business users. Changes are effective immediately in the target system. Make sure to maintain only those authorizations that are intended for what a user needs to do in the system. Not doing so can cause security issues. 1058 PUBLIC Integration Guide Integration APIs Service Request The service is structured into the following two top-level nodes: Message Header (MessageHeader) The service message header is not in use in this service. Business User (BusinessUser) The service nodes contain the service's business data. Note In the following table, attributes are marked in blue. Nodes and Fields for the BusinessUser Node Node or Field PersonExternalID PersonID PersonUUID BusinessPartnerRoleCode Description Maximum Field Length Cardinality Person External ID 60 0..1 Mandatory for business partner category role BUP003 (Em ployee) at crea tion. Person ID 10 0..1 At least one of the person IDs is man datory. Person UUID 36 0..1 At least one of the person IDs is man datory. Business Partner 6 0..1 Role Code Only business partner role code BUP003 (Em ployee) is sup ported. This field is man datory. Integration Guide Integration APIs PUBLIC 1059 Node or Field MarkedForArchivingIndicator ValidityPeriod StartDate Cardinality: 0..1 EndDate PersonalInform ation Cardinality: 0..1 FormOfAddress FirstName LastName PersonFullName 1060 PUBLIC Description Maximum Field Length Cardinality Mark for Archiving 0..1 Set to True: The business user will be ar chived The actionCode [1] for User must be set to 02 Set to False: The business user will be re activated (Undo Ar chive) The actionCode [1] for User must be set to 02 Format: 0..1 YYYY-MM-DD By default, the sys tem date is set. Format: 0..1 YYYY-MM-DD By default, 9999-12-31 is set. Form of address 4 0..1 First name 40 0..1 Last name 40 0..1 This field is man datory. Person full name 80 0..1 Integration Guide Integration APIs Node or Field AcademicTitle CorrespondenceLanguage MiddleName AdditionalLastName BirthName NickName Initials AcademicSecondTitle LastNamePrefix LastNameSecondPrefix NameSupplement actionCode User(only for Cloud) Cardinality: 0..1 UserName LogonLanguageCode Description Maximum Field Length Cardinality Academic title 4 0..1 Correspondence 9 0..1 language Middle name 40 0..1 Additional last 40 0..1 name Birth name 40 0..1 Nick name 40 0..1 Initials 10 0..1 Academic second 4 0..1 title Last name prefix 4 0..1 Last name second 4 0..1 prefix Name supplement 4 0..1 You can use the 2 following values: 01 - Create 02 - Update 03 - Delete Mandatory if [2] is not set and per sonal information data are given. optional User name/Alias 40 0..1 Logon language 9 0..1 Integration Guide Integration APIs PUBLIC 1061 Node or Field DateFormatCode 1062 PUBLIC Description Maximum Field Length Cardinality You can use the 2 0..1 following values: 1DD.MM.YYYY (Gregorian Date) 2 - MM/DD/ YYYY (Gre gorian Date) 3 - MM-DDYYYY (Gre gorian Date) 4YYYY.MM.DD (Gregorian Date) 5YYYY/MM/D D (Gregorian Date) 6 - YYYY-MMDD (Gregorian Date, ISO 8601) 7GYY.MM.DD (Japanese Date) 8GYY/MM/DD (Japanese Date) 9 - GYY-MMDD (Japanese Date) AYYYY/MM/D D (Islamic Date 1) BYYYY/MM/D D (Islamic Date 2) Integration Guide Integration APIs Node or Field DecimalFormatCode TimeZoneCode TimeFormatCode LockedIndicator Description Maximum Field Length Cardinality CYYYY/MM/D D (Iranian Date) You can use the 2 0..1 following values: 1.234.567,89 X- 1,234,567.89 Y - 1 234 567,89 Time zone 10 0..1 You can use the 2 0..1 following values: 0 - 24 Hour Format (Ex ample: 12:05:10) 1 - 12 Hour Format (Ex ample: 12:05:10 PM) 2 - 12 Hour Format (Ex ample: 12:05:10 pm) 3 - Hours from 0 to 11 (Example: 00:05:10 PM) 4 - Hours from 0 to 11 (Example: 00:05:10 pm) Locked indicator 5 0..1 Integration Guide Integration APIs PUBLIC 1063 Node or Field Description Maximum Field Length Cardinality ValidityPeriod StartDate Format: 1 Cardinality: 1 YYYY-MM-DD If no start date is maintained for the User, the StartDate for the BusinessUser is entered. EndDate Format: 1 YYYY-MM-DD If no EndDate is maintained, it is set to 9999-12-31. Role RoleName Cardinality: 0..un actionCode bounded Role name 40 You can use the 2 following values: 01 - Create 03 - Delete Mandatory if [6] is not set and role name data is given. 1 optional actionCode You can use the 2 following values: 01 - Create 02 - Update 03 - Delete Mandatory if [3] is not set and user data (UserName and Role) are given. optional [6] roleListCompleteTransmissionIn dicator CTI for the Role node optional 1064 PUBLIC Integration Guide Integration APIs Node or Field Description Maximum Field Length Cardinality UserAssignment UserID (only for on-prem ise) actionCode Cardinality: 0..1 User ID 12 You can use the 2 following values: 01 - Create 02 - Update 03 - Delete Mandatory if [4] is not set and User ID data are given. 1 optional WorkplaceInfor EmailAddress Email address 241 0..1 mation PhoneInformati PhoneType Phone type 1 1 Cardinality: 0..1 on B - Business Cardinality: 0..2 C - Cell One set of phone CountryDialing Country dialing 10 0..1 information per Code code phone type sup ported. Used for both phone types. PhoneNumberAre Phone number 10 0..1 aID area code Used for phone type B only. PhoneNumberSub Phone number 30 0..1 scriberID subscriber ID Used for both phone types. PhoneNumberExt Phone number ex 10 0..1 ension tension Used for phone type B only. Integration Guide Integration APIs PUBLIC 1065 Node or Field Description Maximum Field Length Cardinality actionCode You can use the 2 following values: 01 - Create 02 - Update 03 - Delete Mandatory if [7] is not set and phone data is given. optional FunctionalTitleName Functional title 40 0..1 name Department Department name 40 0..1 RoomNumber Room number 10 0..1 Building Building name 10 0..1 actionCode You can use the 2 following values: 01 - Create 02 - Update 03 - Delete Mandatory if [5] is not set and work place information data is given. optional [7] phoneInformationListCompleteTr ansmissionIndicator CTI for the PhoneInformati on node optional [1] actionCode You can use the 2 following values: 01 - Create 02 - Update 03 - Delete This attribute is mandatory. optional [2] personalInformationListCompleteTransmissionIn dicator CTI for the PersonalInform ation node optional 1066 PUBLIC Integration Guide Integration APIs Node or Field Description Maximum Field Length Cardinality [3] userListCompleteTransmissionIndicator CTI for the User node optional [4] userAssignmentListCompleteTransmissionIndicat or CTI for the UserAssignment node optional [5] workplaceInformationListCompleteTransmissionI ndicator CTI for the WorkplaceInfor mation node optional Sample Payload Sample Code <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:aba="http://sap.com/xi/ABA"> <soapenv:Header/> <soapenv:Body> <aba:BusinessUserBundleMaintainRequest_sync> <!--1 or more repetitions:--> <BusinessUser actionCode="01" personalInformationListCompleteTransmissionIndicator="false" userListCompleteTransmissionIndicator="false" userAssignmentListCompleteTransmissionIndicator="false" workplaceInformationListCompleteTransmissionIndicator="false"> <PersonExternalID>Muster01</PersonExternalID> <BusinessPartnerRoleCode>BUP003</BusinessPartnerRoleCode> <PersonalInformation actionCode="01"> <FormOfAddress>0002</FormOfAddress> <FirstName>Max</FirstName> <LastName>Muster</LastName> <PersonFullName>Prof. Dr. Max Muster</PersonFullName> <AcademicTitle>0002</AcademicTitle> <CorrespondenceLanguage>D</CorrespondenceLanguage> <MiddleName>Michael</MiddleName> <AcademicSecondTitle>0001</AcademicSecondTitle> <BirthName>Milli</BirthName> <NickName>Maxi</NickName> <LastNamePrefix>0001</LastNamePrefix> </PersonalInformation> <User actionCode="01" roleListCompleteTransmissionIndicator="false"> <!--Optional:--> <UserName>MAXMUSTER01</UserName> <LogonLanguageCode>DE</LogonLanguageCode> <LockedIndicator>false</LockedIndicator> <Role actionCode="01"> <RoleName>SAP_BR_MANAGER</RoleName> </Role> <Role actionCode="01"> <RoleName>SAP_BR_BPC_EXPERT</RoleName> </Role> </User> <WorkplaceInformation actionCode="01" phoneInformationListCompleteTransmissionIndicator="true"> <EmailAddress>Max.Muster01@Test.com</EmailAddress> Integration Guide Integration APIs PUBLIC 1067 <PhoneInformation actionCode="01"> <PhoneType>C</PhoneType> <CountryDialingCode>+49</CountryDialingCode> <PhoneNumberSubscriberID>0160123456</ PhoneNumberSubscriberID> </PhoneInformation> <PhoneInformation actionCode="01"> <PhoneType>B</PhoneType> <CountryDialingCode>+49</CountryDialingCode> <PhoneNumberAreaID>06227</PhoneNumberAreaID> <PhoneNumberSubscriberID>7</PhoneNumberSubscriberID> <PhoneNumberExtension>12345</PhoneNumberExtension> </PhoneInformation> <FunctionalTitleName>TESTER</FunctionalTitleName> <Department>QUALITY</Department> <RoomNumber>C1.23</RoomNumber> <Building>WDF01</Building> </WorkplaceInformation> </BusinessUser> <BusinessUser actionCode="01" personalInformationListCompleteTransmissionIndicator="false" userListCompleteTransmissionIndicator="false" userAssignmentListCompleteTransmissionIndicator="false" workplaceInformationListCompleteTransmissionIndicator="false"> <PersonExternalID>MINIMUSTER01</PersonExternalID> <BusinessPartnerRoleCode>BUP003</BusinessPartnerRoleCode> <PersonalInformation actionCode="01"> <FormOfAddress>0001</FormOfAddress> <FirstName>Mini</FirstName> <LastName>Muster</LastName> <PersonFullName>Prof. Dr. Mini Muster</PersonFullName> <AcademicTitle>0002</AcademicTitle> <CorrespondenceLanguage>D</CorrespondenceLanguage> <AcademicSecondTitle>0001</AcademicSecondTitle> <LastNamePrefix>0001</LastNamePrefix> </PersonalInformation> <User actionCode="01" roleListCompleteTransmissionIndicator="false"> <!--Optional:--> <UserName>MINIMUSTER01</UserName> <LogonLanguageCode>DE</LogonLanguageCode> <LockedIndicator>false</LockedIndicator> <Role actionCode="01"> <RoleName>SAP_BR_MANAGER</RoleName> </Role> <Role actionCode="01"> <RoleName>SAP_BR_BPC_EXPERT</RoleName> </Role> </User> <WorkplaceInformation actionCode="01" phoneInformationListCompleteTransmissionIndicator="true"> <EmailAddress>Mini.Muster01@Test.com</EmailAddress> <PhoneInformation actionCode="01"> <PhoneType>C</PhoneType> <CountryDialingCode>+49</CountryDialingCode> <PhoneNumberSubscriberID>0160123456</ PhoneNumberSubscriberID> </PhoneInformation> <PhoneInformation actionCode="01"> <PhoneType>B</PhoneType> <CountryDialingCode>+49</CountryDialingCode> <PhoneNumberAreaID>06227</PhoneNumberAreaID> <PhoneNumberSubscriberID>7</PhoneNumberSubscriberID> <PhoneNumberExtension>12345</PhoneNumberExtension> </PhoneInformation> <FunctionalTitleName>TESTER</FunctionalTitleName> <Department>QUALITY</Department> <RoomNumber>C1.23</RoomNumber> 1068 PUBLIC Integration Guide Integration APIs <Building>WDF01</Building> </WorkplaceInformation> </BusinessUser> </aba:BusinessUserBundleMaintainRequest_sync> </soapenv:Body> </soapenv:Envelope> Service Response You receive a confirmation message response for each bundle of business users you send. If the service request is processed, a confirmation message is sent. This contain crucial information provided by the fields PersonExternalID, PersonID, and PersonUUID for each business user of the bundle. The following table provides an overview of the response structure for the BusinessUser service node. Field or Node Description Maximum Field Length Cardinality PersonExternalID Person External ID 60 0..1 PersonID Person ID 10 0..1 PersonUUID Person UUID 36 0..1 Log BusinessDocumentProcessingResu Not in use 2 0..1 Cardinality: 1 ltCode MaximumLogItemSeverityCode If several mes 1 0..1 sages are stored for a business user, the maxi mum of all re ceived severity co des the most se vere level will be shown. Item TypeID Message number 40 0..1 Cardinality: 0..un CategoryCode Not in use 15 0..1 bounded SeverityCode Severity code defi- 1 0..1 nition: 1 - Informa tion 2 - Warning 3 - Error Integration Guide Integration APIs PUBLIC 1069 Field or Node Error Codes Error Code 104 105 Note WebURI Description Maximum Field Length Cardinality Contains the mes 200 1 sage texts. Not in use 0..1 Description Combination of Ext. ID &1 and ID &2 inconsistent. Process ing cancelled. PersonExternalID and PersonID have a 1:1 relationship. Enter thePersonID that corresponds with the PersonExternalID. Combination of Ext. ID &1 and UUID &2 inconsistent. Person ExternalID and PersonUUID have a 1:1 relation ship. Enter thePersonUUID that corresponds with the PersonExternalID Constraints This service does not support: Service Performer (BBP005) business users Freelancer (BBP010) business users Additional Information Business User Note For more information about the API, choose the Details tab on the SAP API Business Hub. 5.10.2 Business User - Read Technical name: QUERYBUSINESSUSERIN 1070 PUBLIC Integration Guide Integration APIs This synchronous inbound SOAP service enables you to provision users from your external data source such as an identity management system. Service Request The service is structured into the following two top-level nodes: Business User (BusinessUser) The service node contains the search parameters. Nodes and Fields for the BusinessUser Node Field or Node Description Maximum Field Length PersonExternalIdI IntervalBoundaryT You can use the follow 1 nterval ypeCode ing values: Cardinality: 0..un bounded 1- Equal No upper boun dary value must be set. 3 - Between Upper boundary value is manda tory. 6 - Lower than Upper boundary value is optional. 7 - Lower equal Upper boundary value is optional. 8 - Greater than Upper boundary value is optional. 9 - Greater equal Upper boundary value is optional. This field is mandatory if LowerBoundaryPers onExtId is set. LowerBoundaryPers Employee name 60 onExtId Cardinality 1 0..1 Integration Guide Integration APIs PUBLIC 1071 Field or Node Description Maximum Field Length UpperBoundaryPers 60 onExtId PersonIDInterval Cardinality: 0..un bounded IntervalBoundaryT You can use the follow 1 ypeCode ing values: 1- Equal No upper boun dary value must be set. 3 - Between Upper boundary value is manda tory. 6 - Lower than Upper boundary value is optional. 7 - Lower equal Upper boundary value is optional. 8 - Greater than Upper boundary value is optional. 9 - Greater equal Upper boundary value is optional. This field is mandatory if LowerBoundaryPers onId is set. LowerBoundaryPers 10 onId UpperBoundaryPers 10 onId Cardinality 0..1 1 0..1 0..1 1072 PUBLIC Integration Guide Integration APIs Field or Node Description Maximum Field Length BusinessPartnerRo IntervalBoundaryT You can use the follow 1 leCodeInterval ypeCode ing values: Cardinality: 0..un bounded 1- Equal No upper boun dary value must be set. 3 - Between Upper boundary value is manda tory. 6 - Lower than Upper boundary value is optional. 7 - Lower equal Upper boundary value is optional. 8 - Greater than Upper boundary value is optional. 9 - Greater equal Upper boundary value is optional. This field is mandatory if LowerBoundaryBusi nessPartnerRoleCo de is set. LowerBoundaryBusi Only business partner 6 nessPartnerRoleCo role code BUP003 de (Employee) is sup ported. MarketForArchivin IntervalBoundaryT You can use the follow gIndicator ypeCode ing values: Cardinality: 0..un bounded True False LowerBoundaryMark 1 edForArchivingInd icator Cardinality 1 0..1 1 0..1 Integration Guide Integration APIs PUBLIC 1073 Field or Node UserIdInterval Cardinality: 0..un bounded Description Maximum Field Length IntervalBoundaryT You can use the follow 1 ypeCode ing values: 1- Equal No upper boun dary value must be set. 3 - Between Upper boundary value is manda tory. 6 - Lower than Upper boundary value is optional. 7 - Lower equal Upper boundary value is optional. 8 - Greater than Upper boundary value is optional. 9 - Greater equal Upper boundary value is optional. This field is mandatory if LowerBoundaryUser Id is set. LowerBoundaryUser 12 Id UpperBoundaryUser 12 Id Cardinality 1 0..1 0..1 1074 PUBLIC Integration Guide Integration APIs Field or Node Description Maximum Field Length UserNameInterval Cardinality: 0..un bounded IntervalBoundaryT You can use the follow 1 ypeCode ing values: 1- Equal No upper boun dary value must be set. 3 - Between Upper boundary value is manda tory. 6 - Lower than Upper boundary value is optional. 7 - Lower equal Upper boundary value is optional. 8 - Greater than Upper boundary value is optional. 9 - Greater equal Upper boundary value is optional. This field is mandatory if LowerBoundaryUser Name is set. LowerBoundaryUser 40 Name UpperBoundaryUser 40 Name Cardinality 1 0..1 0..1 Integration Guide Integration APIs PUBLIC 1075 Field or Node Description Maximum Field Length FirstNameInterval Cardinality: 0..un bounded IntervalBoundaryT ypeCode You can use the follow 1 ing values: 1- Equal No upper boun dary value must be set. 3 - Between Upper boundary value is manda tory. 6 - Lower than Upper boundary value is optional. 7 - Lower equal Upper boundary value is optional. 8 - Greater than Upper boundary value is optional. 9 - Greater equal Upper boundary value is optional. This field is mandatory if LowerBoundaryFirs tName is set. LowerBoundaryFirs 35 tName UpperBoundaryFirs 35 tName Cardinality 1 0..1 0..1 1076 PUBLIC Integration Guide Integration APIs Field or Node Description Maximum Field Length LastNameInterval Cardinality: 0..un bounded IntervalBoundaryT You can use the follow 1 ypeCode ing values: 1- Equal No upper boun dary value must be set. 3 - Between Upper boundary value is manda tory. 6 - Lower than Upper boundary value is optional. 7 - Lower equal Upper boundary value is optional. 8 - Greater than Upper boundary value is optional. 9 - Greater equal Upper boundary value is optional. This field is mandatory if LowerBoundaryLast Name is set. LowerBoundaryLast 40 Name UpperBoundaryLast 40 Name EmailAddressInter IntervalBoundaryT 1 val ypeCode Cardinality: 0..un LowerBoundaryEmai 241 bounded lAddress UpperBoundaryEmai 241 lAddress Query Processing Conditions (QueryProcessingConditions) The service nodes contain the service's business data. Cardinality 1 0..1 0..1 1 0..1 0..1 Integration Guide Integration APIs PUBLIC 1077 Fields for the QueryProcessingConditions Node Field Description Maximum Field Length QueryHitsTotalNumberIn dicator You can use the following val ues: True False (default) QueryHitsMaximumNumber Value Enter the maximum number of hits. If no value is entered, the default is automatically set to 1000. 999999999 QueryHitsUnlimitedIndi cator You can use the following val ues: True False (default) Set True to get all data based on selection criteria. QueryLastReturnedObjec tID You can use the following val ues: True False (default) If QueryHitsMaximumNumber Value is set and more data is available, you can set this value to True. Cardinality 1 0..1 1 0..1 Sample Payload Sample Code <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:aba="http://sap.com/xi/ABA"> <soapenv:Header/> <soapenv:Body> <aba:BusinessUserSimpleByElementsQuery_sync> <BusinessUser> <PersonIDInterval> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <!--Optional:--> <LowerBoundaryPersonID>9980035943</LowerBoundaryPersonID> <!--Optional:--> </PersonIDInterval> <BusinessPartnerRoleCodeInterval> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <!--Optional:--> <LowerBoundaryBusinessPartnerRoleCode>bup003</ LowerBoundaryBusinessPartnerRoleCode> </BusinessPartnerRoleCodeInterval> </BusinessUser> <QueryProcessingConditions> <!--Optional:--> 1078 PUBLIC Integration Guide Integration APIs <QueryHitsMaximumNumberValue>1</QueryHitsMaximumNumberValue> <QueryHitsUnlimitedIndicator>false</QueryHitsUnlimitedIndicator> </QueryProcessingConditions> </aba:BusinessUserSimpleByElementsQuery_sync> </soapenv:Body> </soapenv:Envelope> Service Response Business User (BusinessUser) Note The fields below the node User will be filled. Node or Field PersonExternalID PersonID PersonUUID BusinessPartnerRoleCode MarkedForArchivingIndicator ValidityPeriod StartDate Cardinality: 0..1 EndDate PersonalInform ation Cardinality: 0..1 FormOfAddress FirstName LastName PersonFullName AcademicTitle CorrespondenceLanguage Description Maximum Field Length Cardinality Person External ID 60 0..1 Person ID 10 1 Person UUID 36 1 Business Partner 6 1 Role Code True 1 False Format: 1 YYYY-MM-DD Format: 1 YYYY-MM-DD Form of address 4 0..1 First name 40 0..1 Last name 40 0..1 Person full name 80 0..1 Academic title 4 0..1 Correspondence 9 0..1 language Integration Guide Integration APIs PUBLIC 1079 Node or Field MiddleName AdditionalLastName BirthName NickName Initials AcademicSecondTitle LastNamePrefix LastNameSecondPrefix User Cardinality: 0..1 NameSupplement UserID UserName LogonLanguageCode Description Maximum Field Length Cardinality Middle name 40 0..1 Additional last 40 0..1 name Birth name 40 0..1 Nick name 40 0..1 Initials 10 0..1 Academic second 4 0..1 title Last name prefix 4 0..1 Last name second 4 0..1 prefix Name supplement 4 0..1 User ID 12 1 User name/Alias 40 1 Logon language 9 0..1 1080 PUBLIC Integration Guide Integration APIs Node or Field DateFormatCode Integration Guide Integration APIs Description Maximum Field Length Cardinality You can use the 2 0..1 following values: 1DD.MM.YYYY (Gregorian Date) 2 - MM/DD/ YYYY (Gre gorian Date) 3 - MM-DDYYYY (Gre gorian Date) 4YYYY.MM.DD (Gregorian Date) 5YYYY/MM/D D (Gregorian Date) 6 - YYYY-MMDD (Gregorian Date, ISO 8601) 7GYY.MM.DD (Japanese Date) 8GYY/MM/DD (Japanese Date) 9 - GYY-MMDD (Japanese Date) AYYYY/MM/D D (Islamic Date 1) BYYYY/MM/D D (Islamic Date 2) PUBLIC 1081 Node or Field DecimalFormatCode TimeZoneCode TimeFormatCode LockedIndicator Description Maximum Field Length Cardinality CYYYY/MM/D D (Iranian Date) You can use the 2 0..1 following values: 1.234.567,89 X- 1,234,567.89 Y - 1 234 567,89 Time zone 10 0..1 You can use the 2 0..1 following values: 0 - 24 Hour Format (Ex ample: 12:05:10) 1 - 12 Hour Format (Ex ample: 12:05:10 PM) 2 - 12 Hour Format (Ex ample: 12:05:10 pm) 3 - Hours from 0 to 11 (Example: 00:05:10 PM) 4 - Hours from 0 to 11 (Example: 00:05:10 pm) Locked indicator 5 0..1 1082 PUBLIC Integration Guide Integration APIs Node or Field Description Maximum Field Length Cardinality ValidityPeriod StartDate Format: 1 Cardinality: 1 YYYY-MM-DD If no start date is maintained for the User, the StartDate for the BusinessUser is entered. EndDate Format: 1 YYYY-MM-DD If no EndDate is maintained, it is set to 9999-12-31. Role RoleName Role name 40 1 Cardinality: 0..un bounded UserAssignment UserID Cardinality: 0..1 UserName User ID 12 1 40 0..1 WorkplaceInfor EmailAddress Email address 241 0..1 mation PhoneInformati PhoneType Phone type 1 1 Cardinality: 0..1 on CountryDialing Country dialing 10 0..1 Cardinality: 0..un Code code bounded PhoneNumberAre Phone number 10 0..1 aID area code PhoneNumberSub Phone number 30 0..1 scriberID subscriber ID PhoneNumberExt Phone number ex 10 0..1 ension tension FunctionalTitleName Functional title 40 0..1 name Department Department name 40 0..1 RoomNumber Room number 10 0..1 Integration Guide Integration APIs PUBLIC 1083 Node or Field Building Description Building name Maximum Field Length Cardinality 10 0..1 Response Processing Conditions (ResponseProcessingConditions) Field Description Maximum Field Length HitsTotalNumberValue Contains the number of 999999999 users based on given criteria. ReturnedQueryHitsNumbe rValue Contains the number of found data sets for business users. 999999999 MoreHitsAvailableIndia ctor The indicator is set if the query was limited to a num ber of hits, but more busi ness user data sets are avail able based on the query. LastReturnedObjectID Displays the last row of the found results list, limited by the found hits or by the value given for QueryHitsMaximumNumber Value. 999999999 Log (Log) If errors occur, the log contains the information shown in the table below: Cardinality 1 1 1 0..1 Field or Node Description BusinessDocumentProcessingResultCode Maximum Field Length 2 Cardinality 0..1 MaximumLogItemSeverityCode If several messages are 1 0..1 stored for a business user, the maximum of all dropped severity codes worst level will be shown. Item TypeID Message number 40 0..1 Cardinality: 0..un CateoryCode Not in use 15 0..1 bounded 1084 PUBLIC Integration Guide Integration APIs Field or Node SeverityCode Note WebURI Description Maximum Field Length Severity code defini- 1 tion: 1 - Information 2 - Warning 3 - Error Contains the message 200 texts. Not in use Cardinality 0..1 1 0..1 Constraints This service does not support: Service Performer (BBP005) business users Freelancer (BBP010) business users Additional Information Business User - Read Note For more information about the API, choose the Details tab on the SAP API Business Hub. 5.10.3 Business User - Read Metadata Technical name: QueryBusinessUserMetadataIn This service enables you to read metadata information from your external data source such as an identity management system for service Business User with this synchronous inbound service. This service provides the search parameter RoleCategory, which restricts the result set of the metadata information of the service. The response includes the metadata information based on the given criteria. If errors occur, the log contains information about the severity code, the message number and message texts. This service is available on the SAP API Business Hub, for more information see APIs on SAP API Business Hub. Integration Guide Integration APIs PUBLIC 1085 Service Request Service Nodes The service nodes contain the service's business data. Node or Field Description Cardinality BusinessPartnerRoleCat IntervalBoundaryTypeCo You can only use the follow 1..1 egoryInterval de ing value: Cardinality: 0..unbounded 1 - Equal LowerBoundaryBusinessP For example: BUP003 0..1 artnerRoleCategoryCode Sample Payload Sample Code <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:aba="http://sap.com/xi/ABA"> <soapenv:Header/> <soapenv:Body> <aba:BusinessUserMetaDataQuery_sync> <!--Zero or more repetitions:--> <BusinessPartnerRoleCategoryInterval> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryBusinessPartnerRoleCategoryCode>BUP003</ LowerBoundaryBusinessPartnerRoleCategoryCode> </BusinessPartnerRoleCategoryInterval> </aba:BusinessUserMetaDataQuery_sync> </soapenv:Body> </soapenv:Envelope> Service Response Service Node BusinessUserMetaData Description Link to Details RoleCategoryDependentM etaData This node contains all meta data, which depends on the role category of a business user, such as the role cate gory with its role, external ID category with its external ID type or relationship category. RoleCategoryDependentMe taData [page 1088] 1086 PUBLIC Integration Guide Integration APIs Service Node Log Error Codes Error Code 112 118 CodeList Description Link to Details This node provides the avail able code lists for SAP spe cific codes. For example country/region code, aca demic title. CodeList [page 1090] This nodes displays occurred Log [page 1091] messages. Message Description Interval Boundary Type Code &1 is not supported for BusinessPartnerRoleCa tegoryInterval. You can only use the following value: 1 - Equal No data found by given search criteria. To display all data, don't enter any value. Authentication Method You can use the following authentication methods: User ID/password (Username Token), X.509 certificate (X509 Token) or Single Sign On using SAML (SAML Token). Constraints Currently this SOAP service is only enabled for English. Additional Information If you have any issues, report an incident for component CA-GTF-BUM. Note For more information about the API, choose the Details tab on the SAP API Business Hub. Integration Guide Integration APIs PUBLIC 1087 5.10.3.1 RoleCategoryDependentMetaData Nodes and Fields Note In the following table, field attributes are marked in blue. RoleCategoryDependentMetaData Node or Field Description Cardinality BusinessPart BusinessPartnerRoleCategoryCode nerRoleCateg ory Cardinality: 1..1 Description languageCode BusinessPart BusinessPartnerRoleCode nerRole Cardinality: 1..1 Description languageCode For example: BUP003 For example: Employee For example: BBP005 1..1 0..unbounded 1..1 0..unbounded DefaultIndicator Can be true or false BusinessPart nerExternalI DCategory Cardinality: 0..1 BusinessPartnerExternalIDCategoryCode Description languageCode BusinessPart nerExternalI D Cardinality: 0..unbounded BusinessPartnerExternalIDCode Description languageCode DefaultIndicator For example: 1..1 HCM030 For example: HCM030 0..unbounded 1..1 0..unbounded The value can be eithertrue or false BusinessPart nerRelations hipCategory Cardinality: 0..1 BusinessPartnerRelationshipCategoryCode Description languageCode Partner1_BusinessPartnerC BusinessPartnerCategoryCo ategory de Cardinality: 0..unbounded For example: BUR025 Can be: 2 - Organi zation 3 - Group 1..1 0..unbounded 1..1 Description languageCode 0..unbounded Partner2_BusinessPartnerC BusinessPartnerCategoryCo Can be: 1..1 ategory de 1 - Person 1088 PUBLIC Integration Guide Integration APIs Node or Field Cardinality: 0..unbounded NodeProperti NodePath es Cardinality: 0..unbounded NodeProperty Cardinality: 0..unbounded FieldPropert NodePath ies 0..unbounded Fieldname Description Cardinality Description languageCode 0..unbounded For example: 1..1 BUSINESS_USE R NodePropertyCode Description languageCode Node property codes are: 01 - ena bled 02 - disa bled 03 - read only 1..1 0..unbounded For example: 1..1 BUSINESS _USERUSERROLE BUSINESS _USERUSERVALIDITY _PERIOD BUSINESS _USERUSER_ASS IGNMENT Name of a field. 1..1 Integration Guide Integration APIs PUBLIC 1089 Node or Field FieldProperty Cardinality: 0..unbounded Description Cardinality FieldPropertyCode Node property 1..1 codes are: 01 - ena bled 02 - disa bled 03 - read only 04 - man datory 05 - ena bled, read only for up date 06 - man datory, read only for update Description languageCode 0..unbounded Note To display more information about the service node on the SAP API Business Hub, choose API References and select the operation. 5.10.3.2 CodeList Nodes and Fields Note In the following table, field attributes are marked in blue. CodeList Node or Field FieldName FieldCodeList Cardinality: 0..un bounded FieldValue Description Cardinality Name of the field. 1..1 This node provides the 1..1 available code lists for SAP specific codes. For example country/ 1090 PUBLIC Integration Guide Integration APIs Node or Field FieldDescription languageCode Description Cardinality region code, academic 0..unbounded title. Note To display more information about the service node on the SAP API Business Hub, select the operation. 5.10.3.3 Log Nodes and Fields Note In the following table, field attributes are marked in blue. Log Node or Field BusinessDocumentProcessingResultCode MaximumLogItemSeverityCode Item Cardinality: 0..unbounded TypeID CategoryCode SeverityCode Note WebURI Description Cardinality 0..1 If several messages are 0..1 stored for a business user, the maximum of all dropped severity codes worst level will be shown. Message number. 0..1 Not in use. 0..1 Severity code definition: 0..1 1 - Information 2 - Warning 3 - Error Contains the message texts. 1..1 Not in use. 0..1 Note To display more information about the service node on the SAP API Business Hub, select the operation. Integration Guide Integration APIs PUBLIC 1091 6 Business Event Handling Subscribe to business events in SAP Marketing Cloud. You can subscribe to business events triggered in SAP Marketing Cloud to receive notifications in extensions on SAP BTP. Then you can take follow-up actions on the events, if desired. When an event is triggered in SAP Marketing Cloud, there is at least one API available to fetch the necessary information. The following diagram illustrates the systems required to use business event handling in SAP Marketing Cloud. You can use the SAP-managed deployment service for the Kubernetes cluster to set up the SAP BTP, Kyma runtime. For more information, see Kyma Environment. Prerequisites You have connected SAP Marketing Cloud to SAP Event Mesh and have enabled the events in SAP Marketing Cloud. For more information, see Integrating Enterprise Event Enablement. You have configured SAP Event Mesh and set up a message queue to consume the events being triggered in SAP Marketing Cloud. For more information, see Using Event Mesh. For details about configuring the business events and APIs with SAP Marketing Cloud and extensions on SAP BTP, see the following blog: Use SAP BTP, Kyma runtime to extend SAP Marketing Cloud Note The SAP blog isn't part of the official documentation of SAP Marketing Cloud and some of the information may be outdated. Example A customer in B2B Marketing, running email campaigns in SAP Marketing Cloud, wants to use business events on interactions. They want to notify the responsible sales person that a contact has opened or clicked through 1092 PUBLIC Integration Guide Business Event Handling a recent email, which was supporting their sales activities in a given opportunity. The sales person is also notified if the email wasn't delivered or opened because it was hard bounce, for example, if the email address was invalid. The sales person is also notified if the email wasn't delivered or opened due to a soft bounce, for example, the email was identified as JUNK or SPAM and didn't reach the inbox of the contact. For more examples of business scenarios where you can use business events from SAP Marketing Cloud, see the following blog: Extended Capabilities of SAP Marketing Cloud using Business Event Handling. Note The SAP blog isn't part of the official documentation of SAP Marketing Cloud and some of the information may be outdated. More Information SAP Event Mesh Business Event Handling SAP Marketing Cloud Business Events 6.1 Campaign File Export Business event for campaign file export (MarketingObjectAttachment). During campaign execution, you can export target group members with the fields of the export definition as a file. The file is stored in relation to the campaign in SAP Marketing Cloud. If another system wants to use this file to access the contact information and send out white papers, for example, then it alerts SAP Marketing Cloud by a business event. The event is raised after a successful export. The external system can retrieve the contact information using the Read Content of Export Files in Campaigns API (API_MKT_EXPORT_DEFINITION). For more information, see Read Content of Export Files in Campaigns [page 901]. Business Events The following business event is available for the MarketingObjectAttachment object: Integration Guide Business Event Handling PUBLIC 1093 Events Event Created Description Payload This event is raised when a marketing campaign export file is created. MarketingObjectUUID: The unique identifier of the marketing object. MarketingObject: MarketingObject MarketingObjectType: The type of the marketing object. MktgObjectAttachmentFilename: The filename of the marketing object attachment. Additional Information For more information about how business events are handled, see Business Event Handling. For more technical information about this event, see the Marketing Campaign Export File Events SAP API Business hub. One-time registration is required for first-time users. page on the 6.2 Campaigns Business events for campaigns (MarketingCampaign). A business event can be raised for externally executed campaigns when the campaign has ended and the status has been changed to Stopped. The event allows the external system on which the campaign was executed, to react and retrieve further information using the Campaigns API (API_MKT_CAMPAIGN). For more information, see Campaigns [page 767]. Business Events The following business event is available for the MarketingCampaign object: Events Event Description Payload Completed This event is raised when a marketing campaign is completed. CampaignUUID: The unique identifier of the campaign. 1094 PUBLIC Integration Guide Business Event Handling Additional Information For more information about how business events are handled, see Business Event Handling. For more technical information about this event, see the Marketing Campaign Events page on the SAP API Business hub. One-time registration is required for first-time users. 6.3 Coupon Code Usages Business event for coupon code usage (CouponCodeUsages). A business event can be raised to collect coupon code usage changes for coupons. Follow-up activities can then be triggered. You can retrieve detailed information about the coupon code usage using the Coupons API (API_MKT_COUPON_SRV). For more information, see Coupons [page 1026]. Business Events The following business event is available for the CouponCodeUsages business object: Events Event Description Payload Changed This event is raised when a marketing coupon is used during campaign execu tion. CouponCodeUUID: The unique identi fier of a coupon code. Example for a Received Message Sample for Enterprising Messaging Java API (emjapi): Sample Code [ { "message": " {\"eventType\":\"BO.MarketingCoupon.Changed\", \"cloudEventsVersion\":\"0.1\",\"source\":\"https://S4HANAOD.sap.com\", \"eventID\":\"+hY+UEf5HtmYoI4Dl/x9uw==\",\"eventTime\":\"2019-04-17T11:32:10Z \",\"schemaURL\":\"https://S4HANAOD.sap.com/sap/opu/odata/IWXBE/ BROWSER_SRV/\",\"contentType\":\"application/json\",\"data\":{\"KEY\": [{\"COUPONUUID\":\"FA163E5047F91ED9909BF4279961A4C7\"}],\"COUPONCODEUUID\": [{\"COUPONCODEUUID\":\"364CD2B40C8B189316006024A4657417\"}]}}", "timestamp": "4/17/19 11:32 AM", "id": "47a2003c-95d2-475d-bd59-cfc81a053f2d" } ] Integration Guide Business Event Handling PUBLIC 1095 For further processes, such as reading further coupon information requested by the OData services (such as API_MKT_COUPON, CUAN_COUPON_MAINTAIN, and so on), CouponUUID or CouponCodeUUID must be converted and entered as CouponUUID equals fa163e50-47f9-1ed9-909b-f4279961a4c7 and CouponCodeUUID equals 364C-d2b4-0c8b-18931600-6024a4657417. Examples Coupon information with GUID: /sap/opu/odata/SAP/API_MKT_COUPON_SRV/ Coupons(guid'fa163e50-47f9-1ed9-909b-f4279961a4c7') Coupon code information with GUID: /sap/opu/odata/SAP/API_MKT_COUPON_SRV/ CouponCodes(guid'364C-d2b4-0c8b-18931600-6024a4657417') Additional Information For more information about how business events are handled, see Business Event Handling. For more technical information about this event, see the Marketing Coupon Events page on the SAP API Business hub. One-time registration is required for first-time users. 6.4 Interactions Business events for interactions (Interaction). A business event can be raised for any interaction type. Follow-up activities can then be triggered. You can retrieve detailed information using the Interactions API (API_MKT_INTERACTION). For more information, see Interactions [page 615]. Business Events The following business event is available for the Interaction object: Events Event Description Payload Created This event is raised when an interaction InteractionUUID: The unique identi is created. fier of the Interaction. InteractionType: The type of the In teraction. 1096 PUBLIC Integration Guide Business Event Handling Marking an Interaction Type for Business Events To indicate that you want to raise a business event for an interaction type, do the following: 1. Open the Manage Your Solution app. 2. Go to the Managing Interaction Content configuration step under Contacts and Profiles. 3. Find the interaction type you want to raise a business event for. 4. Select the Business Event checkbox in the Key Information screen. The following screen capture shows an example of an interaction type that has been identified as a business event. Additional Information For more information about how business events are handled, see Business Event Handling. For more technical information about this event, see the Interaction Events page on the SAP API Business hub. One-time registration is required for first-time users. 6.5 Interaction Contacts Business events for interaction contacts (InteractionContact). If you implement custom or partner scenarios that are dependent on the lifecycle of an interaction contact, you can use business events for interaction contacts. These events are used to trigger a reaction when an interaction contact is created, updated, merged, or deleted. You can then react on these changes. You can retrieve detailed information about the interaction contacts using the following APIs: Contacts API (API_MKT_CONTACTS). For more information, see Contacts [page 412]. Interaction Contacts API (API_MKT_INTERACTION_CONTACT). For more information, see Interaction Contacts [page 469]. Corporate Accounts API (API_MKT_CORPORATE_ACCOUNT). For more information, see Corporate Accounts [page 512]. Integration Guide Business Event Handling PUBLIC 1097 Business Events The following business events are available for the InteractionContact object: Events Event Description Payload Created Changed Deleted This event is raised when an interaction contact is created. This event is raised when an interaction contact is changed. This event is raised when an interaction contact is deleted. InteractionContactUUID: The unique identifier of the Interaction Con tact. InteractionContactType: The type of the Interaction Contact. Merged This event is raised when an interaction contact is merged. InteractionContactUUID: The unique identifier of the Interaction Con tact. AssgdToInteractionContactUUID: The unique identifier of the interaction contact, where the merged contact is assigned to. AssgdToInteractionContactType: The type of the Interaction Contact, where the merged contact is assigned to. Additional Information For more information about how business events are handled, see Business Event Handling. For more technical information about these events, see the Interaction Contact Events page on the SAP API Business Hub. One-time registration is required for first-time users. 6.6 Marketing Permissions Business events for marketing permissions (MarketingPermission). Marketing permissions that are gathered in SAP Marketing Cloud are often distributed to other marketingrelated systems, for example, call center solutions. When a permission is created or changed in SAP Marketing Cloud, a business event can be raised to trigger the distribution of that permission. You can retrieve detailed information about the permission using the Interaction Contacts API (API_MKT_INTERACTION_CONTACT). For more information, see Interaction Contacts [page 469]. 1098 PUBLIC Integration Guide Business Event Handling Business Events The following business events are available for the MarketingPermission object: Events Event Description Payload Created Changed This event is raised when a marketing permission is created. This event is raised when a marketing permission is changed. MarketingPermissionUUID: The unique identifier of a marketing permis sion. ContactPermission: Contact permis sion (contact allowed / not allowed or permission to be checked). Additional Information For more information about how business events are handled, see Business Event Handling. For more technical information about these events, see the Marketing Permission Events page on the SAP API Business hub. One-time registration is required for first-time users. 6.7 Marketing Subscriptions Business events for marketing subscriptions (MarketingSubscription). Marketing subscriptions that are gathered in SAP Marketing Cloud are often distributed to other marketingrelated systems, for example, call center solutions. When a contact subscribes or changes their subscription in SAP Marketing Cloud, a business event can be raised to trigger the distribution of that subscription. You can retrieve detailed information about the subscription using the Interaction Contacts API (API_MKT_INTERACTION_CONTACT). For more information, see Interaction Contacts [page 469]. Business Events The following business events are available for the MarketingSubscription object: Integration Guide Business Event Handling PUBLIC 1099 Events Event Created Changed Description Payload This event is raised when a marketing subscription is created. This event is raised when a marketing subscription is changed. MarketingSubscriptionUUID: The unique identifier of a marketing sub scription. ContactSubscription: Contact sub scription (contact allowed / not allowed or permission to be checked). Additional Information For more information about how business events are handled, see Business Event Handling. For more technical information about these events, see the https://api.sap.com/event/ SAPMarketingCloudBusinessEvents_MarketingSubscriptionEvents/overview page on the SAP API Business hub. One-time registration is required for first-time users. 1100 PUBLIC Integration Guide Business Event Handling 7 Integration Technologies Here you can find an overview about the integration technologies used in your solution. Technology SOAP REST OData CSV Description SOAP is a protocol specification for exchanging structured information in the implementation of web services in com puter networks. The message format is based on XML. Mes sage transfer is based on other web protocols, usually HTTP(S). Representational State Transfer (REST) is a architecture style for creating scalable web services. REST services are usually based on HTTP(S). They use HTTP URIs for resource identification and HTTP methods for service operations. It is used widely as an alternative to SOAP, as REST services usu ally provide better performance, scalability and simpler in terfaces. OData provides a protocol for queryable and interoperable RESTful APIs. It provides an entity-based data model and a query language. Create, read, update and delete methods expressed using HTTP methods. All OData services use HTTPS protocol to ensure data security. The standard port for HTTPS is 443. A comma-separated values (CSV) (also sometimes called character-separated values) file stores tabular data (num bers and text) in plain-text form. CSV files are widely used as import or export format and can be down- and uploaded to many systems. Integration Guide Integration Technologies PUBLIC 1101 8 Create Your Own Apps: SAP Rapid Application Development by Mendix With this integration, you can supplement marketing capabilities with apps that you've created on the low code platform Mendix. Business Benefits Extend SAP Marketing Cloud with customer-specific applications for dedicated business use cases, for example, a trade fair app for registration of contacts for demo sessions. Enable business users to easily create apps for marketing using SAP Rapid Application Development by Mendix. Key Capabilities Extend SAP Marketing Cloud with a side-by-side approach, public APIs, and extensions. Provide user authentication and ensure security standards. Provide a means of extending apps to support a two-tier landscape for quality and productive systems. Fulfill requirements when the connected SAP Marketing Cloud system is upgraded. Example Scenarios In B2B scenarios, apps can enable sales people to enter leads and maintain contact data in marketing. Other companies' access to customer contacts for registration at session events or to request a product demo. For B2C customers, it's beneficial for their call-center agents to put together a well-tailored factsheet of the most important profile data of their consumers by means of a low code app. You're already running SAP Marketing Cloud and want to take the next step in your digitalization by offering individual product demo sessions at a trade fair. The registration can be realized by sending out emails with registration codes, for example, using offer coupon codes. 1102 PUBLIC Integration Guide Create Your Own Apps: SAP Rapid Application Development by Mendix Prerequisites You've created a user on Mendix to access their platform. We recommend to install the Mendix Studio Pro (development platform) locally. Steps to Get Your App Prepare 1. Make sure that you have the Administrator role assigned. 2. Define the business scenarios you want to realize with the app and figure out, which application programming interfaces (APIs) from SAP Marketing Cloud you need. Get familar with the data model, the entity relationship model and the available nodes and components, and how they interact with each other on the side of SAP Marketing Cloud. 3. Map the required APIs to your business scenario and check if they're available in SAP Marketing Cloud. Steps in SAP Marketing Cloud 1. Create communication arrangements and communication systems for the required communication scenarios in the SAP system for the APIs you selected. 2. Open the metadata request URL in your browser and save the text file to your machine. The URL has the pattern https://<host>/sap/opu/odata/sap/ API_MKT_<object>_SRV;v=<latest version>/$metadata. Example https://<host>/sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0003/$metadata Steps in Mendix 1. Use the OData Model Creator for SAP Solutions to connect the SAP system with the Mendix solution. You can find the connectors in the Mendix App Store under Connectors SAP . In our example, we used the OData Connector for SAP Solutions and the OData Model Creator for SAP Solutions. 2. There you can manually upload the data model: 1. Choose Manual and upload the locally stored metadata XML file. 2. Select the locally stored file. 3. Choose Continue twice, and then Generate .mpk. The Mendix system generates a data model out of the SAP file. This generated data model can be imported into your Mendix project. You can see the data models next to your module folder. 3. Connect the required elements of data models in a combined Domain Model of your module. 4. We recommend using the offered app templates by Mendix for SAP, such as the SAP App Template for Fiori Apps. With the template, the correct OData connector is also installed. 5. For deployment ensure that the app user has the business catalog roles assigned that are required for the APIs you are using. You can generally find this information in the API documentation. Alternatively, you can use a technical user with basic authentications. Integration Guide Create Your Own Apps: SAP Rapid Application Development by Mendix PUBLIC 1103 Related Information Business Scenarios Implementing Integrations for Business Scenarios [page 9] Consuming the Integration APIs [page 395] > Getting Started [page 387] > Consuming the Integration APIs [page 395] Documentation provided by SAP: SAP Rapid Application Development by Mendix Tutorial from SAP's Developer Community: Get Started with SAP Rapid Application Development by Mendix Documentation provided by Mendix: Low code development for SAP® by Mendix Component for Incidents Please use the following component for incidents: XX-PART-MDX-RAD 1104 PUBLIC Integration Guide Create Your Own Apps: SAP Rapid Application Development by Mendix Important Disclaimers and Legal Information Hyperlinks Some links are classified by an icon and/or a mouseover text. These links provide additional information. About the icons: Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this: The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information. SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct. Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information. Videos Hosted on External Platforms Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the control or responsibility of SAP. Beta and Other Experimental Features Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up. The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP. Example Code Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct. Bias-Free Language SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities, genders, and abilities. Integration Guide Important Disclaimers and Legal Information PUBLIC 1105 www.sap.com/contactsap © 2021 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies. Please see https://www.sap.com/about/legal/trademark.html for additional trademark information and notices. THE BEST RUNAH XSL Formatter V6.3 MR5 for Windows (x64) : 6.3.6.26216 (2016/10/17 11:37JST) Antenna House PDF Output Library 6.3.855 (Windows (x64))