This paper explores the Consumer Data Management, Consumer Data Management CDM area as the process and framework for collecting, managing, and analyzing consumer data from various sources in order to form a unified view of each client. Customer data
Full description
nursing
Batch Management Over viewFull description
Descrição completa
Full description
SAP's Event Management product allows you to manage your business processes by exception, give visibility of process status to your supply chain and react to issues occuring in the supply ch…Full description
SAP Credit Management OverviewFull description
SAP MM, SAP Inventory Management SAP IM ERP TIPSDescripción completa
Full description
SAP HUMDescripción completa
SAP Cash Management
SAP Event Management OverviewFull description
Integration Guide
SAP Hybris Marketing On Premise Document Version: 1.02 – 2017-03-07
Impo Im port rt Co Cont ntac acts ts wi witth Mar arke kettin ing g Pe Perm rmis issi sion onss fr from om an Ex Exte tern rnal al So Sour urce ce Sy Sysste tem m . . . . . . . . . . . . . . . . . .105
Before you start, make sure you have the latest version of this document. You can find the latest version at the following location: http://help.sap.com/mkt The following table provides an overview of the most important document changes. If the information you are looking for is not described in this guide or if you find something described incorrectly, please send an email to mailto:[email protected] and we'll update this guide. Table 1: Document History Version
Date
Description
1.0
2017-05-09
Initial version for SAP Hybris Marketing
Data Management Upload Interfaces 1702 4
CUSTOMER
Document History
1
Introduction
This document describes the external interfaces that SAP Hybris Marketing provides for creating or updating Interaction Contacts, Interactions, Interests, Corporate Accounts, Product Categories, and Products. The following interfaces exist: ●
●
CSV upload - This upload is performed manually in Import Data and is additionally documented in the Application Help, which you can access directly from the app. OData service
Note The OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV should be used to create SAP Hybris Marketing interactions from business documents from any source system. In contrast to OData service CUAN_IMPORT, CUAN_BUSINESS_DOCUMENT_IMP_SRV enables you to change interactions. Each business 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 is used for standard integration of SAP Hybris Marketing with SAP Hybris Cloud for Customer. It is also used in marketingdriven and sales-driven processes. For information on using the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV see the Importing Business Documents guide at http:// help.sap.com/mkt
SAP Hybris Marketing Cloud
SAP Hybris Marketing Cloud Product Page
Integration . ●
Remote function call (RFC)
●
Web service
You can use the Business Add-In Interaction Contact Update (CUAN_CE_IC_UPDATE) to create new contacts or companies based on the imported interactions, interaction contacts, or companies. For more information, see Customizing for SAP Hybris Marketing under (BAdIs)
BAdI: Interaction Contact Update
Contacts and Profiles
Interaction Contacts
Business Add-Ins
.
Feedback
We'd really like to know what you think of the quality, structure or content of this guide. Please send your feedback to us at mailto:[email protected].
Data Management Upload Interfaces 1702 Introduction
CUSTOMER
5
2
General
This chapter describes miscellaneous functions and checks.
2.1
Email Validation Checks
Email addresses are checked for validity according to RFC 3696 norm. The validation checks are listed in the table below. The format of a valid email address is [email protected] ● ●
●
●
The local part, found before @, is typically the user name. A subdomain, found directly after @, is optional, for example help in [email protected]. A subdomain can also be composed of several parts, separated by a dot, for examplecloud.help. The domain is typically the name of the business, organization or Internet service provider that owns that domain. The top-level domain is what appears right-most in an email address, after the domain. For example,.com in [email protected].
Interaction contacts refer to contacts in SAP Hybris Marketing A contact is a natural person who interacts with a company. Contact data is collected and merged from several sources into the master data tables within SAP Hybris Marketing. We distinguish between contacts, corporate contacts, consumers, and suspects to define the business relationship of a contact to a company. For this purpose, the contact master data contains the IS_CONTACT and IS_CONSUMER fields: ●
A suspect is a natural person whose interests are unknown but who, at some future date, may be important in the interaction with a company (B2B process), or may generate sales revenue (B2C process).
●
A contact is a natural person with whom a company interacts in a B2B process (IS_CONTAcT = X).
●
A consumer is a natural person who generates sales revenue (IS_CONSUMER = X).
A person can be a contact and a consumer at the same time. In addition to the business relationship, the validation status and contact level is also interesting. These indicate to what extent the information about a contact is valid. For example, if a contact simply clicked on an item on your Web site, the validation status is low, meaning that the contact is unknown. Whereas if a contact filled in a form on the Web site and entered name and address data, the contact is self-identified. If a contact clicked on a link in an email that you have sent after the contact has registered on your Web site, the contact is verified, meaning that the email address is validated. If a contact is in your customer database, the contact is a business partner.
Enhancing the Interaction Contact Data The CUAN_S_CE_IC_EXT_FAFL structure contains the attributes for interaction contacts that you can import into the SAP Hybris Marketing system. In addition to the attributes defined in the structure, you can add customspecific attributes: ●
for interaction contacts in the INCL_EEW_CUAN_CE_IC_ROOT include
●
for interaction contact persons in the INCL_EEW_CUAN_CE_IC_ROOT_PERS include
●
for interactions and interaction contacts in the INCL_EEW_CUAN_CE_IA_IC include
The attributes that are added to the include are considered automatically. If you want to add master data to the interaction contact via the interaction, use the INCL_EEW_CUAN_CE_IA_IC include. Some of the imported data is set by implemented business logic. The Business Add-In BAdI: Interaction Contact Update (CUAN_CE_IC_UPDATE) determines the records that are picked up to create the attributes for the Interaction Contact Best Record. The BAdI also determines the validation status. For more information, see the BAdI documentation in Customizing for SAP Hybris Marketing under and Profiles
Interaction Contacts
Business Add-Ins
Contacts
.
Note Note about the BADI Update Interaction Contact
Data Management Upload Interfaces 1702 8
CUSTOMER
Interaction Contacts
Two field groups are available for updating interaction contact common data - one group contains fields related to the name and one group contains fields related to the address: ●
The standard logic of the BADI Contact Interaction Update is as follows as far as these two field groups are concerned. These fields are filled according to the priority assigned to an origin in step 8. For example, if data from the origin SAP_ERP_CONTACT has a higher priority than data from the origin SAP_CRM_BUPA, the fields in these groups will be filled solely with data from SAP_ERP_CONTACT. If data in certain fields is not provided from SAP_ERP_CONTACT, these fields will remain empty. Missing data will not be filled from the source with the next highest priority if it is available. Customers can change the standard BADI logic to adjust this behavior if required.
Free Text Mapping When you import interaction contacts from a non-SAP system, free texts cannot always be automatically mapped to the internal IDs and names used by SAP. The automatic mapping of free text values to internal ID values keeps the interface simple. If the consumer provides free text, that is, data elements with the _FT suffix, the system tries to find the matching key value. If only free text is provided, the system tries to determine the corresponding code. Mapping is supported for the following attributes: ●
Country
●
Region
●
Language
●
Department
●
Function
●
Industry
●
Gender
●
Marital Status
●
Title
During the import of interaction contacts and interactions, mapping is performed automatically. For new, unknown free texts that cannot be mapped to SAP IDs, entries are created automatically as work items. You can then map these free texts to SAP IDs in the Customizing activity Map Free Texts.
ID ORIGIN The origin of an ID indicates the source of this ID. The ID_ORIGIN field is maintained in Customizing for SAP Hybris Marketing under
the . This is relevant if you want to add a new origin. For ID origins that are not delivered by SAP, add these IDs via the contact facets. The contact facets interface is available in the RFC-enabled function module and the OData service. For CSV Upload, the ID_ORIGIN field is set to SAP_FILE_IMPORT. This is the default, but you can also define different ID origins. This allows you to update the contact with different sources. If no ID is provided in the CSV file, it is generated automatically. Contacts and Profiles
Interaction Contacts
Define Origins of Contact ID
Data Management Upload Interfaces 1702 Interaction Contacts
CUSTOMER
9
Caution ●
●
You must specify a different ID Origin per source system or data source. In other words, if you import data from multiple sources, for example, from an ERP system, a CRM system, or a third-party system, you must ensure that the ID Origin for each source is different. Otherwise the data from one source will overwrite data imported from another source. You are not allowed to use the origin SAP_HYBRIS_MKT_IC.
In addition, you can flag an origin as incognito. Incognito in this context means that the system does not automatically create a master data record for a contact ID with the respective origin since the origin does not contain sufficient information to relate the ID to a person. For contact IDs from origins that are not flagged as incognito, the system automatically creates a master data record with the available information.
Data Management Upload Interfaces 1702 10
CUSTOMER
Interaction Contacts
4
Interactions
Use 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. Interaction data consists of two parts: one part identifies, describes, and controls the interaction itself, the other part identifies and describes the contact who performed the interaction. There is no limit on the number of interactions that an interaction contact can have.
Note When you upload interactions using the OData interface, you cannot upload contact data (name, address and so on) at the same time. Contact data is uploaded separately.
Prerequisites Before interaction data can be imported, the following prerequisites must be met: ●
●
●
Customizing has been maintained for the following fields: ○
ID_ORIGIN in the Customizing activity Define Origins of Contact ID (CEI_CE_DEF_ORIGIN)
○
IA_TYPE in the Customizing activity Define Interaction Types (CEI_CE_DEF_IA_TYPE)
○
COMM_MEDIUM in Customizing activity Define Communication Media (CEI_CE_DEF_CMM_MEDIA)
Interaction type and communication medium have been assigned to a channel in the Customizing activity Assign Interaction Types and Communication Media to Channels (CEI_CE_CH_ASGN) . Interests must be edited or uploaded in
Business Administration
Interaction Interests .
Note If social media posts are imported (IA_TYPE = SOCIAL_POSTING), the ID_ORIGIN must be available as social media channel code (SMI_TYPE) such as TW for Twitter (see Customizing activity Define Settings for Social Media Integration (CSAN_ICONS)). The entries for ID_ORIGIN and COMM_MEDIUM must be identical with the SMI_TYPE. ●
If ID_ORIGIN is an email address (IA_TYPE = EMAIL), the ID field must contain a valid email address. This is checked in the pre-delivered implementation of the CL_CUAN_CE_IA_UPLOAD_BADI_EXMP class of the BAdI Revise and Manage Interactions While Uploading (CUAN_CE_IA_UPLOAD).
For more information, see Customizing for the Profile Dashboard under Profiles
SAP Hybris Marketing
Contacts and
Interactions .
Data Management Upload Interfaces 1702 Interactions
CUSTOMER
11
Semantic Key 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 and are checked during import: ○
ID_ORIGIN: Origin of the interaction contact data (except in the case of ANONYMOUS interactions, as
described under point 2b below.) ○
ID: External ID of the interaction contact data (except in the case of ANONYMOUS interactions, as
described under point 2b 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 Hybris
Cloud for Customer. ○
SOURCE_OBJECT_ID: Object ID of the source object, for example, the GUID of the SAP Hybris 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. Table 3: If IA_TYPE is SOCIAL_POSTING
SOURCE_OBJECT_ID should be filled
Remarks
with
Original Post ID of the respective so
This is checked during upload.
cial media network SHOP_ITEM_VIEW
WEB_SESSION_ID
For recommendations only. Not checked during upload.
WEBSITE_SEARCH
WEB_SESSION_ID
For recommendations only. Not checked during upload.
CLICK_THROUGH
WEB_SESSION_ID
For recommendations only. Not checked during upload.
SALES_ORDER
SALES_ORDER_ID
For recommendations only. Not checked during upload.
Data Management Upload Interfaces 1702 12
CUSTOMER
Interactions
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:
1. 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. 2. 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 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.
Update Modes In most cases interactions can only be added, but not updated. However, the following exception exists: ●
Non-semantic key fields of interactions for social media posts and for SAP Hybris Cloud for Customer can be updated. The fields ID_ORIGIN and ID usually identify the contact. Depending on the contact update mode (fields IC_UPDATE_MODE as explained in the table below) the import behavior is as follows: If a contact has already been created, its data is updated using the fields describing a contact. For the update logic, see Interaction Contacts [page 8]. If the contact is not yet available in the system, it is created. The following contact update modes are available for the field IC_UPDATE_MODE: Table 4: Update Modes Update
Type of Update
What Is Updated
N
No Update
Only the Contact ID is determined. If no contact is found, an error is triggered.
C
Create
Only the Contact ID is determined. If no contact is found, a new one is created.
F
Full Update
All existing fields are overwritten by imported fields. If empty fields are imported,
Code
these overwrite the corresponding filled fields of the facet.
Data Management Upload Interfaces 1702 Interactions
CUSTOMER
13
Update
Type of Update
What Is Updated
Delta
All imported fields that are filled overwrite existing fields of the same facet of the
Code D
contact. If the contact don't already exist, it is created.
Custom Fields For a description of all fields supported for the import of interaction data, see the Appendix [page 110]. You can use the following includes if you want to add customer-specific attributes, which are then considered automatically during the upload: ●
INCL_EEW_CUAN_CE_IA_IC (contact-specific fields used in interactions)
Data Management Upload Interfaces 1702 14
CUSTOMER
Interactions
5
Companies
Companies exist as interaction contacts with the type Corporate Account. The approach for uploading companies using OData RFC, Web Service and CSV is similar to that followed for interaction contacts, but with fewer attributes available. The CUAN_S_CE_COMP_EXT_FAFL structure contains the attributes for companies that you can import into the SAP Hybris Marketing system. In addition to the attributes defined in the structure, you can add customer-specific attributes in the INCL_EEW_CUAN_CE_IC_ROOT include for interaction contacts, INCL_EEW_CUAN_CE_IC_ROOT_COMP include for companies (similar to interaction contacts) and in the INCL_EEW_CUAN_CE_IA_IC include for interaction contacts and interactions. The attributes that are added to the include are considered automatically. For CSV Upload, the ID_ORIGIN field is set to SAP_FILE_IMPORT. This is the default, but you can also define different ID origins. This allows you to update the company with different sources. If no ID is provided in the CSV file, it is generated automatically.
Data Management Upload Interfaces 1702 Companies
CUSTOMER
15
6
Product Categories and Products
Product categories and products constitute master data rather than transactional data. Products can be categorized, for example, pens, ink cartridges, and erasers can be grouped in the category Stationery.
Note Semantic Key for Products
The semantic key for products determines the uniqueness of a product record. The following fields are mandatory for product data: ●
PRODUCT_ORIGIN: Origin of the product data
●
PRODUCT_ID: ID of the product data
If the product is related to a category, this relationship is expressed through the category assignment. In this case, the category ID within the product data is depicted as an assignment key. Product categories can be set up in hierarchies: All categories are fixed elements of one particular hierarchy, and can be hierarchically structured amongst themselves by means of the parent category assignment. The description of products and product categories is language-dependent. It consists of the language key , the product or product category name such as MR-750 or Stationery, and the product or product category description such as The MR-750 computer includes 32 GB RAM. or Stationery includes pens, ink cartridges, and erasers.
You can upload product category data and product data separately. In general, you must upload category data before you upload product data (exception: the upload of product data via OData service, seeImporting Products and Product Categories Using OData Service [page 67]). When you upload product data, you can include category ID and hierarchy ID of an existing product category to establish the corresponding assignment. If you do not need product category data, you can leave the fields related to the category empty. When uploading product categories, you can import only one hierarchy per upload process. If you want to update existing product or product category data and add new data, this is possible in one joint upload process. New data will be created while existing data will be overwritten.
Prerequisites for Product Data Upload To import product data, you have to maintain the field PRODUCT_ORIGIN in Customizing for SAP Hybris Marketing under
Contacts and Profiles
Products
Define Origins of Product ID
.
Data Management Upload Interfaces 1702 16
CUSTOMER
Product Categories and Products
Upload of Product Attributes via Interaction Upload If you upload interaction data and the system recognizes that a related product is missing, the system allows you to import product data with the upload of interactions. This option is available only for the initial upload of product data, not for the update of existing product data. When a product is initially uploaded, it is created initially and the new technical key is stored as a reference at the PRODUCT node of the Interaction business object (CUAN_INTERACTION). If the same product is uploaded a second time, the system identifies the existing product and the key is stored again to avoid the creation of duplicates. The existing product is not updated. If you want to update the existing product data, you must use the dedicated product upload. A product that is imported via the interaction upload is available in Segmentation. The import of products via interaction upload is not possible using the CSV import but with OData or any of the other interfaces.
Data Management Upload Interfaces 1702 Product Categories and Products
CUSTOMER
17
7
Best Practices and Troubleshooting
This section contains recommendations for obtaining optimum results during data upload. This includes information about the optimum package size, recommendations for system security and performance optimization, as well as troubleshooting tips if errors occur.
7.1
Recommended Package Sizes and Upload Sequence
Optimum package sizes for the different object types: Table 5: Object Type
Multiple
Recommended Initial Load ●
Parallel upload of entities is not allowed since this can lead to data inconsisten cies.
●
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
Contacts
OData ●
Recommended load: 5000
●
More than 10000 will result in error
●
Data upload is all or nothing. In other words, if an error occurs during upload, no data is uploaded. For this reason, it might make sense to upload smaller pack ages, for example, 10 x 500 entities. In terms of system performance, there is no significance difference in whether you upload 500 or 5000 entities. However you should consider network latency when deciding on the package size, which depends on the quality of the customer data.
Data Management Upload Interfaces 1702 18
CUSTOMER
Best Practices and Troubleshooting
Object Type
Interactions
Recommended Initial Load
Note For CSV and OData imports, import packages containing more than 1000 interac tions are processed asynchronously by default. Packages with 1000 or fewer in teractions are processed synchronously. Customers can change the default set ting for CSV and OData if required in the Customizing table CUANC_CE_IMPSIZE .RFC and Web Service imports are always processed syn chronously. 1. CSV ○
○
With common contact data ○
Max. 10 000 (memory restricted)
○
Recommended 5 000
Without common contact data (IC_UPDATE_MODE = ‚N‘): ○
Data Management Upload Interfaces 1702 Best Practices and Troubleshooting
CUSTOMER
19
Table 6: Error / Error Message
What It Means
What You Can Do
CUAN_INTERACTION 000 Invalid entry
Either:
Maintain Customizing
in column &2: '&1'
Timestamp is incorrect
●
Customizing is missing
Correct invalid entries: for example
●
Invalid characters have been used
Phone numbers have to start with ‘+’ or
●
The format is incorrect
‘00’.
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 num ber. 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 encoding.
Send data in utf-8 encoding. Use an edi tor that supports this.
CSV upload error: No content provided; empty upload
Either: ●
● ●
The selected entity does not match the file content. For example, the entity Contacts has been selected for upload but the file contains Products. There are hidden characters in the first column of the spreadsheet.
The error is probably from the virus
Contact your system administrator
scanner, which is not set up correctly.
Interactions cannot be locked, since
Interactions or Contacts are locked by: ●
Another load in parallel (same con tact is locked in different sessions).
●
file.
The file is really empty.
Unspecific message from CSV upload:
locked by &1
Select the correct option and the correct
Set up your system correctly.
Avoid loading interactions when con tacts are being changed in parallel. Close the report.
A mass change is running on inter actions.
●
Reports (delivered or written by t he customer) are not closed and are locking interactions and/or con tacts.
Data Management Upload Interfaces 1702 20
CUSTOMER
Best Practices and Troubleshooting
Error / Error Message
What It Means
Import failed
Import failed because objects are locked
What You Can Do ●
In the event of lock errors, imports
by another process or because of other
are automatically restarted again in
errors..
the background until there are no more errors. ●
In the event of other errors, imports are not automatically restarted. Since the import file is stored in a staging area for up to 30 days, the administrator can use transaction SE11 or SE16 to check the file and correct errors. The import can then be restarted manually using report CUAN_CE_IA_RESTART_IMPORT.
7.2
Optimizing Performance During OData Service Calls
This section describes how to call an OData service in SAP Hybris Marketing Cloud in a way that ensures a high degree of system security and performance. The description uses CUAN_IMPORT_SRV as an example, but the method applies to all OData services in SAP Hybris Marketing Cloud. Importing Data into the SAP Hybris Marketing Cloud System
1. Reques Requestt an x-CSRF token token and a session session cookie cookie by calling the the metadata metadata document, document, for example, example,https:// /sap/opu/odata/sap/cuan_import_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 payload with with the data you want to to post. 4. Post the data data via the corresponding corresponding endpoint endpoint and send send the x-CSRF token token and the session 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:/// sap.opu.odata/sap/cuan_import_srv/ImportHeaders.
https:// 5. You should should terminate terminate the session session cookie by calling the the logoff service. service. For example, example, https:// /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.
Data Management Upload Interfaces 1702 Best Practices and Troubleshooting
CUSTOMER
21
●
●
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 = '' iv_url = '/sap/opu/odata/sap/cuan_import_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. ENDIF CATCH cx_cuan_cpred_error INTO exc_cpred_error. * Error handling ENDTRY.
Code Syntax *************************************************************************** * Create payload and * send it via post request to the SAP Hybris 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 = '' iv_url = '/sap/opu/odata/sap/cuan_import_srv/ImportHeaders' 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
Data Management Upload Interfaces 1702 22
CUSTOMER
Best Practices and Troubleshooting
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 CSRF-Token and session cookie cookie and try again go to step 1 *... *... ENDIF. ENDWHILE.
Data Management Upload Interfaces 1702 Best Practices and Troubleshooting
CUSTOMER
23
8
Import of Data Using CSV Upload
Import data in CSV file format
Use With the Import Data application, you can upload data for the following objects in Comma Separated Value (CSV) file format: Contacts and Profiles ●
Corporate Accounts
●
Contacts
●
Account Team Members
●
Product Categories
●
Products
●
Interests
●
Interactions
●
Marketing Locations
●
Marketing Beacons
●
Subscriptions
Others ●
Brands
●
Custom dimensions
●
Actual and committed spend
●
Survey Response
●
Campaign Success
Note If you upload data for more than one of these object types, you must observe the following upload sequence: 1. Product categories 2. Products 3. Interaction Contacts 4. Interactions Prerequisites ●
●
Your copy of the following standard roles, gives key users authorization for key activities and administrative tasks, such as uploading data using a CSV file, as well as access to export definitions for target groups and campaigns: The composite role Key User Access (SAP_MARKETING_BUS_ADMIN_USER)
Data Management Upload Interfaces 1702 24
CUSTOMER
Import of Data Using CSV Upload
● ●
●
●
The single role Business Administration (SAP_CEI_KUA) Before you upload data for any given object type, read the important information about it in the section, Special Points to Note About Specific Object Types of this document. Each example file you download contains detailed instructions on how to add values to the spreadsheet for each object type. Read the instructions carefully before uploading data. Assign users responsible for uploading data using a CSV file to a copy of those roles. For more information about roles, see the section Authorizations in the Security Guide for SAP Hybris Marketing on the SAP Help Portal at http://help.sap.com/mkt
Security Information
).
Objects That Can Be Extended
The attributes allowed for each object type are defined in the structures listed in the table. You can display these structures in the system using transaction SE11. Within the structures, there are also a number of fields provided with unspecified names. Add custom fields, if the predelivered fields do not meet your requirements. You can add custom fields under Import Data, as described in the following section: Table 7: Object Type
Structure Name
Corporate accounts (companies)
CUAN_S_CE_COMP_EXT_FAFL
Contacts
CUAN_S_CE_IC_EXT_FAFL
Account team members
CUAN_S_CE_IC_TM_EXT
Products categories
CUAN_T_PROD_CAT_EXT_FLAT
Products
CUAN_S_PRODUCT_EXT_FLAT
Interactions
CUAN_S_CE_IA_EXT_FLAT
Interests
Fixed first row: INTEREST_ITEM and ISO language keys in any sequence
Survey Response
CUAN_T_CE_IA_TAG_FLAT
Adding Values and Uploading CSV Files To import data: 1. Go to
Import Data
.
2. Select the object type for which you want to upload data and choose Download CSV Template. 3. Read the detailed instructions for the object type at the top of the file and enter the required data. 4. To ensure correct handling of special characters, store the CSV file in the UTF-8 code page. 5. Back on the Import Data screen, browse for the file and choose Import.
Data Management Upload Interfaces 1702 Import of Data Using CSV Upload
CUSTOMER
25
Special Points to Note About Specific Object Types ●
Corporate Accounts (Companies): ○ ○
○
○
●
When corporate accounts are uploaded, the origin of the content is set to SAP_FILE_IMPORT by default. If you want to upload the origin of contact IDs, you add the column ID_ORIGIN to the structure. If there is a value for ID_ORIGIN, the ID column must also have a value. If IDs are provided they must be unique and cannot be used more than once in the same CSV file. The uploaded data is available in Corporate Accounts. You can view details for individual corporate accounts in the corresponding fact sheet. The additional fields are available as an attribute in Segmentation, and on the Additional Data facet of the Corporate Account fact sheet.
Contacts: ○ ○
○ ○
○
When contacts are uploaded, the origin of the content is set to SAP_FILE_IMPORT by default. If you want to upload the origin of contact IDs, add the column ID_ORIGIN to the structure. If there is a value for ID_ORIGIN, the ID column must also have a value. If IDs are provided they must be unique and cannot be used more than once in the same CSV file. The uploaded data is available under Contacts and as a filter value under the Profile Dashboard . The additional fields are available in the Additional Data section, on the Personal Data facet, of the Contact fact sheet, and as an attribute in Segmentation. Marketing Permissions for Contacts: Marketing permissions are used to control whether or not communication with a contact is allowed, using a certain communication medium, for example, e-mail. Currently, e-mail is supported as the communication medium. It is used during an automated campaign. This marketing campaign is one with an automatic system reaction, such as a trigger to open an e-mail or click a link within an e-mail. Marketing permissions can be created or updated during the import of contacts. Marketing permissions are created by providing the e-mail address field (SMTP_ADDR or SMTP_ADDR_2), and the corresponding
opt-in field (OPT_IN_SMTP_ADDR or OPT_IN_SMTP_ADDR_2). ●
Account Team Members ○
○
○
Ensure that you have carried out the Customizing activity Define Team Member Roles and that each role is assigned only once per interaction contact. Ensure that the ID_ORIGIN you want to use is not set to shareablein the Customizing activity Define Origins of Contact ID.
Caution
Update mode is full: The account team member data you upload always overwrites any existing data in the system. If you want to keep the existing assignments in the system, add these assignments to the spreadsheet to ensure that they are part of the new upload. If you don't add them, they will be overwritten by the new upload. ●
Product Categories and Products: ○
○
If you want to segment consumers who have bought a certain product or products from a certain category, for example, you can use the uploaded data, including additional fields, for segmentation purposes in Segmentation. Semantic Key: The semantic key for products determines the uniqueness of a product record. The following fields are mandatory for product data: ○
PRODUCT_ORIGIN: Origin of the product data
○
PRODUCT_ID: ID of the product data
Data Management Upload Interfaces 1702 26
CUSTOMER
Import of Data Using CSV Upload
For the product category: Provide the ID and the hierarchy ID in the CSV file.
○
If the product category relates to more than one language, create several rows for the same product category. Generate a separate line for each language, which is identical except for the language.
○
●
Interactions : ○ ○
Provide the origin and the ID in the CSV file. Semantic Key: The semantic key for interactions determines the uniqueness of an interaction record. The following fields are mandatory: Table 8: Semantic Key
What It Means
ID_ORIGIN
Origin of the interaction contact data
ID
External ID of the interaction contact data
IA_TYPE
Interaction type
COMM_MEDIUM
Communication medium
TIMESTAMP
UTC timestamp in long form (YYYYMMDDhhmmssmm muuun)
Recommendation Timestamp entries are sometimes incorrectly con verted to decimal numbers. To prevent incorrect con verting, deactivate decimal notation and 1000 sepa rating commas in the cell formatting settings.
Note
--
The following additional semantic key fields are not checked during import. They can have values or re main empty.
SOURCE_OBJECT_TYPE
Object type of the source object, for example, an oppor tunity in SAP Hybris Cloud for Customer.
SOURCE_OBJECT_ID
Object ID of the source object, for example, the GUID of the SAP Hybris Cloud for Customer opportunity, or the original post ID of the relevant social media network (such as TW or FB).
Data Management Upload Interfaces 1702 Import of Data Using CSV Upload
CUSTOMER
27
○
By filling the field IC_UPDATE_MODE you can control how the contact data is updated. The following update modes are available for the field IC_UPDATE_MODE: Table 9: Update Code
Type of Update What Is Updated
N
No Update
Only the Contact ID is determined. If no contact is found, an error is triggered
F
Full Update
All existing fields are overwritten by imported fields. If empty fields are imported, these imported fields overwrite the corresponding fields with values of the facet.
D
Delta
All imported fields that have values, overwrite existing fields of the same facet of the contact. If the contact doesn't already exist, it is created.
○
○
○
●
The uploaded data is available in the Interactions facets of the fact sheets for corporate accounts and contacts. In addition, you can use the uploaded data including the additional fields for segmentation purposes under Segmentation, such as segmenting consumers who have abandoned their shopping carts in your Web shop.
Marketing Locations ○ ○
○
○
●
If you want to enter multiple interests for one interaction, create several rows for the same interaction due to the flat structure. In this case, only the interest differs, all other columns remain the same.
The values for LOC_ORIGIN and TYPE must exist in the system before you can import your data. Semantic Key: The semantic key for marketing locations determines the uniqueness of a marketing location record. The LOC_ID and LOC_ORIGIN are marketing location's semantic key:
The following fields are mandatory for marketing locations: ○
LOC_ID: Location ID
○
LOC_ORIGIN: Origin of Location ID
○
TYPE: Location Type
○
MKT_AREA_ID : Marketing Area ID
If a combination of LOC_ID and LOC_ORIGIN doesn’t exist in the system, the marketing location is created.
○
If a combination of LOC_ID and LOC_ORIGIN exists in the system, the marketing location is updated.
○
The following fields have system default values: ○
VALID_FROM_DATE. If initial, 0000-00-00 is used
○
VALID_TO_DATE. If initial, 9999-12-31 is used
Marketing Beacons ○
○
The following fields are mandatory for marketing beacons: ○
TYPE: Defaults to iBeacon. Currently iBeacon is the only supported beacon protocol.
○
ID: The unique external ID of the beacon.
○
DESCRIPTION: Description of the beacon. Used to assist in searching for a beacon.
○
UUID: Beacon UUID. Mandatory if TYPE= iBeacon.
○
MAJOR: Beacon major number. Mandatory if TYPE= iBeacon.
○
MINOR: Beacon minor number. Mandatory if TYPE= iBeacon.
If a combination of TYPE, ID, UUID, MAJOR, MINOR exists in the system, the marketing beacon is updated.
Data Management Upload Interfaces 1702 28
CUSTOMER
Import of Data Using CSV Upload
●
Survey Response: ○ ○
○
Provide the ID origin and the ID or the Outbound ID in the CSV file. After downloading survey responses from the third party survey tool SurveyMonkey, transform the data in the required format in the Template_Survey_Response.csv file, using Microsoft Excel macro or Apple Mac Macro. Semantic Key: The semantic key for interactions determines the uniqueness of an interaction record. The following fields are mandatory: Table 10: Semantic Key
What It Means
ID_ORIGIN
Origin of the interaction contact data
ID
External ID of the interaction contact data
Outbound ID
Unique identification of interaction that is generated when a campaign is triggered
IA_TYPE
Interaction type
COMM_MEDIUM
Communication medium
TIMESTAMP
UTC timestamp in long form (YYYYMMDDhhmmssmm muuun)
Recommendation Timestamp entries are sometimes incorrectly con verted to decimal numbers. To prevent this incorrect conversion, deactivate decimal notation and 1000 separating commas in the cell formatting settings.
SURVEY_NAME
Name of the survey
SURVEY_URL
URL of the survey
ANSWER
Answer of each survey question provided by the interac tion contact. The format is “question: [answer]”.
Note The maximum length allowed for an answer is 200 characters.
●
Interests ○
○ ●
The first column INTEREST_ITEM is fixed. If needed, you can add language columns in any order, using the required ISO language codes. There must be at least one description for an interest.
Campaign Success
Data Management Upload Interfaces 1702 Import of Data Using CSV Upload
CUSTOMER
29
○
○
Choose the campaign category for which you want to upload data. The CSV template is generated dynamically based on your selection. Each campaign category is associated to a process type, which determines the campaign type. You can upload campaign success data for campaign categories associated to the following process types: ○
Externally-Executed Campaigns
○
Facebook Campaigns
○
Paid Search Campaigns
Externally-Executed, Facebook, and Paid Search Campaigns ○
For externally-executed, Facebook, and Paid Search campaigns, if the value for EXT_CAMPAIGN_ID already exists in the system, the data is automatically assigned to the campaign with this ID. If the EXT_CAMPAIGN_ID does not exist in the system, an unassigned data set is created and you can assign it to a campaign later. This is the campaign ID that was generated in an external system, in Facebook, or in Google AdWords when the campaign was created, or the externally-generated or Facebook campaign ID that you manually assigned to your campaign in the system. This is not the campaign ID generated when you create a campaign in SAP Hybris Marketing.
When data is uploaded for an existing EXT_CAMPAIGN_ID and REPORTING_DATE, the previous data is overwritten with the latest KPIs for that campaign. For more information, see Assigning Success Data to Externally Executed, Facebook, and Paid Search Campaigns. ○
●
Brands For each row of the input file, the following applies: ○ ○
○ ●
If a brand ID does not exist in the system, the brand is created. If a brand description does not exist for a brand ID in the corresponding language, the brand description is created. Otherwise, the brand description is updated with the value from the file. If there is invalid data in the local file, no brand data is saved.
Custom Dimensions For the upload of values for a custom dimension, the following applies (custom dimensions must be defined in
Customizing for SAP Hybris Marketing under ○
Planning
Budget Plans
Define Custom Dimensions ): :
The file must contain the name of the custom dimension for which values are uploaded. You can only upload values for one custom dimension for a specific file. For example, the custom dimension with ID LOB has been defined, where LOB represents Line of Business. The upload file for values for LOB custom dimension must be as follows: * LOB ID,LANGUAGE,DESCRIPTION INSURE,E,Insurance INVEST,E,Investments CONSULT,E,Consulting
●
Actual and Committed Spend For the upload of actual and committed spend, the following fields are available: ○
SOURCE ID
The source ID is optional and contains 30 characters. The source ID indicates the source of the spend information, for example, it can indicate the agency from which the spend originates. ○
CAMPAIGN ID
The campaign ID is mandatory and contains 10 characters. Campaigns have been created in the Campaigns application, or in the Detailed Campaign Spend application. ○
SPEND TYPE
Data Management Upload Interfaces 1702 30
CUSTOMER
Import of Data Using CSV Upload
Spend types are optional and have been defined in Customizing for SAP Hybris Marketing under Planning ○
Spend Management
Define Spend Types .
SPEND ITEM ID
The spend item ID is optional and contains 10 numeric characters. If specified, the spend item ID must exist in the campaign and the spend type must match. If no spend type is specified, the spend type is derived from the spend item of the campaign ○
REFERENCE DATE
The date is mandatory and is used for currency conversion. The reference date must be a valid date in the following format YYYYMMDD. ○
ACTUAL SPEND AMOUNT
The actual spend amount is mandatory and zero values are allowed. The actual spend amount represents the actual costs that have been incurred from marketing activities. ○
COMMITTED SPEND AMOUNT
The committed spend amount is mandatory and zero values are allowed. The committed spend amount represents the amount of already known spend based on existing requests and orders for an item, for example, from a purchasing system. ○
CURRENCY
Currency is mandatory and is the code for the spend amount. For the upload of actual and committed spend, the following rules apply: ○
○ ○
○
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. Use a period (.) to separate decimals in amounts. If a field is optional and you do not want to include a value for it in the file, 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. The following is an example of the content of an input file: ○
Provide the ID and the ID Origin of the Contact in the CSV file.
○
Semantic Key: The semantic key for interactions determines the uniqueness of an interaction record.
Data Management Upload Interfaces 1702 Import of Data Using CSV Upload
CUSTOMER
31
The following fields are mandatory: Table 11: Semantic Key
What It Means
ID_ORIGIN
Origin of the interaction contact data
ID
External ID of the interaction contact data
MKT_PERM_COMM_MEDIUM
Outbound Communication Medium for which marketing per mission has been given
COMM_MEDIUM
Communication medium
Table 12: Other Fields Semantic Key
What It Means
TIMESTAMP
This field is optional. If nothing is entered, the interaction is given the current timestamp.
COMM_CAT_ID
Communication Communica tion Category ID for which the subscription is set. If nothing is entered, a general Marketing Permission for the specified ID / ID Origin and Communication Medium is set.
OPT_IN
This field is mandatory. Y must be entered for an opt-in, N for an opt-out.
Checks During Upload
During the upload, the system performs the format checks and conversions listed here. The content validation stops with the first error. The system only saves and uploads the content if no errors occur. ●
●
●
●
Date values The SAP date format (YYYYMMDD) and the date format specified in the user profile are allowed. Integer values: Integer values with or without separators are allowed, for example 1.317.208. Timestamp values: The SAP date, SAP date & time (YYYYMMDDhhmmss), or the time stamp long (YYYYMMDDhhmmss,aaaaaaa) values are allowed with or without separators. E-mail values are allowed in the following format: {name}@{domain}
Additional Upload Interfaces In addition to this manual upload option, you can also import mass data into your system using one of the following upload interfaces: ●
OData service
●
Remote function call (RFC)
Data Management Upload Interfaces 1702 32
CUSTOMER
Import of Data Using CSV Upload
Web service
●
Note ●
●
●
For detailed information about the other upload interfaces and about importing the master data entities interaction contacts, contacts, interactions, corporate accounts (companies), (companies), interests, product categories, and products using OData service CUAN_IMPORT_SRV, see the Data Management Upload Interfaces Guide for the current release at http://help.sap.com/mkt http://help.sap.com/mkt.. For more information about importing offers using OData, see the Extensibility Guide at http:// help.sap.com/mkt The OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV is used for standard SAP Hybris Marketing integration with SAP Hybris Cloud for Customer. It is used in marketing-driven, and sales-driven processes. For information about replicating SAP Hybris Cloud for Customer business documents to SAP Hybris Marketing interactions using the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV, see the http://help.sap.com/mkt.. Importing Business Documents guide at http://help.sap.com/mkt
Data Management Upload Interfaces 1702 Import of Data Using CSV Upload
CUSTOMER
33
9
Import of Data Using OData Service CUAN_IMPORT_SRV
You can import interaction contacts, interactions, corporate accounts (companies), interests, product categories, and products into SAP Hybris Marketing using OData service CUAN_IMPORT_SRV. We recommend that you do not use batch processing ($batch) because error handling is more complex. A batch request can return an OK code and still have errors that have to be looked up in the response body. You can still send multiple entities in one POST request without using batch processing. See chapter 9.2 Importing Interaction Contacts Using OData Service for an example of how to do this for interactions contacts. The same procedure also applies to all other entities you import with this service.
Note Note about importing business documents: The OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV
should be used to create SAP Hybris Marketing interactions from business documents from any source system. In contrast to OData service CUAN_IMPORT, CUAN_BUSINESS_DOCUMENT_IMP_SRV (Business Documents) enables you to change interactions. Each business 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 is used for standard integration of SAP Hybris Marketing with SAP Hybris Cloud for Customer. It is also used in marketing-driven and sales-driven processes. For information about using the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV see https://help.sap.com/http.svc/rc/ 2f2c6c46ef044da7a62c01ba617d68b4/1702%20YMKT/en-US/ InterfaceDocuBusinessDocumentImport_1702.pdf.. InterfaceDocuBusinessDocumentImport_1702.pdf
Prerequisites ● ●
The SICF node for the external service name CUAN_IMPORT_SRV (mass data import for SAP Hybris Marketing) has been maintained in the SAP Hybris Marketing gateway system (which is either the SAP Hybris Marketing back-end system or a remote gateway system, depending on your setup). You can check in transaction SICF if the service is available (usually, the service is implemented during the standard installation process of SAP Hybris Marketing ).
Authorization Users who want to consume the CUAN_IMPORT_SRV OData service, must have the following authorizations: ●
OData-Service CUAN_IMPORT_SRV
●
Action authorizations for import; Authorization Object HPA_ACTION
Data Management Upload Interfaces 1702 34
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
●
Authorization to call the external service (role SAP_CEI_ECOMMERCE_INTEGRATION in transaction PFCG – this role contains all required authorizations. You can copy and adapt this role according to your requirements. For more information, see section Authorizations in the security guide for SAP Hybris Marketing under http:// help.sap.com/mkt
Security Information
.
-
HPA_ACTION
HPA_OBJ
ACTVT
Interactions
IMPORT_EXTERNAL_INTERAC
CUAN_INTERACTION
16
CUAN_INTERACTION_CONTAC
16
TIONS
Team Member
IMPORT_IC_TEAM_MEMBER
T
Contacts/Companies
16
IMPORT_INTERACTION_CONT
CUAN_INTERACTION_CONTAC
ACTS
T
Interests
IMPORT_INTERESTS
CUAN_INTEREST
16
Products
IMPORT_PRODUCTS
CUAN_PRODUCT
16
Product Categories
IMPORT_PROD_CAT_HIERS
CUAN_PROD_CATEGORY_HIER
16
ARCHY
Mass Import The OData protocol allows the import or update of one object record (contact, interaction, company, product, or product category) 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 entity Import Header and create interaction contacts, interactions, companies, products, or product categories as subnodes of the import header. The metadata of the service is read by means of the OData call: ●
Additional Fields If you have created additional, custom fields for your structures, you can view the naming conventions for these fields in the OData Service using the Request URI listed above.
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
35
9.1
Structure of OData Service CUAN_IMPORT_SRV
The CUAN_IMPORT_SRV OData service consists of the following entity sets and entity types: Table 13: Entity Set
Entity Type
Entity Type Description
AccountTeamMembers
AccountTeam
Account Team Member
Companies
Company
Company
Contacts
Contact
Interaction Contact
ContactFacets
ContactFacet
Additional facets
ContactMarketingAttributes
ContactMarketingAttributes
Marketing attributes
ContactMarketingPermissions
ContactMarketingPermission
Marketing permissions
ImportHeaders
ImportHeader
Technical Import Message Header
Interactions
Interaction
OData Import Interaction
InteractionAdditionalObjectRefer
InteractionAdditionalObjectRe
Additional object references of an inter
ences
ference
action
InteractionDigitalAssetSets
InteractionDigitalAsset
Digital Assets belonging to an interaction
InteractionInterests
InteractionInterest
Item of interest belonging to an interac tion
InteractionOffers
InteractionOffer
Offers belonging to an interaction
InteractionTags
InteractionTag
Tags belonging to an interaction
Products
Product
OData Import Product
InteractionProducts
InteractionProduct
Product belonging to an interaction
ProductCategories
ProductCategory
OData Import Product Category
Interests
Interest
OData Import Interest
Entity Type "ImportHeader" The entity type ImportHeader describes the technical header of an import of interaction contacts. The properties Id, Timestamp, and UserName are used for logging the external data request. For every service request a new, unique ID is required. If no ID is provided, it is defaulted internally.
Data Management Upload Interfaces 1702 36
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
The SourceSystemId property allows you to distinguish between different source systems. The value is later on used as prefix to create unique external contact IDs stored as a facet while a facet is a reference to an external system (as one and the same interaction contact can have different IDs in different systems such as ERP, Twitter, or Facebook). The SourceSystemId is a mandatory attribute. Id, Timestamp, and UserName of the back-end user are defaulted when no values are given. ImportHeader Meta Information Table 14: Property
Description
Edm Core Type
Max
Mandatory
Key
Len gth Id
Unique technical identifier of
Edm.String
0
Edm.DateTime
0
X
import run. If this is not pro vided, it is defaulted internally. If you provide the same ID twice, it will lead to an error code 500. Timestamp
Timestamp of the import run in the format: number of milli seconds since midnight Jan 1, 1970. For example: "/ Date(1406014140922)/"
UserName
User name
Edm.String
0
SourceSystemType
Type of source system
EDM.string
3
SourceSystemId
Identifier of source system
Edm.String
20
ForceSynchronousPr
If this flag is set, you can firce
Edm.Boolean
ocessing
imports to be processed syn
X
chronously regardless of the size of the upload file.
Entity Type "Account Team Member" The entity type AccountTeamMembercontains all attributes that are required to assign team members to interaction contacts (company or person). Interaction contacts are identified by the information filled in the attributes InteractionContactId and InteractionContactIdOrigin. The UserId is the identifier of a user in the system that shall be assigned as team member to the interaction contact. The role is the business role in which the team member acts for this interaction contact.
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
37
Table 15: Property
Description
Edm Core Type
Max Length
Key
InteractionContact
Identifier of an interac
Edm.String
100
X
Id
tion contact facet
InteractionContact
Origin of Interaction
Edm.String
20
X
IdOrigin
Contact ID
UserId
User ID of team mem
Edm.String
12
X
Edm.String
4
X
ber Role
Role
Entity Type "Company" The entity type Company contains all attributes that are required to create a company (corporate account) with its main facets. If the ID of the company is provided by the external source system, the system can identify the company for later updates. The IdOrigin property must exist in the system either as a value delivered by SAP and implemented during the standard installation process of SAP Hybris Marketing or as a value configured by the customer in Customizing for SAP Hybris Marketing (transaction SPRO) under Interaction Contacts
Contacts and Profiles
Define Origins of Contact ID .
If no IdOrigin is provided, the system sets a technical ID Origin (SAP_ODATA_IMPORT) and concatenates the provided ID with the provided source system ID (which is derived from the property SourceSystemId of the ImportHeader. However it is not recommended to provide no ID Origin since you lose the information about the source of the data. Therefore, you should always provide an ID Origin, which describes the origin of the data and which must be unique per connected source system.
Example EMailAddress Property:
A company can write e-mails to a company. The EMailAddress property is the ID of this company used in this communication channel. The EMailAddress is only one facet of this company. The company may use other facets (such as Facebook, Google+, or Twitter) in other communication channels. If the ID of the company is not provided by the external source system, it will be generated in the back-end system. In this case, an update of a company is not possible. The result ID of the update will be stored in attribute SAP_ODATA_IMPORT of the facet ID_ORIGIN, whether the ID of the company has been provided or not. Company Meta Information
Data Management Upload Interfaces 1702 38
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Table 16: Property
Description
Edm Core Type
Max Length
Key
Id
Identifier provided by
Edm.String
100
X
X
external system IdOrigin
Origin or source of ID
Edm.String
20
Timestamp
Timestamp
Edm.DateTime
0
Edm.String
40
Format: number of mil liseconds since mid night Jan 1, 1970. For example: "/ Date(1406014140922)/ " City
City as part of postal address
CountryDescription
Name of country
Edm.String
40
EMailAddress
E-mail address
Edm.String
241
EMailOptIn
Opt-in for e-mail ad
Edm.String
1
dress FacebookId
Identifier for Facebook
Edm.String
255
FacebookOptIn
Opt-in for Facebook
Edm.String
1
FaxNumber
Fax number
Edm.String
30
Format: +country code region code + fax num ber e.g. +49 6227 123456 FaxOptIn
Opt-in for fax number
Edm.String
1
GooglePlusId
Identifier for Google +
Edm.String
255
GooglePlusOptIn
Opt-in for Google +
Edm.String
1
HouseNumber
House number as part
Edm.String
10
Edm.String
1000
Edm.String
40
of postal address ImageURI
Uniform Resource Identifier of image
LanguageDescriptio
Name of communica
n
tion language
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
39
Property
Description
Edm Core Type
Max Length
Latitude
Geographical coordi
Edm.Decimal
0
Edm.Decimal
0
Edm.String
30
Edm.String
1
Key
nate Longitude
Geographical coordi nate
MobilePhoneNumber
Phone number for mo bile Format: +country code region code + phone number e.g. +49151123456
MobilePhoneOptIn
Opt-in for mobile con tact
MobileSMSOptIn
Opt-in for mobile SMS
Edm.String
1
Name
Name of company
Edm.String
80
Obsolete
Contact is obsolete
Edm.Boolean
0
PhoneNumber
Phone number for mo
Edm.String
30
Edm.String
1
Edm.String
10
bile Format: +country code region code + phone number e.g. +49151123456 PhoneOptIn
Opt-in for mobile con tact
PostalCode
Postal code as part of postal address
RegionDescription
Name of region
Edm.String
40
SAPCRMBusinessPart
SAP CRM Business
Edm.String
10
nerId
Partner identifier
SAPCRMMarketingPro
SAP CRM Marketing
Edm.String
10
spectId
Prospect identifier
Street
Street as part of postal
Edm.String
60
Edm.String
255
address TwitterId
Identifier for Twitter
Data Management Upload Interfaces 1702 40
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Property
Description
Edm Core Type
Max Length
TwitterOptIn
Opt-in for Twitter
Edm.String
1
WebSite
Web site
Edm.String
1,000
Key
Entity Type "Contact" The entity type Contact contains all attributes that are required to create an interaction contact with its main facets. If the ID of the contact is provided by the external source system, the system can identify the contact for later updates. The IdOrigin property must exist in the system either as a value delivered by SAP and implemented during the standard installation process of SAP Hybris Marketing, or as a value configured by the customer in Customizing for SAP Hybris Marketing (transaction SPRO) under Define Origins of Contact ID
Contacts and Profiles
Interaction Contacts
.
If no IdOrigin is provided, the system sets a technical ID Origin (SAP_ODATA_IMPORT) and concatenates the provided ID with the provided source system ID (which is derived from the property SourceSystemId of the ImportHeader. However it is not recommended to provide no ID Origin since you lose the information about the source of the data. Therefore, you should always provide an ID Origin, which describes the origin of the data and which must be unique per connected source system. Some of the Contact properties are identifiers for facets under which a contact is known in the outside world.
Example EMailAddress Property:
A contact can write mails to a company. The EMailAddress property is the ID of this contact used in this communication channel. The EMailAddress is only one facet of this contact: The contact may use other facets (such as Facebook, Google+, or Twitter) in other communication channels. If the ID of the contact is not provided by the external source system, it will be generated in the back-end system. In this case an update of a contact is not possible. The result ID of the update will be stored in attribute SAP_ODATA_IMPORT of the facet ID_ORIGIN, if the ID of the contact has been provided or not. A contact can be classified to be used in different processes. 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. Contact Meta Information
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
41
Table 17: Property
Description
Edm Core Type
Id
Identifier provided by external sys Edm.String
Max Length
Key
100
X
X
tem IdOrigin
Origin or source of ID
Edm.String
20
Timestamp
Timestamp
Edm.DateTime
0
Edm.String
40
Format: number of milliseconds since midnight Jan 1, 1970. For ex ample: "/Date(1406014140922)/" City
City as part of postal address
CompanyId
Id of a company for which a person Edm.String
100
acts as contact CompanyIdOrigin
Origin or source of company ID
Edm.String
20
CountryDescription
Name of country
Edm.String
40
CustomerName
Name of customer for which a per Edm.String
40
son acts as contact DepartmentDescriptio
Name of department type (classi
Edm.String
40
n
fication as contact)
EMailAddress
1st e-mail address
Edm.String
241
EMailOptIn
Opt-in for e-mail contact for 1st e-
Edm.String
1
Edm.String
241
mail address EMailAddress2
2nd e-mail address
EMail2OptIn
Opt-in for e-mail contact for 2nd e- Edm.String
1
mail address EMailAddress3
3rd e-mail address
Edm.String
241
EMail3OptIn
Opt-In for e-mail contact for 3rd
Edm.String
1
eMail address FacebookId
Identifier for Facebook
Edm.String
255
FacebookOptIn
Opt-in for Facebook
Edm.String
1
FaxNumber
Fax number
Edm.String
30
Format: +country code region code + fax number e.g. +49 6227 123456
Data Management Upload Interfaces 1702 42
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Property
Description
Edm Core Type
Max Length
FaxOptIn
Opt-in for fax number
Edm.String
1
FirstName
First name
Edm.String
40
FullName
Full name
Edm.String
80
FunctionDescription
Name of job function (classifica
Edm.String
40
Key
tion as contact) GenderDescription
Gender description
Edm.String
40
GooglePlusId
Identifier for Google +
Edm.String
255
GooglePlusOptIn
Opt-in for Google plus
Edm.String
1
HouseNumber
House number as part of postal
Edm.String
10
Edm.String
1000
address ImageURI
Uniform Resource Identifier of image
IndustryDescription
Name of industry (classification as Edm.String
40
contact) IsConsumer
Indicates whether person is a con
Edm.Boolean
0
Edm.Boolean
0
sumer IsContact
Indicates whether person acts as contact for an account
LanguageDescription
Name of communication language
Edm.String
40
LastName
Last name
Edm.String
40
Latitude
Geographical coordinate
Edm.Decimal
Longitude
Geographical coordinate
Edm.Decimal
MaritalStatusDescrip
Marital status description
Edm.String
20
Phone number for mobile
Edm.String
30
tion MobilePhoneNumber
Format: +country code region code + phone number e.g. +49151123456 MobilePhoneOptin
Opt-in for mobile contact
Edm.String
1
MobileSMSOptin
Opt-in for mobile SMS
Edm.String
1
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
43
Property
Description
Edm Core Type
Max Length
Obsolete
Contact is obsolete
Edm.Boolean
0
PhoneNumber
Phone number
Edm.String
30
Key
Format: +country code region code + phone number e.g. +49151123456 PhoneOptin
Opt-in for phone contact
Edm.String
1
PostalCode
Postal code as part of postal ad
Edm.String
10
dress PostalOptin
Opt-in for postal contact
Edm.String
1
RegionDescription
Name of region
Edm.String
40
SAPCRMBusinessPartne
SAP CRM Business Partner identi
Edm.String
10
rId
fier (classification as contact)
SAPCRMMarketingProsp
SAP CRM Marketing Prospect
Edm.String
10
ectId
identifier
SAPERPAccountId
SAP ERP Account identifier (clas
Edm.String
10
Edm.String
10
10
sification as contact) SAPERPConsumerAccoun
SAP ERP Consumer account iden
tId
tifier (classification as consumer)
SAPERPContactId
SAP ERP Contact identifier (classi Edm.String fication as contact)
SAPHybrisConsumerAcc
SAP Hybris Consumer account
ountId
identifier (classification as con
Edm.String
100
sumer) Street
Street as part of postal address
Edm.String
60
TitleDescription
Title description
Edm.String
40
TwitterId
Identifier for Twitter
Edm.String
255
TwitterOptIn
Opt-in for Twitter
Edm.String
1
Entity Type "ContactFacet" If additional facets are needed, you must use the entity set ContactFacets based on the entity type ContactFacet. For every additional facet one instance of the ContactFacet entity type must be provided.
Data Management Upload Interfaces 1702 44
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
ContactFacet Meta Information Table 18: Property
Description
Edm Core Type
Max Length
Key
Id
Facet Identifier
Edm.String
255
X
IdOrigin
Origin of facet identifier (values de Edm.String
20
X
fined in Customizing view CUANV_CE_ORIGIN )
(Creation) Timestamp of facet
Timestamp
Edm.DateTime
0
Edm.String
1
Format: number of milliseconds since midnight Jan 1, 1970. For ex ample: "/Date(1406014140922)/" Opt-in for contact facet
OptIn
If the ID of the contact is provided by the external source system, the system can identify the contact for later updates. The IdOrigin property must exist in the system either as a value delivered by SAP and implemented during the standard installation process of SAP Hybris Marketing, or as a value configured by the customer in Customizing for SAP Hybris Marketing (transaction SPRO) under Define Origins of Contact ID
Contacts and Profiles
Interaction Contacts
.
Entity Type "ContactLocation" If contacts should be assigned to a marketing location, you must use the entity set ContactLocations based on the entity type ContactLocation. Table 19: ContactLocation Meta Information Property
Description
Edm Core Type
Max Length
Key
LocationIdOrigin
Origin of a location
Edm.String
30
X
Edm.String
50
X
identifier (values de fined in Customizing view CUANV_LOC_ORI) LocationId
Identifier of a location
The LocationIdOrigin can be configured by the customer in Customizing for SAP Hybris Marketing (transaction SPRO) under ID
Contacts and Profiles
Marketing Locations
Define Origins of Marketing Location
.
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
45
Entity Type "ContactMarketingAttribute If marketing attributes are needed, you must use the entity set ContactMarketingAttributes based on the entity type ContactMarketingAttribute. For every marketing attribute, one instance of the ContactMarketingAttribute entity type must be provided. Table 20: ContactMarketingAttribute Meta Information Property
Description
Edm Core Type
Max Length
Key
CategoryId
External identifier for
Edm.String
75
X
Edm.String
40
X
Edm.String
16
-
Edm.String
255
X
marketing category CategoryDescripti
Description of market
on
ing category
LanguageDescripti
Language in which cat
on
egory description is provided Value of marketing at
Value
tribute
Either CategoryId or CategoryDescription can be used to identify a marketing category. CategoryDescriptions are language dependent. LanguageDescription can be used to set the language of a CategoryDescription. Language belonging to LanguageDescription must exist in the system otherwise language of communication user will be used. The value is language independent.
Entity Type "ContactMarketingPermission" If additional marketing permissions are needed, you must use the entity set ContactMarketingPermissions based on the entity type ContactMarketingPermission. For every additional marketing permission, one instance of the ContactMarketingPermission entity type must be provided. Table 21: ContactMarketingPermission Meta Information Property
Description
Edm Core Type
Max Length
Key
Id
Facet Identifier
Edm.String
255
X
IdOrigin
Origin of facet identifier (values de Edm.String
20
X
0
-
fined in Customizing view CUANV_CE_ORIGIN ) Timestamp
(Creation) Timestamp of facet
Edm.DateTime
Format: number of milliseconds since midnight Jan 1, 1970. For ex ample: "/Date(1406014140922)/"
Data Management Upload Interfaces 1702 46
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Property
Description
Edm Core Type
Max Length
Key
OptIn
Consent
Edm.String
1
-
OutboundCommunicatio
Communication to which the con
Edm.String
20
X
nMedium
sent is given
CommunicationDirecti
Whether the direction of permis
Edm.String
1
X
on
sion is inbound (I) or outbound (O)
CommunicationCategor
Id of a Communication Category
Edm.String
10
-
yId
available in the system (e.g. news letter)
If the ID of the contact is provided by the external source system, the system can identify the contact for later updates. The IdOrigin property must exist in the system either as a value delivered by SAP and implemented during the standard installation process of SAP Hybris Marketing, or as a value configured by the customer in Customizing for SAP Hybris Marketing (transaction SPRO) under Define Origins of Contact ID
Contacts and Profiles
Interaction Contacts
.
The OutboundCommunicationMedium property must exist in the system either as delivered value by SAP, implemented during the standard installation process of SAP Hybris Marketing, or as a value configured by the customer in Customizing of SAP Hybris Marketing (transaction SPRO) under Interactions
Contacts and Profiles
Define Communication Media .
The CommunicationDirection property is not a required field. If you enter nothing, the default is O for outbound. The CommunicationCategoryId must available in the system. The CommunicationCategoryId could represent, for example, a newsletter for which permission is given or withdrawn.
Associations for Interaction Contacts You have the option to create several interaction contacts with several additional facets by using one OData request. The relations are as follows: Table 22: Associations
Principal Entity
Cardinality of Princi
Dependent Ent it y
pal Entity CompanyContactFace
Cardinal it y of Depe nd ent Entity
Company
One
ContactFacet
Many
Company
One
ContactMarketingAt
Many
ts CompanyContactMark etingAttribute
tribute
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
Entity Type "Interaction" Entity type Interaction contains all attributes needed to create interactions with their interests and related products. Interaction Meta Information Table 23: Property
Description
Edm Core Type
Key
Identifier (GUID) of interaction Edm.String
Max Length
Mandatory
32
Key
X
in this import. Defaulted inter nally! CampaignId
CRM Campaign ID
Edm.String
24
CommunicationMedi
Communication Medium
Edm.String
20
External ID of Interaction Con
Edm.String
255
X
um ContactId
tact Data
Data Management Upload Interfaces 1702 48
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Property
Description
Edm Core Type
Max Length
Mandatory
ContactIdOrigin
Origin of Interaction Contact
Edm.String
20
X
Key
Data ContentData
Interaction Content Data
Edm.String
ContentTitle
Interaction Content Title
Edm.String
255
Device
Device
Edm.String
80
DigitalAccountId
Digital Account ID
Edm.String
40
DigitalAccountTyp
Digital Account Type
Edm.String
10
InitiativeId
Campaign ID
Edm.String
10
InitiativeVersion
Edition (Version)
Edm.Int32
10
InteractionType
Interaction Type
Edm.String
20
IsAnonymous
Indicates whether interaction
Edm.Boolean
n/a
Edm.Decimal
n/a
Longitude of a geographical lo Edm.Decimal
n/a
e
X
is anonymous Latitude
Latitude of a geographical lo cation
Longitude
cation Spatial Reference Identifier
Edm.String
10
Origin of Marketing Location
Edm.String
30
Location ID
Edm.String
50
Campaign Content Identifier
Edm.Int32
10
MarketingPermissi
Communication medium for
Edm.String
20
onCommunicationMe
which permission has been
dium
given
MarketingPermissi
Direction of the communica
Edm.String
1
onDirection
tion medium for which permis
Edm.Int16
5
SpatialReferenceI dentifier MarketingLocation Origin MarketingLocation Id MarketingOrchestr ationId
sion has been given Quantifier
Interaction Quantifier
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
49
Property
Description
Edm Core Type
Max Length
Reason
Reason for a certain interac
Edm.String
40
Mandatory
Key
tion Example: Interaction Type EMAIL_BOUNCE_SOFT ; nterac
tion Reason: MAILBOX_FULL SourceDataUrl
URL of Source Data
Edm.String
SourceObjectId
Interaction source object ID
Edm.String
50
SourceObjectType
Interaction Source Object type Edm.String
30
SourceObjectAddit
The external object ID of the
Edm.String
50
ionalId
source object
SourceSystemId
Interaction Source System ID
Edm.String
255
SourceSystemType
Interaction Source System
Edm.String
20
Type StartingPointUrl
URL of Starting Point
StartingPointText
Text displayed at starting point Edm.String
255
Timestamp
UTC Timestamp
Edm.DateTime
21
Edm.String
X
Format: number of millisec onds since midnight Jan 1, 1970. For example: "/ Date(1406014140922)/" Valuation
Interaction Valuation
Edm.Int16
3
Amount
Amount
Edm.Decimal
31
Currency
Currency Code
Edm.String
3
Entity Type "InteractionInterest" If additionally items of interest for the interactions are needed entity type InteractionInterest has to be used. InteractionInterest Meta Information
Data Management Upload Interfaces 1702 50
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Table 24: Property
Description
Edm Core Type
Max Length
Key
Identifier (GUID) of interac
Edm.String
32
40
Mandatory
Key
X
tion interest in this import Defaulted internally! Interest
Item of interest
Edm.String
Quantifier
Weighting Factor
Edm.Int16
X
Interests must exist in the system either as values deliveredby SAP or configured by the customer in Administration
Business
Manage Interests . .
Entity Type "InteractionProduct" If additionally product references for interactions are needed entity type InteractionProduct has to be used. InteractionProduct Meta Information Table 25: Property
Description
Edm Core Type
Max Length
Key
Identifier (GUID) of interac
Edm.String
32
Mandatory
Key
X
tion product in this import Defaulted internally! ItemId
Item id
Edm.String
50
X
ItemType
Item type
Edm.String
30
X
RecommendationModelT
Product recommendation
Edm.String
30
ypeID
model type id
SourceSystemId
Interaction source system id
Edm.String
255
Amount
Product related amount (re
Edm.Decimal
31
lated currency is on root only) Description
Product description
Edm.String
120
ImageUrl
URL of a product image
Edm.String
1333
Name
Product name
Edm.String
40
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
51
Property
Description
Edm Core Type
Max Length
NavigationURL
URL to the product details
Edm.String
1333
Mandatory
Key
page Quantifier
Weighting factor
Edm.Int16
Quantity
Product related quantity
Edm.Decimal
22
UnitOfMeasure
Unit of measure of product
Edm.String
3
quantity Valuation
sentiment or opinion of inter Edm.Int16 action contacts
Entity Type "InteractionProductCategory" If additionally product category references for interactions are needed entity type InteractionProductCategory has to be used. InteractionProductCategoryMeta Information Table 26: Property
Description
Edm Core Type
Max Length
Mandatory
Key
HierarchyId
External Identifier of a prod uct category hierarchy
Edm.String
50
X
X
CategoryId
External Identifier of a prod
Edm.String
50
X
uct category Quantifier
Weighting factor
Edm.Int16
Valuation
Sentiment or opinion of in
Edm.Int16
teraction contacts
Entity Type "InteractionAdditionalObjectReference If additional object references for interactions are needed, the entity type InteractionAdditionalObjectReference has to be used. Meta Information for InteractionAdditionalObjectReference
Data Management Upload Interfaces 1702 52
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Table 27: Property
Description
Edm Core Type
Max Length
Mandatory
Key
ObjectType
Type of the object
Edm.String
30
X
X
ID of the object ref Edm.String
50
X
X
referenced ObjectId
erenced
Entity Type "InteractionDigitalAsset" If additional digital asset references for interactions are needed, the entity typeInteractionDigitalAsset has to be used. Meta Information for InteractionDigitalAsset Table 28: Property
Description
Edm Core Type
Max Length
Mandatory
Key
SourceSystemId
Source system of
Edm.String
255
X
X
Edm.String
50
X
X
Edm.String
120
Edm.String
256
the digital asset ID of the digital asset Id
Source system of the digital asset ID of the digital asset
Name
Name of the digital asset
MIMEType
MIME type of the digital asset, for ex ample text, image, audio or video
URL
URL where the digi Edm.String
1.333
tal asset is located CampaignID
Campaign ID
Edm.String
10
Entity Type "InteractionOffer" InteractionOffer Meta Information
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
53
Table 29: Property
Description
Edm Core Type
Max Length
Mandatory
Key
Origin
Origin of the offer
Edm.String
30
X
X
Id
Identifier of the offer
Edm.String
10
X
X
ContentItemId
ID of the content item of the
Edm.String
5
Edm.String
50
offer RecommendationSce
ID of the recommendation
narioId
scenario
Entity Type "InteractionTag" If additionally tag references for interactions are needed, the entity type InteractionTag has to be used. Meta Information for InteractionTag Table 30: Property
Description
Edm Core Type
Max Length
Mandatory
Key
TagType
Type of the tag
Edm.String
75
X
X
Tag
ID of the tag
Edm.String
200
X
X
Associations for Interactions With one OData request you can create several interactions with several additional items of interest and/or products, additional object references, digital assets, offers, or tags. The relations are as follows: Table 31: Associations
Entity Type "Interest" Meta Information for Interest Table 32: Property
Description
Edm Core Type
Max Length
Mandatory
Key
Description
Description of the interest
Edm.String
120
X
-
Language
Language code
Edm.String
2
X
X
Id
ID of the interest
Edm.String
40
X
X
Associations for Interests You can create several interests with several additional items of product categories with one OData request. The relations are as follows: Table 33: Association
Principal Entity
Cardinality of Princi
Dependent Ent it y
pal Entity InterestProductCat
Interest
one
Cardinal it y of Depe nd ent Entity
ProductCategory
many
egories
Entity Type "ProductCategory" Entity type ProductCategory contains all attributes needed to create product categories.
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
55
ProductCategory Meta Information Table 34: Property
Description
Edm Core Type
Max Length
Mandatory
Id
ID of product category
Edm.String
50
X
HierarchyId
ID of product hierarchy
Edm.String
50
ParentCategoryId
ID of parent category
Edm.String
50
Name
Product category name
Edm.String
40
Description
Description of product cate
Edm.String
512
Key
X
gory
Entity Type "Product" Entity type Product contains all attributes needed to create product categories. Product Meta Information Table 35: Property
Description
Edm Core Type
Max Length
Mandatory
Id
ID of product
Edm.String
50
X
ProductIdOrigin
Origin of source of ID
Edm.String
30
X
Name
Product Name
Edm.String
120
Description
Product Description
Edm.String
512
ImageUrl
URL of product image
Edm.String
1.333
NavigationURL
URL of navigation target
Edm.String
1.333
CategoryId
ID of product category
Edm.String
50
HierachyId
ID of product hierarchy
Edm.String
50
Key
X
Associations for Products and Product Categories You have the option to create several products with several additional product categories with one OData request.
Data Management Upload Interfaces 1702 56
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
The relations are as follows: Table 36: Associations
Principal Entity
Cardinality of Princi
Dependent Ent it y
pal Entity
Cardinal it y of Depe nd ent Entity
HeaderProduct
ImportHeader
One
Product
Many
ProductProductCate
Product
One
ProductCategory
Many
ImportHeader
One
ProductCategory
Many
gories HeaderProductCateg ory
9.2
Importing Interaction Contacts Using OData Service
To create or update interaction contacts the entity types ImportHeader, Contact and optional ContactFacet are needed.
Caution ●
● ●
You must specify a different ID Origin per source system or data source. In other words, if you import data from multiple sources, for example, from an ERP system, a CRM system, or a third-party system, you must ensure that the ID Origin for each source is different. Otherwise the data from one source will overwrite data imported from another source. You are not allowed to use the origin SAP_HYBRIS_MKT_IC. When you import updates for interaction contacts, you must import the full data, and not just updated attributes. If you only import updated attributes, all other existing attributes will be deleted (that is, overwritten with an empty value).
Example to create two contacts with several facets. The first person, Otto Normalverbraucher, is a contact for a company (account). The second person, Erika Mustermann, is a consumer that acts directly as an account. In the example below, you have to replace "UserName" : "", with a valid communication user.
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
Import of Data Using OData Service CUAN_IMPORT_SRV
Update Interaction Contacts The update of interaction contacts is performed using the same OData service as for the creation process. You must provide the properties SourceSystemId and ContactId so that the system can identify the interaction contacts to be updated. The system always updates a complete interaction contact; partial update of a contact is not supported. This means that it is not possible to update only two attributes of a contact, for example, as the empty attributes of the update would overwrite the existing attribute entries. If a facet is not provided anymore in the update case, the system sets this facet to obsolete in the target system. ●
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
61
Success Message After a successful creation or update of interaction contacts, the system provides you with a success message in the following appearance:
Error Handling Due to the fact that the attribute SourceSystemId is the only mandatory attribute, the system does not provide you with many error messages that result from the business logic. You can retrieve the log files that OData gateway stores using transaction /IWFND/ERROR_LOG. The log file provides you with a detailed description of the structural errors. In case of runtime errors, you can use transaction ST22 for deeper analyses. Known root causes: ●
The OData service is not active
●
The same identifier in the ImportHeader is used for more than one run
Data Management Upload Interfaces 1702 62
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
9.3
Importing Interactions Using OData Service
The following entity types are required to create interactions: ImportHeader, Interaction. The following entity types are optional: InteractionInterest, InteractionProduct, InteractionOffer, InteractionDigitalAsset, InteractionTag and/or InteractionAdditionalObjectReference.
Caution You must specify a different ID Origin per source system or data source. In other words, if you import data from multiple sources, for example, from an ERP system, a CRM system, or a third-party system, you must ensure that the ID Origin for each source is different. Otherwise the data from one source will overwrite data imported from another source.
Import of Data Using OData Service CUAN_IMPORT_SRV
Error Handling You can retrieve the log files that OData gateway stores using transaction /IWFND/ERROR_LOG. The log file provides you with a detailed description of the structural errors. In case of runtime errors, you can use transaction ST22 for deeper analyses. The business object HPA_IMPORT_HEADER also keeps track of all messages that have been raised. Known root causes ●
The OData service is not active
●
The same identifier in the ImportHeader is used for more than one run
●
See Import Using RFC [page 95]
9.4
Importing Companies Using OData Service
The approach for creating or updating companies is similar to that used for interaction contacts. The entity types ImportHeader and Company are needed. The entity types ContactMarketingPermission and ContactFacet are optional.
Caution You must specify a different ID Origin per source system or data source. In other words, if you import data from multiple sources, for example, from an ERP system, a CRM system, or a third-party system, you must ensure that the ID Origin for each source is different. Otherwise the data from one source will overwrite data imported from another source.
Update Companies The update of companies is performed using the same OData service as for the creation process. You must provide the properties SourceSystemId and ContactId so that the system can identify the companies to be updated. The system always updates a complete company; partial update of a company is not supported. This
Data Management Upload Interfaces 1702 66
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
means that it is not possible to update only two attributes of a company, for example, as the empty attributes of the update would overwrite the existing attribute entries. If a facet is not provided anymore in the update case, the system sets this facet to obsolete in the target system. ●
Success Message After a successful creation or update of companies, the system issues a success message.
Error Handling Due to the fact that the attribute SourceSystemId is the only mandatory attribute, the system does not provide you with many error messages that result from the business logic. You can retrieve the log files that OData gateway stores using transaction /IWFND/ERROR_LOG. The log file provides you with a detailed description of the structural errors. In case of runtime errors, you can use transaction ST22 for deeper analyses. Known root causes: ●
The OData service is not active
●
The same identifier in the ImportHeader is used for more than one run
9.5
Importing Products and Product Categories Using OData Service
To create products or product categories the entity types ImportHeader, Product and/or ProductCategory are needed. The OData service allows you to import product and product category data in one upload process as it ensures the creation of the category before the corresponding product is created and assigned.
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
69
}
Error Handling You can retrieve the log files that OData gateway stores using transaction /IWFND/ERROR_LOG. The log file provides you with a detailed description of the structural errors. In case of runtime errors, you can use transaction ST22 for deeper analyses. The business object HPA_IMPORT_HEADER also keeps track of all messages that have been raised. Known Root Causes ●
The OData service is not active
●
The same identifier in the ImportHeader is used for more than one run
●
See Import Using RFC [page 95]
9.6
Import of Marketing Locations Using an OData Service
A marketing location is defined as any physical or virtual location where a marketing activity can be conducted. It can be a brick and mortar store, a mall, a kiosk, a Web store, or even a beach area where marketers can distribute their coupons. Marketing locations can be maintained using the corresponding app in the system. Additionally, they can be imported from other systems using a public OData application programming interface (API). You can use the public OData service CUAN_MARKETING_LOCATION_IMP_SRV to upload (import) and read external marketing locations. Entity Data Model
The following tables list the details of the Marketing Location Import service entities. Table 37: OData Version: Root URL:
See the following chapters for implementation details and search behavior of the OData services.
Data Management Upload Interfaces 1702 70
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Table 38: Entity Data Model: Marketing Locations Name
Is Key
Edm Core
Max
Type
Length
Creatable
Updatable Sortable
Nullable
Filterable
Complex Type Name
LocationID TRUE
Edm.Strin g
50
TRUE
FALSE
TRUE
FALSE
TRUE
n.a.
Locatio nOrigin
TRUE
Edm.Strin g
30
TRUE
FALSE
TRUE
FALSE
TRUE
n.a.
Location Name
FALSE
Edm.Strin g
80
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Company FALSE Name
Edm.Strin g
80
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
MallName
FALSE
Edm.Strin g
40
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Introduc tion
FALSE
Edm.Strin g
--
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Additiona FALSE lInformation
Edm.Strin g
--
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Special
FALSE
Edm.Strin g
--
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Marketin gAreaId
FALSE
Edm.Strin g
40
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
TypeCode
FALSE
Edm.Strin g
20
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Country Code
FALSE
Edm.Strin g
3
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
City
FALSE
Edm.Strin g
40
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Region Code
FALSE
Edm.Strin g
3
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Postcode
FALSE
Edm.Strin g
10
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Street
FALSE
Edm.Strin g
60
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
House Num
FALSE
Edm.Strin g
10
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Building
FALSE
Edm.Strin g
20
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Floor
FALSE
Edm.Strin g
10
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
RoomNo
FALSE
Edm.Strin g
10
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
71
Name
Is Key
Edm Core
Max
Type
Length
Creatable
Updatable Sortable
Nullable
Filterable
Complex Type Name
TelnrLong
FALSE
Edm.Strin g
30
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
FaxnrLong FALSE
Edm.Strin g
30
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
SmtpAddr
FALSE
Edm.Strin g
241
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
WebUri
FALSE
Edm.Strin g
--
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
ImageUri
FALSE
Edm.Strin g
--
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Open Hours
FALSE
Edm.Strin g
--
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Categories FALSE
Edm.Strin g
--
TRUE
TRUE
FALSE
TRUE
FALSE
n.a.
Valid FromDate
FALSE
Edm.Date -Time
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
ValidTo Date
FALSE
Edm.Date -Time
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Obsolete
FALSE
Edm.Strin g
1
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
DigitalAc countID
FALSE
Edm.Strin g
40
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
DigitalAc FALSE countType
Edm.Strin g
10
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Language
FALSE
Edm.Strin g
1
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Latitude
FALSE
Edm.Deci mal
--
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Longitude
FALSE
Edm.Deci mal
--
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
SpatialRe ferenceId
FALSE
Edm.Strin g
-10
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
It is possible to create and change marketing locations using OData batch processing. The fields of the OData entities have the following meaning: ●
Marketing Location ○
LocationID: The unique location ID provided by the external system which serves, in the import
scenario, as part of the internal marketing location key. ○
LocationOrigin: A unique identifier of the origin of the external marketing location. This origin ID also
serves in the import scenario as part of the internal marketing location key.
Data Management Upload Interfaces 1702 72
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
○
LocationName: Name of the external marketing location (free text).
○
CompanyName: Name of the company associated with the external marketing location (free text).
○
MallName: Name of the mall if the external marketing location is in a shopping mall (free text).
○
Introduction: Introduction (free text).
○
AdditionalInformation: Additional information related to the marketing location (free text).
○
Special: Special Information related to the marketing location (free text).
○
MarketingAreaID: The ID of the marketing area, which has to be known by the system.
○
TypeCode: Marketing Location Type.
The marketing locations are defined in the configuration (CUANV_LOC_TYPE). The following default types are available: ○
MALL: Shopping Mall
○
ONLINE_STORE: Online Store
○
PHYSICAL_STORE: Physical Store
○
CountryCode: Country code.
○
City: City (free text).
○
RegionCode: Marketing location region code.
○
Postcode: Marketing location address postal code.
○
Street: Marketing location address street name.
○
Building: Marketing location address building.
○
Floor: Marketing location address floor number.
○
RoomNo: Marketing location address room number.
○
TelnrLong: Marketing location telephone number.
○
FaxnrLong: Marketing location fax number.
○
SmtpAddr: Marketing location e-mail address.
○
WebUri: Marketing location Web URI.
○
ImageUri: URI for the image to be used to represent the marketing location.
○
OpenHours: Marketing location open hours.
○
Categories: Marketing location business categories (free text).
○
ValidFromDate: The validity start date of the marketing location.
○
ValidToDate: The validity end date of the marketing location.
○
Obsolete: Do not use.
Note: If, for example, marketing locations are deleted in the original system which sends them via OData, obsolete can be set to true (X). ○
DigitalAccountID: Digital account ID associated to the marketing location.
○
DigitalAccountType: Digital account type of the digital account associated to the marketing location.
○
Language: Marketing location language code.
○
Latitude: Latitude value of address, for example: 55,64813464.
○
Longitude: Longitude value of address, for example: -3,24568414.
○
SpatialReferenceId: Geo location spatial ref ID of the marketing location.
Calling the OData Service Operation Create Request
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
73
The upload of marketing locations data starts as a post request using batch processing. The following example shows the coding for creating multiple marketing locations. URL (POST): /sap/opu/odata/sap /CUAN_MARKETING_LOCATION_IMP_SRV/$batch
Request Header Enter Content-Type as: multipart/mixed; boundary=batch Request Body Example --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Locations HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 LOC1309WECHAT_POILocation Name for LOC1309CompanyName for LOC1309MallName for LOC1309MEDIA_TYPEMALLCAMontrealQCH9X2R2DUKE111Building1309FOURTHLAGRANGE51499999995149999999[email protected]example.comexample.comMonday To Friday from 9am to 5pmBest prices on the marketGift Certificates availableSales every dayEtest222WEC_SUBACC10101020Ref0709032016-09-13T08:012016-09-13T08:01 --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Locations HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000
Data Management Upload Interfaces 1702 74
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
LOC1409WECHAT_POILocation Name for LOC1409CompanyName for LOC1409MallName for LOC1409MEDIA_TYPEMALLCAMontrealQCH9X2R2DUKE111Building1409FOURTHLAGRANGE51499999995149999999[email protected]example.comexample.comMonday To Friday from 9am to 5pmBest prices on the marketGift Certificates availableSales every dayEtest222WEC_SUBACC10101020Ref0709032016-09-14T08:012016-09-14T08:01 --changeset---batch--
Response Response Codes Example for response in case of successful creation: --C3B0988F46AC4AC9F15E17F0C060050A0 Content-Type: multipart/mixed; boundary=C3B0988F46AC4AC9F15E17F0C060050A1 Content-Length: 5449 --C3B0988F46AC4AC9F15E17F0C060050A1 Content-Type: application/http Content-Length: 2575 content-transfer-encoding: binary HTTP/1.1 201 Created Content-Type: application/atom+xml;type=entry Content-Length: 2301
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
75
location: https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_LOCATION_IMP_SRV/ Locations(LocationID='LOC1309',LocationOrigin='WECHAT_POI') dataserviceversion: 2.0 https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_LOCATION_IMP_SRV/ Locations(LocationID='LOC1309',LocationOrigin='WECHAT_POI')Locations(LocationID='LOC1309',LocationOrigin='WECHAT_POI') title> 2016-09-13T15:47:13ZLOC1309WECHAT_POILocation Name for LOC1309CompanyName for LOC1309MallName for LOC1309Best prices on the marketGift Certificates availableSales every dayMEDIA_TYPEMALLCAMontrealQCH9X2R2DUKE111Building1309FOURTHLAGRANGE51499999995149999999LOC1309@example.comexample.comexample.comMonday To Friday from 9am to 5pm2016-09-13T00:00:002016-09-13T00:00:00test222WEC_SUBACCE1020.00000000001010.0000000000Ref070903 --C3B0988F46AC4AC9F15E17F0C060050A1 Content-Type: application/http Content-Length: 2575 content-transfer-encoding: binary HTTP/1.1 201 Created Content-Type: application/atom+xml;type=entry Content-Length: 2301
Data Management Upload Interfaces 1702 76
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
location: https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_LOCATION_IMP_SRV/ Locations(LocationID='LOC1409',LocationOrigin='WECHAT_POI') dataserviceversion: 2.0 https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_LOCATION_IMP_SRV/ Locations(LocationID='LOC1409',LocationOrigin='WECHAT_POI')Locations(LocationID='LOC1409',LocationOrigin='WECHAT_POI') title> 2016-09-13T15:47:13ZLOC1409WECHAT_POILocation Name for LOC1409CompanyName for LOC1409MallName for LOC1409Best prices on the marketGift Certificates availableSales every dayMEDIA_TYPEMALLCAMontrealQCH9X2R2DUKE111Building1409FOURTHLAGRANGE51499999995149999999LOC1409@example.comexample.comexample.comMonday To Friday from 9am to 5pm2016-09-14T00:00:002016-09-14T00:00:00test222WEC_SUBACCE1020.00000000001010.0000000000Ref070903 --C3B0988F46AC4AC9F15E17F0C060050A1---C3B0988F46AC4AC9F15E17F0C060050A0--
Example for response in case of error during creation: --A8844D2A97F36CE1AB062A098A41423D0 Content-Type: application/http Content-Length: 1229
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
77
content-transfer-encoding: binary HTTP/1.1 400 Bad Request Content-Type: application/xml;charset=utf-8 Content-Length: 1109 dataserviceversion: 1.0 CX_ST_MATCH_ELEMENT/D79846DB5F914A4DA0C78A5F26310A11System expected end of element '{http://www.w3.org/2005/ Atom}entry'CEC-MKT-CEI/SAP/CUAN_MARKETING_LOCATION_IMP_SRV000157D7DA1FD92F1E58E10000000A445B6520160913155237.0977530Run transaction /IWFND/ERROR_LOG on SAP Gateway hub system (System Alias ) and search for entries with the timestamp above for more details SAP_Transaction> See SAP Note 1797736 for error analysis (https://service.sap.com/sap/ support/notes/1797736)See SAP Note 1869434 for details about working with $batch (https:// service.sap.com/sap/support/notes/1869434) --A8844D2A97F36CE1AB062A098A41423D0--
Update Request The following example shows the coding for updating Multiple Marketing Locations. URL (POST):/sap/opu/odata/sap /CUAN_MARKETING_LOCATION_IMP_SRV/$batch
Request Header Enter Request Header Content-Type as: multipart/mixed; boundary=batch Request Body Example --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary PUT Locations(LocationID='LOC1309',LocationOrigin='WECHAT_POI') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 LOC1309WECHAT_POILocation Name for LOC1309 UpdateCompanyName for LOC1309 Update
Data Management Upload Interfaces 1702 78
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
MallName for LOC1309 UpdateMEDIA_TYPEMALLCAMontrealQCH9X2R2DUKE111Building1309FOURTHLAGRANGE51499999995149999999LOC1309@example.comexample.comexample.comMonday To Friday from 9am to 5pmBest prices on the marketGift Certificates availableSales every dayEtest222WEC_SUBACC10101020Ref0709032016-09-13T08:012016-09-13T08:01 --changeset---batch--
Example for response in case of successful update: --BB2970BAF345D3B9A1732E1819A3049F0 Content-Type: multipart/mixed; boundary=BB2970BAF345D3B9A1732E1819A3049F1 Content-Length: 238 --BB2970BAF345D3B9A1732E1819A3049F1 Content-Type: application/http Content-Length: 71 content-transfer-encoding: binary HTTP/1.1 204 No Content Content-Length: 0 dataserviceversion: 2.0 --BB2970BAF345D3B9A1732E1819A3049F1---BB2970BAF345D3B9A1732E1819A3049F0—
Example for response in case of failed update: --115619F6A9253BD869F9FD9FB247481F0 Content-Type: application/http Content-Length: 1327 content-transfer-encoding: binary HTTP/1.1 400 Bad Request Content-Type: application/xml;charset=utf-8 Content-Length: 1207 dataserviceversion: 1.0 /IWBEP/CM_MGW_RT/022Location Key mismatched.
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
79
CEC-MKT-CEI/SAP/CUAN_MARKETING_LOCATION_IMP_SRV000157D73783D93C1E67E10000000A445B6520160913174530.8639530Run transaction /IWFND/ERROR_LOG on SAP Gateway hub system (System Alias ) and search for entries with the timestamp above for more details SAP_Transaction> See SAP Note 1797736 for error analysis (https://service.sap.com/sap/ support/notes/1797736)See SAP Note 1869434 for details about working with $batch (https:// service.sap.com/sap/support/notes/1869434)/IWBEP/CX_MGW_BUSI_EXCEPTIONLocation Key mismatchederror --115619F6A9253BD869F9FD9FB247481F0--
Delete Request The Delete of Marketing Locations data is started as a post request using batch processing. The Delete request will set the deleted Marketing Location property “Obsolete” to true (X). The following example shows the coding for deleting a Marketing Location. URL (POST): /sap/opu/odata/sap /CUAN_MARKETING_LOCATION_IMP_SRV/$batch
Request Header Enter Content-Type as: multipart/mixed; boundary=batch Request Body Example --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary DELETE Locations(LocationID='LOC1309',LocationOrigin='WECHAT_POI') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 --changeset---batch--
Response
Response Codes Example for response in case of successful deletion: --E39D08BA9681B0858BBE7CBCE606822C0
Data Management Upload Interfaces 1702 80
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Content-Type: multipart/mixed; boundary=E39D08BA9681B0858BBE7CBCE606822C1 Content-Length: 238 --E39D08BA9681B0858BBE7CBCE606822C1 Content-Type: application/http Content-Length: 71 content-transfer-encoding: binary HTTP/1.1 204 No Content Content-Length: 0 dataserviceversion: 2.0 --E39D08BA9681B0858BBE7CBCE606822C1---E39D08BA9681B0858BBE7CBCE606822C0— Example for response in case of error during deletion: --919A691B78E12B52C00D5C7BE02C885F0 Content-Type: application/http Content-Length: 1990 content-transfer-encoding: binary HTTP/1.1 500 Internal Server Error Content-Type: application/xml;charset=utf-8 Content-Length: 1860 dataserviceversion: 1.0 /IWBEP/CM_MGW_RT/058Missing response data in changeset deferred processing mode. Diagnosis Missing response data for some operation in a changeset running in defer mode System Response Procedure Fix the programming error in data provider Procedure for System AdministrationCEC-MKT-CEI/SAP/CUAN_MARKETING_LOCATION_IMP_SRV000157E0ADFA967D1FCFE10000000A445B6520160920204523.3643380Run transaction /IWFND/ERROR_LOG on SAP Gateway hub system (System Alias ) and search for entries with the timestamp above for more details SAP_Transaction> See SAP Note 1797736 for error analysis (https://service.sap.com/sap/ support/notes/1797736)See SAP Note 1869434 for details about working with $batch (https:// service.sap.com/sap/support/notes/1869434)/sap/opu/odata/iwbep/message_text;o=LOCAL_CEI/ T100_longtexts(MSGID='%2FIWBEP %2FCM_MGW_RT',MSGNO='058',MESSAGE_V1='',MESSAGE_V2='',MESSAGE_V3='',MESSAGE_V4='')/ $value/IWBEP/CX_MGW_TECH_EXCEPTIONMissing response data in changeset deferred processing mode/sap/opu/odata/iwbep/message_text;o=LOCAL_CEI/ T100_longtexts(MSGID='%2FIWBEP %2FCM_MGW_RT',MSGNO='058',MESSAGE_V1='',MESSAGE_V2='',MESSAGE_V3='',MESSAGE_V4='')/ $valueerror --919A691B78E12B52C00D5C7BE02C885F0--
Read Request
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
81
The Read of marketing locations data is started as a post request using batch processing. The following example shows the coding for reading a marketing location. URL (POST): /sap/opu/odata/sap /CUAN_MARKETING_LOCATION_IMP_SRV/$batch
Request Header Enter Content-Type as: multipart/mixed; boundary=batch Request Body Example --batch Content-Type: application/http Content-Transfer-Encoding: binary GET Locations(LocationID='LOC1309',LocationOrigin='WECHAT_POI') HTTP/1.1 --batch Content-Type: application/http Content-Transfer-Encoding: binary GET Locations(LocationID='LOC1409',LocationOrigin='WECHAT_POI') HTTP/1.1 --batch-Response Response Codes Example for response in case of successful read --C69ACC18C865F01E7D4C11B98951636C0 Content-Type: application/http Content-Length: 2428 content-transfer-encoding: binary HTTP/1.1 200 OK Content-Type: application/atom+xml;type=entry Content-Length: 2256 dataserviceversion: 2.0 sap-metadata-last-modified: Tue, 20 Sep 2016 17:09:27 GMT https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_LOCATION_IMP_SRV/ Locations(LocationID='LOC1309',LocationOrigin='WECHAT_POI')Locations(LocationID='LOC1309',LocationOrigin= type="text">Locations(LocationID='LOC1309',LocationOrigin='WECHAT_POI') 'WECHAT_POI') title> 2016-09-20T20:48:51ZLOC1309WECHAT_POILocation Name for LOC1309 Update againCompanyName for LOC1309 UpdateMallName for LOC1309 UpdateBest prices on the marketGift Certificates availableSales every dayMEDIA_TYPEMALLCAMontrealQCH9X2R2DUKE111Building1309
Data Management Upload Interfaces 1702 82
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
FOURTHLAGRANGE51499999995149999999LOC1309@example.comexample.comexample.comMonday To Friday from 9am to 5pm2016-09-13T00:00:002016-09-13T00:00:001020.00000000001010.0000000000Ref070903 --C69ACC18C865F01E7D4C11B98951636C0 Content-Type: application/http Content-Length: 2401 content-transfer-encoding: binary HTTP/1.1 200 OK Content-Type: application/atom+xml;type=entry Content-Length: 2229 dataserviceversion: 2.0 sap-metadata-last-modified: Tue, 20 Sep 2016 17:09:27 GMT https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_LOCATION_IMP_SRV/ Locations(LocationID='LOC1409',LocationOrigin='WECHAT_POI')Locations(LocationID='LOC1409',LocationOrigin=' type="text">Locations(LocationID='LOC1409',LocationOrigin='WECHAT_POI') WECHAT_POI') title> 2016-09-20T20:48:51ZLOC1409WECHAT_POILocation Name for LOC1409CompanyName for LOC1409MallName for LOC1409Best prices on the marketGift Certificates availableSales every dayMEDIA_TYPEMALLCAMontrealQCH9X2R2DUKE111Building1409FOURTHLAGRANGE51499999995149999999
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
83
LOC1409@example.comexample.comexample.comMonday To Friday from 9am to 5pm2016-09-14T00:00:002016-09-14T00:00:001020.00000000001010.0000000000Ref070903 --C69ACC18C865F01E7D4C11B98951636C0--
Example for response in case of error during read: --CD0C57931505332CF17EBF7692F71CDD0 Content-Type: application/http Content-Length: 1361 content-transfer-encoding: binary HTTP/1.1 404 Not Found Content-Type: application/xml;charset=utf-8 Content-Length: 1243 dataserviceversion: 1.0 es/metadata"> /IWBEP/CM_MGW_RT/020Resource not found for segment 'Location'.CEC-MKT-CEI/SAP/CUAN_MARKETING_LOCATION_IMP_SRV000157E09590967D1FD1E10000000A445B6520160920205037.7722580Run transaction /IWFND/ERROR_LOG on SAP Gateway hub system (System Alias ) and search for entries with the timestamp above for more details SAP_Transaction> See SAP Note 1797736 for error analysis (https://service.sap.com/sap/ support/notes/1797736)See SAP Note 1869434 for details about working with $batch (https:// service.sap.com/sap/support/notes/1869434)/IWBEP/CX_MGW_BUSI_EXCEPTIONResource not found for segment 'Location'error --CD0C57931505332CF17EBF7692F71CDD0 Content-Type: application/http Content-Length: 2401 content-transfer-encoding: binary HTTP/1.1 200 OK
Data Management Upload Interfaces 1702 84
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Content-Type: application/atom+xml;type=entry Content-Length: 2229 dataserviceversion: 2.0 sap-metadata-last-modified: Tue, 20 Sep 2016 17:09:27 GMT https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_LOCATION_IMP_SRV/ Locations(LocationID='LOC1409',LocationOrigin='WECHAT_POI')Locations(LocationID='LOC1409',LocationOrigin='WECHAT_POI') title> 2016-09-20T20:50:37ZLOC1409WECHAT_POILocation Name for LOC1409CompanyName for LOC1409MallName for LOC1409Best prices on the marketGift Certificates availableSales every dayMEDIA_TYPEMALLCAMontrealQCH9X2R2DUKE111Building1409FOURTHLAGRANGE51499999995149999999LOC1409@example.comexample.comexample.comMonday To Friday from 9am to 5pm2016-09-14T00:00:002016-09-14T00:00:001020.00000000001010.0000000000Ref070903 --CD0C57931505332CF17EBF7692F71CDD0--
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
85
9.7
Import of Marketing Beacons Using an OData Service
You can import marketing beacons into SAP Hybris Marketing using the OData Service CUAN_MARKETING_BEACON_IMPORT (OData service for Marketing Beacon Import). A marketing beacon is defined as a tiny, battery-powered, Bluetooth, low energy- based device that can be used locate a mobile app user in a precise physical location, so that a marker can conduct location- relevant marketing activities. Entity Data Model
The following tables list the details of the Marketing Beacons Import service entities. Table 39: OData Version:
See the following chapters for implementation details and search behavior of the OData services.
Table 40: Entity Data Model: Marketing Beacons Name
Is Key
Edm Core
Max
Type
Length
Creatable
Updatable Sortable
Nullable Filterable
Complex Type Name
Id
TRUE
Edm.Strin
50
TRUE
FALSE
TRUE
FALSE
TRUE
n.a.
--
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
20
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
40
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
g Descrip
FALSE
tion
Edm.Strin g
Type
FALSE
Edm.Strin g
UUID
FALSE
Edm.Strin g
Major
FALSE
Edm.Int32
--
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Minor
FALSE
Edm.Int32
--
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
Latitude
FALSE
Edm.Deci
--
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
mal
Data Management Upload Interfaces 1702 86
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Name
Is Key
Edm Core
Max
Type
Length
Creatable
Updatable Sortable
Nullable Filterable
Complex Type Name
Longitude
FALSE
Edm.Deci
--
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
30
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
50
TRUE
TRUE
TRUE
TRUE
TRUE
n.a.
mal Locatio
FALSE
Edm.Strin
nOrigin
g
LocationId FALSE
Edm.Strin g
It is possible to create, change, and read marketing beacons using OData batch processing. The fields of the OData entities have the following meaning: ●
Marketing Beacon ○
Id: The unique marketing beacon ID provided by the external system which serves, in the import
scenario, as the internal marketing beacon key. ○
Description: Description of the external marketing beacon (free text).
○
UUID: iBeacon Universally Unique Identifier. It contains 32 hexadecimal digits, split into 5 groups,
separated by dashes. ○
Major: Major and Minor values are numbers assigned to iBeacons to identify them with greater accuracy
than only using UUID. Major values are intended to identify and distinguish a group. For example, all beacons in on a certain floor or room could be assigned a unique Major value. ○
Minor: Major and Minor values are numbers assigned to iBeacons to identify them with greater accuracy
than only using UUID. Minor values are intended to identify and distinguish an individual. For example, distinguishing individual beacons within a group of beacons assigned a Major value. ○
Latitude: Latitude value of an address. For example: 55,64813464.
○
Longitude: Longitude value of an address. For example: -3,24568414.
○
SpatialReferenceId: Geo Beacon Spatial Ref ID of the marketing beacon.
○
LocationId: Marketing location ID.
○
LocationOrigin: Origin of the marketing location.
Calling the OData Service Operation Create Request
The upload of marketing beacons data is started as a post request using batch processing. The following example shows the coding for creating multiple marketing beacons. URL (POST): /sap/opu/odata/SAP/CUAN_MARKETING_BEACON_IMPORT_SRV/$batch
Request Header
Enter Content-Type as: multipart/mixed; boundary=batch
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
87
Request Body Example --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Beacons HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 BEACON1409This is BEACON1409IBEACONf7826da6-4fa2-4e98-8024-bc5b71e0893e78257108935564813464-324568414SIRD01WECHAT_POI286603472 --changeset Content-Type: application/http Content-Transfer-Encoding: binary POST Beacons HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 BEACON1509This is BEACON01509IBEACONf7826da6-4fa2-4e98-8024-bc5b71e0893e782657108935564813464-324568414SIRD01WECHAT_POI286603472 --changeset---batch--
Response Response Codes
Data Management Upload Interfaces 1702 88
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Example for response in case of successful creation: --F8C2A9724F37B985A59D553A3D2061B10 Content-Type: multipart/mixed; boundary=F8C2A9724F37B985A59D553A3D2061B11 Content-Length: 3218 --F8C2A9724F37B985A59D553A3D2061B11 Content-Type: application/http Content-Length: 1459 content-transfer-encoding: binary HTTP/1.1 201 Created Content-Type: application/atom+xml;type=entry Content-Length: 1221 location: https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_BEACON_IMPORT_SRV/Beacons('BEACON14092') dataserviceversion: 2.0 https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_BEACON_IMPORT_SRV/Beacons('BEACON14092')Beacons('BEACON14092')2016-09-14T14:08:45ZBEACON14092This is BEACON14092IBEACONf7826da6-4fa2-4e98-8001-bc5b71e0893e782657108935564813464.0000000000-324568414.0000000000SIRD01WECHAT_POI286603472 --F8C2A9724F37B985A59D553A3D2061B11 Content-Type: application/http Content-Length: 1460 content-transfer-encoding: binary HTTP/1.1 201 Created Content-Type: application/atom+xml;type=entry Content-Length: 1222 location: https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_BEACON_IMPORT_SRV/Beacons('BEACON15092') dataserviceversion: 2.0 https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_BEACON_IMPORT_SRV/Beacons('BEACON15092')Beacons('BEACON15092')2016-09-14T14:08:45ZBEACON15092
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
89
This is BEACON015092IBEACONf7826da6-4fa2-4e98-8003-bc5b71e0893e782657108935564813464.0000000000-324568414.0000000000SIRD01WECHAT_POI286603472 --F8C2A9724F37B985A59D553A3D2061B11---F8C2A9724F37B985A59D553A3D2061B10--
Example of response in case of error during creation: --8D802B497485B141A6EDF3DE68FA52900 Content-Type: application/http Content-Length: 1227 content-transfer-encoding: binary HTTP/1.1 400 Bad Request Content-Type: application/xml;charset=utf-8 Content-Length: 1107 dataserviceversion: 1.0 CX_SY_CONVERSION_NO_NUMBER/995DB739AB5CE919E10000000A11447BThe argument 'f7826da6' cannot be interpreted as a number message> CEC-MKT-CEI/SAP/CUAN_MARKETING_BEACON_IMPORT_SRV000157D75FBFD9771E8DE10000000A445B6520160914135857.6382290Run transaction /IWFND/ERROR_LOG on SAP Gateway hub system (System Alias ) and search for entries with the timestamp above for more details SAP_Transaction> See SAP Note 1797736 for error analysis (https://service.sap.com/sap/ support/notes/1797736)See SAP Note 1869434 for details about working with $batch (https:// service.sap.com/sap/support/notes/1869434) --8D802B497485B141A6EDF3DE68FA52900--
Update Request The following example shows the coding for updating multiple marketing beacons. URL (POST):/sap/opu/odata/SAP/CUAN_MARKETING_BEACON_IMPORT_SRV/$batch Request Header Enter Request Header Content-Type as: multipart/mixed; boundary=batch
Data Management Upload Interfaces 1702 90
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Request Body Example --batch Content-Type: multipart/mixed; boundary=changeset --changeset Content-Type: application/http Content-Transfer-Encoding: binary PUT Beacons('BEACON14092') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 BEACON14092This is BEACON14092 updatedIBEACONf7826da6-4fa2-4e98-8001-bc5b71e0893e7826015710893015564813464-324568414SIRD01WECHAT_POI286603472 --changeset Content-Type: application/http Content-Transfer-Encoding: binary PUT Beacons('BEACON15092') HTTP/1.1 Content-Type: application/atom+xml Content-Length: 10000 BEACON15092This is BEACON15092 updatedIBEACONf7826da6-4fa2-4e98-8001-bc5b71e0893e7826015710893015564813464-324568414SIRD01WECHAT_POI286603472 --changeset---batch--
Example for response in case of successful update: --E8643A5BE493A2D3C214DB5895D712730 Content-Type: multipart/mixed; boundary=E8643A5BE493A2D3C214DB5895D712731 Content-Length: 437 --E8643A5BE493A2D3C214DB5895D712731 Content-Type: application/http Content-Length: 71
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
Example for response in case of failed update: --0A9BEE26120EBEE0946EBFF19EFD878B0 Content-Type: application/http Content-Length: 1229 content-transfer-encoding: binary HTTP/1.1 400 Bad Request Content-Type: application/xml;charset=utf-8 Content-Length: 1109 dataserviceversion: 1.0 CX_SY_CONVERSION_NO_NUMBER/995DB739AB5CE919E10000000A11447BThe argument '571089301a' cannot be interpreted as a number message> CEC-MKT-CEI/SAP/CUAN_MARKETING_BEACON_IMPORT_SRV000157D7A124D93C1E85E10000000A445B6520160914141542.6286740Run transaction /IWFND/ERROR_LOG on SAP Gateway hub system (System Alias ) and search for entries with the timestamp above for more details SAP_Transaction> See SAP Note 1797736 for error analysis (https://service.sap.com/sap/ support/notes/1797736)See SAP Note 1869434 for details about working with $batch (https:// service.sap.com/sap/support/notes/1869434) --0A9BEE26120EBEE0946EBFF19EFD878B0--
Read Request The Read of marketing beacons data is started as a post request using batch processing. The following example shows the coding for reading a marketing beacon. URL (POST):/sap/opu/odata/SAP/CUAN_MARKETING_BEACON_IMPORT_SRV/$batch
Request Header Enter Content-Type as: multipart/mixed; boundary=batch
Data Management Upload Interfaces 1702 92
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
Request Body Example --batch Content-Type: application/http Content-Transfer-Encoding: binary GET Beacons(Id='BEACON070901') HTTP/1.1 --batch--
Response Response Codes Example for response in case of successful read: --ADA8B585B0BC057CDCE0A004D77C02080 Content-Type: application/http Content-Length: 1375 content-transfer-encoding: binary HTTP/1.1 200 OK Content-Type: application/atom+xml;type=entry Content-Length: 1203 dataserviceversion: 2.0 sap-metadata-last-modified: Wed, 07 Sep 2016 14:37:50 GMT https://ldciana.wdf.sap.corp:44300/sap/opu/odata/SAP/ CUAN_MARKETING_BEACON_IMPORT_SRV/Beacons('BEACON070901')Beacons('BEACON070901')2016-09-20T20:54:24ZBEACON070901This is BEACON070901 updateIBEACONUIUD070901U1011011011017090101.00000000007090101.0000000000SIRD01WECHAT_POI286603472 --ADA8B585B0BC057CDCE0A004D77C02080--
Example for response in case of error during read: --5AF6C91241CBEC15A03A7454A074870F0 Content-Type: application/http Content-Length: 1358 content-transfer-encoding: binary HTTP/1.1 404 Not Found Content-Type: application/xml;charset=utf-8
Data Management Upload Interfaces 1702 Import of Data Using OData Service CUAN_IMPORT_SRV
CUSTOMER
93
Content-Length: 1240 dataserviceversion: 1.0 /IWBEP/CM_MGW_RT/020Resource not found for segment 'Beacon'.CEC-MKT-CEI/SAP/CUAN_MARKETING_BEACON_IMPORT_SRV000157E0E025967D1FC0E10000000A445B6520160920205555.8115870Run transaction /IWFND/ERROR_LOG on SAP Gateway hub system (System Alias ) and search for entries with the timestamp above for more details SAP_Transaction> See SAP Note 1797736 for error analysis (https://service.sap.com/sap/ support/notes/1797736)See SAP Note 1869434 for details about working with $batch (https:// service.sap.com/sap/support/notes/1869434)/IWBEP/CX_MGW_BUSI_EXCEPTIONResource not found for segment 'Beacon'error --5AF6C91241CBEC15A03A7454A074870F0--
Data Management Upload Interfaces 1702 94
CUSTOMER
Import of Data Using OData Service CUAN_IMPORT_SRV
10 Import Using RFC
You can import interaction contacts, interactions, corporate accounts (companies), product categories, and products into your SAP Hybris Marketing system using a remote function call (RFC). The import parameter IV_ABORT_IF_ERROR for the RFC upload supports the following upload scenarios: ●
X = Store all or nothing (default)
●
Empty: Store the valid values
Authorization The function module checks if the authorization for accessing business objects (HPA_OBJECT) allows changes (ACTVT = 02). If this authorization is missing, the RFC aborts with an error message. For more information, see section Authorizations in the Security Guide for SAP Hybris Marketing under http:// help.sap.com/mkt
Security Information
.
Additional Fields Within the structures, on which the function modules are based, you find fields with unspecified names. If you want to use these fields since the available fields with specified names do not cover your requirements, you must ensure the required additional fields are added in
Data Management
Import Data in SAP Hybris Marketing .
10.1 Importing Interaction Contacts Using RFC Use To create and update interaction contacts using RFC, call the remote-enabled function module CUAN_CE_IC_POST_FLAT (development package CUAN_CONTACT_ENGAGEMENT, function group CUAN_CE_INTEGRATION). The function module imports the values in the table parameter IT_IC_IMP_EXT_FAFL. Each row contains the data of a separate interaction contact. The following attributes are mandatory: ●
ID_ORIGIN
This attribute specifies the domain in which the given ID is valid. The ID_ORIGIN value must exist in the system either as pre-delivered value or configured by the customer in maintenance view CUANV_CE_ORIGIN. ●
ID
Data Management Upload Interfaces 1702 Import Using RFC
CUSTOMER
95
This attribute specifies the ID under which you can identify the contact in your environment. ●
TIMESTAMP
This attribute refers to the validity date of the interaction contact data, or to the date when the contact has provided the data.
Note As each row of IT_IC_IMP_EXT_FAFL table parameter must refer to a separate contact, the same ID / ID_ORIGIN attribute value pair must not be used in different rows. The IT_IC_IMP_EXT_FAFL table parameter also contains a number of identifiers for facets under which a contact is known in the outside world. These attribute names start with ID_ or SMTP_ADDR or TELNR_LONG or FAXNR_LONG or TELNR_MOBILE. In the following attributes, for example, you can specify the interaction contact's e-mail address: SMTP_ADDR, SMTP_ADDR_2, and SMTP_ADDR_3. A contact can write e-mails to a company: SMTP_ADDR is the ID of this contact used in this special communication channel. The e-mail address is only one facet of this contact. Other facets can be used for other communication channels, such as ID_FB (Facebook), ID_GP (google +), ID_TW (twitter), and others. For importing additional facets, you can use the IT_IC_IMP_FACETS_ADDITIONAL parameter table. For each line in the parameter table, you use the REXCORD_IDX attribute to specify the interaction contact in IT_IC_IMP_EXT_FAFL, to which the additional facet shall be added. For the third interaction contact line, for example, enter the value 3 in the RECORD_IDX attribute. Use the attribute ID to specify the contact’s alternative but unique identifier. The ID_ORIGIN attribute is used in the same way as for IT_IC_IMP_EXT_FAFL. The following attributes can be used to assign or revoke the marketing permission in addition to the facet: ●
OUTBOUND_COMM_MEDIUM
●
OPT_IN
●
OPT_IN_TMSTMP
●
COMM_MEDIUM
●
COMM_DIRECTION
The system considers two or more contacts with the same mobile phone number or identifier via the attribute name starting with ID_ or additional facet as one contact and merges them into one contact. There is one exception for the merge. Contacts that have different IDs with the same mobile phone number are not merged when the following is true: ●
Both contacts have a facet with an ID_ORIGIN value starting with SAP_ (one per contact)
●
And the value of the corresponding ID is different for the two contacts
Example A contact has a SAP_CRM_BUPA facet with ID = 987654321. A second contact has a SAP_CRM_BUPA facet with ID = 123456789. NOTE: The system regards these two contacts as different contacts as they have different CRM business partner numbers, even if they share any other ID, which would normally cause the system to merge them.
Both contacts have a mobile phone number facet with ID = [email protected] The system then creates a third contact that serves only as container for the e-mail address and has no data apart from the e-mail facet.
Data Management Upload Interfaces 1702 96
CUSTOMER
Import Using RFC
Note For SAP Hybris Marketing 1.1 below SP06, the OBSOLETE attribute of the IT_IC_IMP_EXT_FAFL table parameter has no impact. You can use the IT_IC_IMP_MARKETING_ATTRIBUTE parameter table for importing marketing attributes for contacts. For each line in the parameter table, you use the REXCORD_IDX attribute to specify the interaction contact in IT_IC_IMP_EXT_FAFL, to which the marketing attribute shall be added. The following attributes can be used to assign marketing attributes: ●
CATEGORY_ID
●
CATEGORY_DESC
●
VALUE
●
LANGU
●
LANGU_DES
CATEGORY_ID is the external identifier for a marketing category. CATEGORY_DESC is the language-dependent
description of a marketing attribute category. You can use either CATEGORY_ID or CATEGORY_DESC to identify the category. If you use CATEGORY_DESC you can use LANGU (SAP Code value e.g. EN) or LANGU_DESC (description of language e.g. “English”) to set the language. The fallback language will be the logon language of the technical user. In the attribute VALUE you can provide a value belonging to a specific category. The exported values are stored in the ET_CONTACT_KEY parameter. Messages are stored in the ET_MESSAGE parameter. Both parameters are tables with the following content: ●
ET_CONTACT_KEY contains one row for each row entered in IT_IC_IMP_EXT_FAFL regardless of IT_IC_IMP_FACETS_ADDITIONAL. The order of entries is the same: The third row in ET_CONTACT_KEY
refers to the third interaction contact (row) in IT_IC_IMP_EXT_FAFL. The following attributes are used: ○
The ID_ORIGIN and ID attributes repeat the values from IT_IC_IMP_EXT_FAFL.
○
CONTACT_KEY returns the database key under which the corresponding interaction contact is or was
already persisted. ○
○
The DBOPERATION attribute indicates whether the interaction contact was updated (value = U) or newly created (value = I). The ANONYMIZED attribute indicates that the contact has requested their data to be protected (value = X’). Apart from the facets, the interaction contact data is cleared and cannot be updated.
Note The FACET_GROUP and MAIN_FACET attributes are not used. ●
FAILURE with value X indicates that an error occurred. The MSGID, MSGNO and MSGTY explain the error, or
contain just a message. ●
The messages for all contacts are returned in parameter ET_MESSAGE. This means that the error messages appear there as well, but additionally with text and different to ET_CONTACT_KEY the system can provide more than one message per contact.
Data Management Upload Interfaces 1702 Import Using RFC
CUSTOMER
97
Example IT_IC_IMP_EXT_FAFL contains two rows with interaction contacts with the same ID / ID_ORIGIN value pair. ET_CONTACT_KEY returns a corresponding row for each contact row with the following attribute values: ●
FAILURE = X
●
MSGID = CUAN_IC
●
MSGNO = 029
●
MSGTY = E (error)
ET_MESSAGE returns one row with the following attribute values: ●
TYPE = E
●
ID = CUAN_IC
●
NUMBER = 029
●
MESSAGE = Imported row 0000000002 contains facet of other row 0000000001
10.2 Importing Interactions Using RFC To create and update interactions using RFC, the CUAN_CE_INTEGRATION function group provides the following function modules: ●
CUAN_CE_INTERACTIONS_POST
●
CUAN_CE_INTERACTIONS_POST_FLAT
For error handling, use the IV_ABORT_IF_ERROR interface. The RFC returns the following data: ●
● ●
The ET_MESSAGES parameter returns an info message with the number of created interactions and error messages, if applicable. Identical error messages are merged, for example, if the interaction type is wrong or not available in Customizing in all ten thousand rows, the parameter only returns one error message. The ET_FAILED_INTERACTIONS parameter returns all rows affected by the error. The parameter IV_DEFAULT_IC_UPDATE_MODE defines the default behavior for all contacts to which the interactions belong. For details of the possible values and their effects, see the Update Mode table or the corresponding table entry in the appendix.
Function Module 'CUAN_CE_INTERACTIONS_POST' In function module CUAN_CE_INTERACTIONS_POST, the table type CUAN_T_CE_IA_EXT of the importing parameter IT_INTERACTIONS has a deep nested structure, which contains the interests and the products. The following code snippet shows the generated signatures and interfaces in the source code of the function module: *"*"Local Interface: *" IMPORTING *" VALUE(IT_INTERACTIONS) TYPE
CUAN_T_CE_IA_EXT
Data Management Upload Interfaces 1702 98
CUSTOMER
Import Using RFC
*" *" *" *" *" *" *" *"
VALUE(IV_ABORT_IF_ERROR) TYPE BOOLE_D DEFAULT 'X' VALUE(IV_DEFAULT_IC_UPDATE_MODE) TYPE CUAN_IC_UPDATE_MODE DEFAULT 'D' VALUE(IV_LOG_HANDLE) TYPE BALLOGHNDL OPTIONAL VALUE(IV_SAVE_LOG) TYPE BOOLE_D OPTIONAL EXPORTING VALUE(ET_FAILED_INTERACTIONS) TYPE CUAN_T_CE_IA_EXT VALUE(ET_MESSAGES) TYPE BAPIRETTAB
Structure 'CUAN_CE_INTERACTIONS_POST_FLAT' In function module CUAN_CE_INTERACTIONS_POST_FLAT, the table type CUAN_T_CE_IA_EXT_FLAT of the importing parameter IT_INTERACTIONS has a flat structure with STRING fields of type CHAR 30,000. This structure is used for SAP data services.
Caution If the table is too big, memory issues occur because the memory is allocated to the entire row length. The following code snippet shows the generated signatures and interfaces in the source code of the function module: *" *" *" *" *" *" *" *" *" *" *"
IMPORTING VALUE(IV_ABORT_IF_ERROR) TYPE BOOLE_D DEFAULT 'X' VALUE(IV_DEFAULT_IC_UPDATE_MODE) TYPE CUAN_IC_UPDATE_MODE DEFAULT 'D' VALUE(IV_LOG_HANDLE) TYPE BALLOGHNDL OPTIONAL VALUE(IV_SAVE_LOG) TYPE BOOLE_D OPTIONAL TABLES IT_INTERACTIONS STRUCTURE CUAN_S_CE_IA_EXT_FLAT ET_FAILED_INTERACTIONS STRUCTURE CUAN_S_CE_IA_EXT_FLAT OPTIONAL ET_MESSAGES STRUCTURE BAPIRET2 OPTIONAL
You can import more than one interest per interaction by copying the record and changing only the value in field "INTEREST_ITEM". The semantic key must be identical. The semantic key of an interaction consists of the fields ID_ORIGIN, ID, COMM_MEDIUM, IA_TYPE, TIMESTAMP, SOURCE_OBJECT_TYPE and SOURCE_OBJECT_ID. During the upload, the flat format will be normalized internally.
Error Handling Error handling is done in the IV_ABORT_IF_ERROR interface, see Import Using RFC [page 95].
10.3 Importing Companies Using RFC To create and update companies using RFC, call the remote-enabled function module CUAN_CE_COMPANY_POST_FLAT (development package CUAN_CONTACT_ENGAGEMENT, function group
Data Management Upload Interfaces 1702 Import Using RFC
CUSTOMER
99
CUAN_CE_INTEGRATION). The function module imports the values in the table parameter IT_COMP_IMP_EXT_FAFL. Each row contains the data of a separate company. The following attributes are
mandatory: ●
ID_ORIGIN
This attribute specifies the domain in which the given ID is valid. The ID_ORIGIN value must exist in the system either as pre-delivered value or configured by the customer in maintenance view CUANV_CE_ORIGIN. ●
ID
This attribute specifies the ID under which you can identify the company in your environment. ●
TIMESTAMP
This attribute refers to the validity date of the company data, or to the date when the company has provided the data.
Note As each row of IT_COMP_IMP_EXT_FAFL table parameter must refer to a separate company, the same ID and ID_ORIGIN attribute value pair must not be used in different rows. The IT_COMP_IMP_EXT_FAFL table parameter also contains a number of identifiers for facets under which a company is known in the outside world. These attribute names start with ID_ or SMTP_ADDR. In the attribute SMTP_ADDR for example, you can specify the company's e-mail address. A company can write e-mails to a company: SMTP_ADDR is the ID of this company used in this special communication channel. The e-mail address is only one facet of this company. Other facets can be used for other communication channels, such as ID_FB (Facebook), ID_GP (google +), ID_TW (twitter), and others. For importing additional facets, you can use the IT_COMP_IMP_FACETS_ADDITIONAL parameter table. For each line in the parameter table, you use the REXCORD_IDX attribute to specify the company in IT_COMP_IMP_EXT_FAFL, to which the additional facet is added. For the third company line, for example, enter the value 3 in the RECORD_IDX attribute. Use the attribute ID to specify the company’s alternative, but unique identifier. The ID_ORIGIN attribute is used in the same way as for IT_COMP_IMP_EXT_FAFL. The following attributes can be used to assign or revoke the marketing permission in addition to the facet: ●
OUTBOUND_COMM_MEDIUM
●
OPT_IN
●
OPT_IN_TMSTMP
●
COMM_MEDIUM
●
COMM_DIRECTION
As companies exist in the system as interaction contacts of type Account, the same rules regarding the merging of companies apply as for interaction contacts (refer to section Importing Interaction Contacts Using RFC [page 95]). The exported values are stored in the ET_COMPANY_KEY parameter and the messages are stored in the ET_MESSAGE parameter. Both parameters are tables with the same content mentioned in the section Importing Interaction Contacts Using RFC [page 95]. You can find more examples in this paragraph.
Data Management Upload Interfaces 1702 100
CUSTOMER
Import Using RFC
10.4 Importing Products and Product Categories Using RFC Products To create and update products using RFC, the CUAN_CE_INTEGRATION function group provides the following function modules: ●
CUAN_PRODUCTS_POST
●
CUAN_PRODUCTS_POST_FLAT
For error handling, use the IV_ABORT_IF_ERROR interface. The RFC returns the following data: ●
●
The ET_MESSAGES parameter returns an info message with the number of created products and error messages, if applicable. Identical error messages are merged, for example, if the product origin is wrong or not available in Customizing in all ten thousand rows, the parameter only returns one error message. The ET_FAILED_PRODUCTS parameter returns all rows affected by the error.
Function Module 'CUAN_PRODUCTS_POST'
In function module CUAN_PRODUCTS_POST, the table type CUAN_T_PRODUCT_EXT of the importing parameter IT_PRODUCTS has a deep nested structure, which contains the product description and the category assignment. The following code snippet shows the generated signatures and interfaces in the source code of the function module: *" IMPORTING *" VALUE(IT_PRODUCTS) TYPE CUAN_T_PRODUCT_EXT *" VALUE(IV_ABORT_IF_ERROR) TYPE BOOLE_D DEFAULT 'X' *" EXPORTING *" VALUE(ET_FAILED_PRODUCTS) TYPE CUAN_T_PRODUCT_EXT *" VALUE(ET_MESSAGES) TYPE BAPIRETTAB
Structure 'CUAN_PRODUCTS_POST_FLAT'
In function module CUAN_PRODUCTS_POST_FLAT, the table type CUAN_T_PRODUCT_EXT_FLAT of the importing parameter IT_PRODUCTS has a flat structure.
Caution If the table size is too is too big, memory issues occur because the memory is allocated to the entire row length. The following code snippet shows the generated signatures and interfaces in the source code of the function module: *" IMPORTING *" VALUE(IV_ABORT_IF_ERROR) TYPE BOOLE_D DEFAULT 'X' *" TABLES *" IT_PRODUCTS TYPE CUAN_T_PRODUCT_EXT_FLAT *" ET_FAILED_PRODUCTS TYPE CUAN_T_PRODUCT_EXT_FLAT OPTIONAL *" ET_MESSAGES TYPE BAPIRETTAB OPTIONAL
Error Handling
Error handling is done in the IV_ABORT_IF_ERROR interface, see Import Using RFC [page 95].
Data Management Upload Interfaces 1702 Import Using RFC
CUSTOMER
101
Product Categories To create and update product categories using RFC, the CUAN_CE_INTEGRATION function group provides the following function modules: ●
CUAN_PRODUCT_CATEG_POST
●
CUAN_PRODUCT_CATEG_POST_FLAT
For error handling, use the IV_ABORT_IF_ERROR interface. The RFC returns the following data: ●
●
The ET_MESSAGES parameter returns an info message with the number of created product categories and error messages, if applicable. The ET_FAILED_PROD_CAT parameter returns all rows affected by the error.
Function Module 'CUAN_PRODUCT_CATEG_POST'
In function module CUAN_PRODUCT_CATEG_POST, the table type CUAN_T_PROD_CAT_EXT of the importing parameter IT_PROD_CAT has a deep nested structure, which contains the category description. The following code snippet shows the generated signatures and interfaces in the source code of the function module: *" IMPORTING *" VALUE(IT_PROD_CAT) TYPE CUAN_T_PROD_CAT_EXT *" VALUE(IV_ABORT_IF_ERROR) TYPE BOOLE_D DEFAULT 'X' *" EXPORTING *" VALUE(ET_FAILED_PROD_CAT) TYPE CUAN_T_PROD_CAT_EXT *" VALUE(ET_MESSAGES) TYPE BAPIRETTAB
Structure 'CUAN_PRODUCT_CATEG_POST_FLAT'
In function module CUAN_PRODUCT_CATEG_POST_FLAT, the table type CUAN_T_PROD_CAT_EXT_FLAT of the importing parameter IT_PROD_CAT has a flat structure.
Caution If the table size is too is too big, memory issues occur because the memory is allocated to the entire row length. The following code snippet shows the generated signatures and interfaces in the source code of the function module: *" IMPORTING *" VALUE(IV_ABORT_IF_ERROR) TYPE BOOLE_D DEFAULT 'X' *" TABLES *" IT_PROD_CAT TYPE CUAN_T_PROD_CAT_EXT_FLAT *" ET_FAILED_PROD_CAT TYPE CUAN_T_PROD_CAT_EXT_FLAT OPTIONAL *" ET_MESSAGES TYPE BAPIRETTAB OPTIONAL
Error Handling
Error handling is done in the IV_ABORT_IF_ERROR interface, see Import Using RFC [page 95].
Data Management Upload Interfaces 1702 102
CUSTOMER
Import Using RFC
11
Import Using Web Service
You can import interactions, interaction contacts, companies, products, and product categories into yourSAP hybris Marketing system using Web services.
11.1
Importing Interaction Contacts Using Web Service
To create or update interaction contacts using web services, the CUANPOSTINTERACTIONCONTACTS service is available. The service provides the PostFlatInteractionContacts operation which is used for function module CUAN_CE_IC_POST_FLAT.
11.2
Importing Interactions Using Web Service
To create or update interactions using web services, the CUANPOSTINTERACTIONS service is available. This service provides the following two operations: ●
PostInteractions
This operation is used for function module CUAN_CE_INTERACTIONS_POST. ●
PostFlatInteractions
This operation is used for function module CUAN_CE_INTERACTIONS_POST_FLAT.
11.3
Importing Companies Using Web Service
To create or update companies using web services, the CUANPOSTICCOMPANIES service is available. The service provides the PostFlatIcCompanies operation which is used for function module CUAN_CE_COMPANY_POST_FLAT.
Data Management Upload Interfaces 1702 Import Using Web Service
CUSTOMER
103
11.4 Importing Products and Product Categories Using Web Service Products To create or update products using web services, the CUANPostProducts service is available. This service provides the following two operations: ●
PostProducts
This operation is used for function module CUAN_PRODUCTS_POST. ●
PostFlatProducts
This operation is used for function module CUAN_PRODUCTS_POST_FLAT.
Product Categories To create or update product categories using web services, the CUANPostProductCategories service is available. This service provides the following two operations: ●
PostProductCategory
This operation is used for function module CUAN_PRODUCT_CATEG_POST. ●
PostProductCategoryFlat
This operation is used for function module CUAN_PRODUCT_CATEG_POST_FLAT.
Data Management Upload Interfaces 1702 104
CUSTOMER
Import Using Web Service
12
Use Cases for Importing Data
You can create interactions that are used to import data to your system, including: ●
●
For interactions that can be used to create newsletter subscriptions, see Import Interactions for Newsletter Subscriptions [page 107] For interactions needed for creating or removing marketing permissions, see Import Interactions for Marketing Permissions [page 108]
12.1
Import Contacts with Marketing Permissions from an External Source System
This use case describes how to import interaction contacts in an initial upload from an external source system that already have marketing permissions set. The OData service CUAN_IMPORT_SRV can be used to create interaction contacts. For this you need a contact, with possibly multiple facets, and the corresponding marketing permissions, all of which are imported in one call. As a result, it is necessary to create a contact that contains the entities of OData service CUAN_IMPORT_SRV according to the following hierarchy: ●
Top Level: ImportHeader
●
Second Level: Contact
●
Third Level: ContactFacets and ContactMarketingPermissions
Example: Max Mustermann, a consumer from a web shop, with web shop account numer 12345, living in Bahnhofstr. 1,Munich 82674, with the mobile number 01511234567 and the email address [email protected] has given permission to be contacted by email but forbidden contact by phone. The following tables outline the properties that are necessary to represent this example: Table 41: Contact Property Name
Description
ContactId
Web shop account number: 12345
ContactIdOrigin
ID Origin must be WEB_SHOP_ACCOUNT
FirstName
Max
LastName
Mustermann
FullName
Max Mustermann
Data Management Upload Interfaces 1702 Use Cases for Importing Data
CUSTOMER
105
Property Name
Description
GenderDescription
Male
IsConsumer
TRUE
Timestamp
Format: number of milliseconds since midnight Jan 1, 1970. For example: "/ Date(1406014140922)/"
Origin of facet identifier (values defined in Customizing view CUANV_CE_ORIGIN ): EMAIL
Timestamp
Timestamp of facet. Format: number of milliseconds since midnight Jan 1, 1970. For example: "/ Date (1406014140922)/"
OptIn
Consent
OutboundCommunicationMedium
Communication to which the consent is given: EMAIL
CommunicationDirection
Whether the direction of permission is inbound (I) or out bound (O)
Data Management Upload Interfaces 1702 106
CUSTOMER
Use Cases for Importing Data
Table 45: CONTACT MARKETING PERMISSION - PHONE Property Name
Description
Id
Facet Identifier: 0151634789
IdOrigin
Origin of facet identifier (values defined in Customizing view CUANV_CE_ORIGIN ): PHONE
Timestamp
Timestamp of facet. Format: number of milliseconds since midnight Jan 1, 1970. For example: "/ Date(1406014140922)/"
OptIn
No Consent
OutboundCommunicationMedium
Communication to which the consent is given: PHONE
CommunicationDirection
Whether the direction of permission is inbound (I) or out bound (O)
12.2 Import Interactions for Newsletter Subscriptions This document describes the use case for creating interactions that are used to create newsletter subscriptions in SAP Hybris Marketing. The OData service CUAN_IMPORT_SRV can be used to create interactions. If you want to create a newsletter subscription, you must create an interaction using the type NEWSLETTER_SUBSCR. If you want to unsubscribe a contact from a newsletter, you must create an interaction using the interaction type NEWSLETTER_UNSUBSCR. The newsletter ID must be contained in the entity InteractionAdditionalObjectReference. As a result, it is necessary to create an interaction for both actions, subscribe and unsubscribe, which contains the entities of OData service CUAN_IMPORT_SRV according to the following hierarchy: ●
Top Level: ImportHeader
●
Second Level: Interaction
●
Third Level: InteractionAdditionalObjectReference (contains the newsletter ID)
If one interaction contact has subscribed to several newsletters simultaneously, it is possible to pass several entries for entity InteractionAdditionalObjectReference for a single interaction record. The following tables outline the properties that are necessary to subscribe or unsubscribe from a newsletter: Table 46: Property Name
Description
ContactId
Email address of the interaction contact
ContactIdOrigin
ID Origin must be EMAIL
Data Management Upload Interfaces 1702 Use Cases for Importing Data
CUSTOMER
107
Property Name
Description
InteractionType
NEWSLETTER_SUBSCR NEWSLETTER_UNSUBSCR
CommunicationMedium
Describes where the subscription occurred, for example, WEB or SYSTEM
Timestamp
Specify when the newsletter was subscribed to or unsubscri bed from
A newsletter is represented by a communication category, so you must use CUAN_COMMUNICATION_CATEGORY
ObjectID
ID of the communication category; length 10
12.3 Import Interactions for Marketing Permissions This document describes the use case for creating interactions needed for creating or removing marketing permissions in SAP Hybris Marketing. You can import marketing permissions into the system using interactions either in CSV files or using an OData service. If you use an OData service, you must create an interaction that contains the entities of OData service CUAN_IMPORT according to the following hierarchy: ●
Top Level: ImportHeader
●
Second Level: Interaction
The following table outlines the properties that are necessary to create or remove marketing permissions using an OData service or CSV file: Table 48: Property Name
Description
ContactId
ID for interaction contact facet, for example, email address for an email permission or phone number for a phone permission
Data Management Upload Interfaces 1702 108
CUSTOMER
Use Cases for Importing Data
Property Name
Description
ContactIdOrigin
ID origin for interaction contact facet, for example, EMAIL, PHONE, MOBILE , or FAX
InteractionType
MKT_PERM_OPTIN MKT_PERM_OPTOUT
CommunicationMedium
Describe where the permission was created, for example, WEB or SYSTEM
Timestamp
Specify when the permission was given
MarketingPermissionCommunicationMedium
Specify what kind of permission will be given, for example, EMAIL, PHONE , or SMS
MarketingPermissionDirection
This must be O for Outbound or I for an inbound permission. The default is O. Inbound permissions are only relevant for storing social media posts.
Data Management Upload Interfaces 1702 Use Cases for Importing Data
CUSTOMER
109
13
Appendix
Interactions In this section, you find an overview of all fields supported for the import of interaction data together with the corresponding description according to structure CUAN_S_CE_IA_EXT. Within the structure, you can find fields with unspecified names. If you want to use these fields because the available fields with specified names do not meet your requirements, you must ensure that the required additional fields are added in
Contacts and Profiles
Import Data
in SAP Hybris Marketing .
Table 49: Field (Technical Name) Used
OData Property
What It Contains
ContactIdOrigin
The origin of your contact IDs. The origin of an ID indi
in CSV ID_ORIGIN
cates the source of this ID. ContactId
ID
The external IDs of your interaction contact data such as Twitter ID, telephone number.
COMM_MEDIUM
CommunicationMedium
The communication medium, which is a path to use for communication such as email or text message. The com munication medium defines by what means, by which path, something happened.
IA_TYPE
InteractionType
Interaction types such as Click Through, Webinar, Survey Response etc. Interaction types define what happened. They have a direction, inbound or outbound (from contact to system or from system to contact). Additionally, they can have a reason, for example Mailbox is full for the inter action type Soft Bounce.
TIMESTAMP
Timestamp
The timestamp in long form (YYYYMMDDhhmmss.mmmuuun). The timestamp refers to the time the interaction took place, not to the time the record was created on the database. Examples for OData Format: ●
Number of milliseconds since midnight Jan 1, 1970. / Date(1406014140922)/
●
SOURCE_OBJECT_TYPE
SourceObjectType
YY-MM-DDThh:mm:ss
The object type of the source object, for example, an op portunity in SAP Hybris Cloud for Customer.
Data Management Upload Interfaces 1702 110
CUSTOMER
Appendix
Field (Technical Name) Used
OData Property
What It Contains
SourceObjectId
The object ID of the source object, for example, the GUID
in CSV SOURCE_OBJECT_ID
of the SAP Hybris Cloud for Customer opportunity or the original post ID of t he respective social media network (such as TW or FB). INTERESTS
Interests
The interaction interests of your contacts. In a deep struc ture, it is a table, in a flat structure it is identical with INTEREST_ITEM . ●
INTEREST_ITEM : interaction interest
●
INTEREST_QUANTIFIER : This field is a weighing fac
tor for the interest, which you can use if the standard mechanism of handling interests is not sufficient for your purposes. ●
INTEREST_VALUATION : This field contains the senti
ment or opinion of interaction contacts (positive or negative) regarding the interest, which you can use if the standard mechanism of handling valuation is not sufficient for your purposes. ●
CUAN_E_CE_IA_INT : Dummy field in extension in
cludeINCL_EEW_CUAN_CE_IA_INTEREST
Data Management Upload Interfaces 1702 Appendix
CUSTOMER
111
Field (Technical Name) Used
OData Property
What It Contains
Products
The interaction products of your contacts. In a deep
in CSV PRODUCTS
structure, it is a table. In a flat structure, it is not available.
●
OBJECT_TYPE
●
ItemType
●
OBJECT_ID
●
ItemId
●
PRODUCT_QUANTIFIER
●
Quantifier
●
PRODUCT_VALUATION
●
Valuation
●
This field contains the ID of the product.
●
PRODUCT_IMAGE_URL
●
ImageUrl
●
This field is a weighing factor for the product, which
●
PRODUCT_NAV_URL
●
NavigationURL
●
PRODUCT_NAME
●
Name
●
PRODUCT_DESC
●
Description
●
AMOUNT
●
Amount
●
QUANTITY
●
Quantity
nism of handling valuation is not sufficient for your
●
UNIT_OF_MEASURE
●
UnitOfMeasure
purposes.
●
PRECO_MODEL_TYPE
●
RecommendationModelTy
●
PRECO_SYSTEM
●
IA_PROD_STATUS
●
SourceSystemId
images, descriptions and pricing and shipping infor
●
IA_PROD_REASON
●
Not in ODdata
mation, for example.
●
Not in OData
peID
●
This field contains the product origin as defined in Customizing.
you can use if the standard mechanism of handling products is not sufficient for your purposes. ●
This field contains the sentiment or opinion of inter action contacts (positive or negative) regarding the product, which you can use if the standard mecha
●
This field contains the URL of the product image.
●
This field contains the product details URL containing
●
This field contains the name of the product.
●
This field contains the detailed descriptions of the product.
●
This field contains the product amount. The related currency is located on/in/at the interaction itself.
●
This field contains the quantity of the product.
●
This field contains the unit of measure of the product.
●
This field contains the Product Recommendation Model Type ID. This field should be filled if an interac tion is related to a Product Recommendation (Click Through/Conversion).
●
This field contains the Product Recommendation Scenario ID. This field should be filled if an interaction is related to a Product Recommendation (Click Through/Conversion).
●
This field contains the status of a line item of an inter action. For information about importing business documents using the OData service CUAN_BUSI NESS_DOCUMENT_IMP_SRV, see the Importing Business Documents guide at http:// help.sap.com/mkt
SAP Hybris Marketing Cloud
SAP Hybris Marketing Cloud Product Page Integration ●
.
This field contains the reason for changes in the line item
Data Management Upload Interfaces 1702 112
CUSTOMER
Appendix
Field (Technical Name) Used
OData Property
What It Contains
in CSV ●
CUAN_E_CE_IA_PRD : Dummy field in extension in
clude INCL_EEW_CUAN_CE_IA_PRODUCT TAGS ●
TAG_TYPE
●
TAG:
Tags : ●
TagType
●
Tag
In a deep structure, it is a table. In a flat structure, it is not available. ●
This field contains the tag type as defined in Custom izing.
●
DIGITAL_ASSETS
DigitalAssets :
This field contains the tag itself.
The digital assets. In a deep structure, it is a table. In a flat structure, it is not available.
●
DIGITAL_ASSET_SYSTEM .
●
SourceSystemId
●
DIGITAL_ASSET_ID .
●
Id
●
This field contains the system of the digital asset.
●
DIGITAL_ASSET_NAME
●
Name
●
This field contains the ID of the digital asset.
●
DIGITAL_ASSET_MIME_T
●
MIMEType
●
This field contains the name of the digital asset
YPE
●
URL
●
This field contains the MIME type of the digital asset
●
DIGITAL_ASSET_URL:
●
CampaignId
●
INITIATIVE_ID
(for example text, image, audio or video). ●
This field contains the URL where the digital asset is located
In a deep structure, it is a table. In a flat structure, it is not
s:
available.
●
ObjectType
●
ObjectId
●
This field contains the type of t he object referenced, for example CUAN_OFFER .
●
This field contains the ID of the object referenced.
Data Management Upload Interfaces 1702 Appendix
CUSTOMER
113
Field (Technical Name) Used
OData Property
What It Contains
Offers :
The offers. In a deep structure, it is a table. In a flat struc
in CSV OFFERS ●
OFFER_ORIGIN
●
Origin
●
OFFER_ID
●
Id
●
OFFER_CONTENT_ITEM_I
●
ContentItemId
D
●
RecommendationScenari
●
RECO_SCENARIO
ture, it is not available. ●
This field contains the Indicator for the offer origin used when importing offers from another system, e.g. SAP_PMR for offers from SAP Promotion Man agement for Retail.
oId ●
This field contains the identifier of the offer.
●
This field contains the ID of the content item of the offer. Together with Language and CommunicationMedium of the Interaction Header,
the offer content can be identified. ●
This field contains recommendation scenario ID. If you use Offer Recommendation Intelligence (ORI), this field indicates the recommendation scenario used to recommend this offer.
●
CUAN_E_CE_IA_OFR : Dummy field in extension in
clude INCL_EEW_CUAN_CE_IA_OFFER CAMPAIGN_ID
-
The ID of a campaign in SAP CRM.
INITIATIVE_ID
-
The ID of the campaign in SAP Hybris Marketing (formerly initiative).
INI_VERSION
-
The ID of the campaign version, which is derived from or belongs to the campaign ID. A campaign version is cre ated for campaigns that are based on dynamic target groups once they are executed.
MARKETING_ORCHESTRATION_
-
The ID of the campaign content (in SP05, the descriptor of this field was Marketing Engagement ID; renamed to
ID
Campaign Content ID in SP06). LOC_ORIGIN
-
The origin of your Marketing Location IDs. The origin of an ID indicates the source of this ID.
LOC_ID
-
The ID of the Marketing Location where the interaction took place such as a Mall or Shop
DIGACC_ID
-
Digital Account ID, mit der Kontakt aufgenommen wurde
DIGACC_TYPE
-
The Digital Account Type is the Type of Digital Account ID
QUANTIFIER
-
This field is a weighing factor, which you can use if the standard mechanism of counting interactions is not suffi cient for your purposes.
Data Management Upload Interfaces 1702 114
CUSTOMER
Appendix
Field (Technical Name) Used
OData Property
What It Contains
Valuation
The sentiment or opinion of interaction contacts (positive
in CSV VALUATION
or negative). IA_STATUS
Not in OData
Status of an interaction (typically replicated from a busi ness document). For information about replicating SAP Hybris Cloud for Customer business documents to SAP Hybris Marketing interactions using the OData service CUAN_BUSI NESS_DOCUMENT_IMP_SRV see the Importing Busi ness Documents guide at http://help.sap.com/mkt SAP Hybris Marketing Cloud Cloud Product Page
IA_REASON
Reason
Integration
SAP Hybris Marketing
.
The potential reasons for an interaction, for example, the soft bounce of an email due to a recipient's full mailbox.
IA_LANGUAGE
Not in OData
Language of the text of the interaction. This can differ from the user’s language. It can be used for example in newsletters.
IS_ANONYMOUS
IsAnonymous
Information as to whether an interaction is anonymous or not. Anonymous interactions do not refer to a contact person.
AMOUNT
Amount
An amount of money which is related to an interaction. The amount is concatenated to the field CURRENCY .
CURRENCY
Currency
The currency which is related to an interaction. The cur rency is concatenated to the field AMOUNT .
MKT_PERM_DIRECTION
MarketingPermissionDirect
Direction of the marketing permission information of an
ion
interaction contact per communication medium (I = in bound or O = outbound)
MKT_PERM_COMM_MEDIUM
MarketingPermissionCommun
The marketing permission information of an interaction
icationMedium
contact per communication medium. For example, an in teraction contact has given consent to be contacted via email.
LATITUDE
Latitude
The latitude of a geographical location where the interac tion took place.
LONGITUDE
Longitude
The longitude of a geographical location where the inter action took place.
UNIT
-
This field is obsolete. Do not use.
Data Management Upload Interfaces 1702 Appendix
CUSTOMER
115
Field (Technical Name) Used
OData Property
What It Contains
SpatialReferenceId
Spatial Reference Identifier is a unique value used to un
in CSV SRID
ambiguously identify projected, unprojected, and local spatial coordinate system definitions. Defines, where lati tude and longitude belong. DEVICE_FT
Device
Name of the device used in this interaction
SOURCE_SYSTEM_TYPE
SourceSystemType
The type of system which stores t he raw data or detailed information such as a clickstream monitoring tool.
SOURCE_SYSTEM_ID
SourceSystemId
The ID of the system which stores the raw data or detailed information such as a clickstream monitoring ID.
SOURCE_OBJECT_ADD_ID
SourceObjectAdditionalId
The external object ID of the source object, for example, the ID of the SAP Hybris Cloud for Customer opportunity.
SOURCE_OBJECT_STATUS_COD
-
Information about the status of the source object such as Completed for a SAP Hybris Cloud for Customer opportu
E
nity. SOURCE_DATA_URL
SourceDataUrl
The navigation URL of the source object, for example, the URL of a Twitter post.
SOURCE_TIMESTAMP
Not in OData of the Import Serv
Timestamp of the source object in the source system
ice but inOData of Business
For example, the timestamp when a contract was created in the source system. This is different from the timestamp of the last change date of the contract.
Documents
For information about importing business documents us ing the OData service CUAN_BUSINESS_DOCU MENT_IMP_SRV, see the Importing Business Docu ments guide at http://help.sap.com/mkt Marketing Cloud Page LAUNCH_URL
StartingPointUrl
Integration
SAP Hybris
SAP Hybris Marketing Cloud Product
.
The starting point URL of an interaction such as a link in an email of a campaign for interaction type CLICK_THROUGH .
LAUNCH_TEXT
StartingPointText
The text of the starting point URL of an interaction such as the link text "More Information" in an email of a cam paign for interaction type CLICK_THROUGH .
LAUNCH_LINK_KEY
-
The key of the starting point URL of an interaction such as the key of the link in an email of a campaign for interaction type CLICK_THROUGH that an interaction contact has clicked.
Data Management Upload Interfaces 1702 116
CUSTOMER
Appendix
Field (Technical Name) Used
OData Property
What It Contains
-
Values defining how an interaction contact is to be up
in CSV IC_UPDATE_MODE
dated. The allowed values are N (= no update), F (= full update), or D (= delta update). CONTENT_TITLE
ContentTitle
The title of the respective content, for example, email subject or the social media post (abbreviated). If the con tent title is empty, the field is filled with the content data (see field CONTENT_DATA ).
CONTENT_DATA
ContentData
The content of an email or a social media post.
NAME_TEXT
-
The full name of the interaction contact (first name and last name).
NAME_FIRST
-
The first name of the interaction contact.
NAME_LAST
-
The last name of the interaction contact.
TITLE
-
The key for the title of the interaction contact such as 0001.
TITLE_FT
-
A free text for the title of the interaction contact.
COUNTRY
-
The country key of the interaction contact such as DE, US.
COUNTRY_FT
-
A free text for the country the interaction contact.
REGION
-
The region key of the interaction contact such as 08, CA.
REGION_FT
-
A free text for the region of the interaction contact.
CITY1
-
The name of the city of the interaction contact.
POSTCODE1
-
The postal code of the city of the interaction contact.
STREET
-
The street of the interaction contact.
HOUSE_NUM1
-
The house number of the interaction contact.
LANGUAGE
-
The language key.
LANGUAGE_FT
-
A free text for the language.
SEX
-
The key for the sex of the interaction contact such as 1, 2, ….
SEX_FT
-
A free text for the sex of the interaction contact.
Data Management Upload Interfaces 1702 Appendix
CUSTOMER
117
Field (Technical Name) Used
OData Property
What It Contains
-
The key for the marital status of your interaction contacts
in CSV MARITAL_STATUS
such as 01, 02. MARITAL_STATUS_FT
-
A free text for the marital status of the interaction con tact.
CONSUMER_ACCOUNT_ID
-
The account ID of a consumer in B2C.
KUNNR
-
The account ID of a company in B2B.
COMPANY_NAME
-
A free text for the company of your interaction contacts.
BRSCH
-
This field contains the industry key of your interaction contacts.
BRSCH_FT
-
A free text for the industry of your interaction contacts.
ABTNR
-
The department key of your interaction contacts.
ABTNR_FT
-
A free text for the department of your interaction con tacts.
PAFKT
-
The function key of your interaction contacts.
PAFKT_FT
-
A free text for the function of your interaction contacts.
SMTP_ADDR
-
This field contains the SMTP address of the email ad dress.
TELNR_LONG
-
This field contains the long version of a telephone number including dialing code, number, and extension. Format: +country code region code + phone number e.g. +49151123456
TELNR_MOBILE
-
The long version of a mobile phone number including dial ing code, number, and extension. Format: +country code region code + phone number e.g. +49151123456
FAXNR_LONG
-
The long version of a fax number including dialing code, number, and extension. Format: +country code region code + fax number e.g. +49151123456
DATE_OF_BIRTH
-
The date of birth of an interaction contact.
Data Management Upload Interfaces 1702 118
CUSTOMER
Appendix
Field (Technical Name) Used
OData Property
What It Contains
-
Information as to whether an interaction contact is a con
in CSV IS_CONTACT
tact or not. IS_CONSUMER
-
Information as to whether an interaction contact is a con sumer or not.
OBSOLETE
-
Information as to whether an object is obsolete or not.
EMAIL_OPTIN
-
Information as to whether an interaction contact allows to be contacted by email or not, or if this information is not available.
PHONE_OPTIN
-
Information as to whether an interaction contact allows to be contacted by landline phone or not, or if this informa tion is not available.
MOBILE_OPTIN
-
Information as to whether an interaction contact allows to be contacted by mobile phone or not, or if this information is not available.
-
FAX_OPTIN
Information as to whether an interaction contact allows to be contacted by fax or not, or if this information is not available.
POSTAL_OPTIN
-
Information as to whether an interaction contact allows to be contacted by mail or not, or if this information is not available.
WEB_URI
-
A Web address that is related to a company, for example.
IMAGE_URI
-
A Web address that is related to a contact image.
CUAN_E_CE_IA_RT
-
Dummy field in extension include INCL_EEW_CUAN_CE_IA_ROOT
CUAN_E_CE_IA_IC_RT
-
Dummy field in extension include INCL_EEW_CUAN_CE_IA_IC
Products In the following, you find an overview of all fields supported for the import of product data together with a corresponding description according to structure CUAN_S_PRODUCT_EXT. Within the structure, you find fields with unspecified names. If you want to use these fields since the available fields with specified names do not cover your requirements, you must ensure the required additional fields are added in
Contacts and Profiles
Import Data
in SAP Hybris Marketing the .
Data Management Upload Interfaces 1702 Appendix
CUSTOMER
119
Table 50: Field (Technical
OData Property
What It Contains
IdOrigin
This field contains the origin of a product indicating the
Name) Used in CSV PRODUCT_ORIGIN
source of this product such as SAP Hybris Commerce Product .
The allowed values are defined in Customizing for SAP Hybris Marketing under Person PRODUCT_ID
Data Management
Interaction Contact
.
This field contains the external product ID from the source of
Id
this product. IMAGE_URL
ImageUrl
This field contains a URL to an image of the product.
NAV_URL
NavigationURL
This field contains a URL to t he details of the product.
DESCRIPTIONS
Descriptions :
This is a component with a table containing the following fields:
●
LANGU
●
Language
●
NAME
●
Name
●
DESCRIPTION
●
Description
●
This field contains the language key of the product de scription.
●
This field contains the name of the product such as MR-750.
●
This field contains the actual description of the product such as The MR-750 computer provides 32 GB RAM .
CATEGORIES :
Categories :
This is a component with a table containing the following
●
HierarchyId
●
HIERARCHY_ID
●
CategoryId
●
CATEGORY_ID
fields: ●
This field contains the external ID of the hierarchy data to which the product is assigned.
●
This field contains the external ID of the category data t o which the product is assigned.
Product Categories In the following, you find an overview of all fields supported for the import of product data together with a corresponding description according to structure CUAN_S_PROD_CAT_EXT. Within the structure, you find fields with unspecified names. If you want to use these fields since the available fields with specified names do not cover your requirements, you must ensure the required additional fields are added in
Contacts and Profiles
Import Data
in SAP Hybris Marketing the .
Data Management Upload Interfaces 1702 120
CUSTOMER
Appendix
Table 51: Field (Technical
OData Property
What It Contains
HierarchyId
This field contains the external ID of the hierarchy data to
Name) Used in CSV HIERARCHY_ID
which the product category is assigned. CATEGORY_ID
Id
This field contains the ID of t he product category.
PARENT_CATEGORY
ParentCategoryId
This field contains the ID of a category that serves as the pa rent for another category.
_ID CATEGORY_DESCRI PTIONS
Category Descriptions : ●
Language
●
LANGU
●
Name
●
NAME
●
Description
●
DESCRIPTION
This is a component with a table containing the following fields: ●
This field contains the language key of the product cate gory description.
●
This field contains the name of the product category such as Stationery.
●
This field contains the actual description of the product category such as Stationery includes pens, erasers, ink cartridges .
Interests The following table contains an overview of all fields supported for the import of interest data, together with the corresponding description according to structure CUAN_S_INTEREST_EXT. Table 52: Interests Field (Technical Name) Used in CSV
OData Property
What It Contains
INTEREST_ITEM
Id
This field contains the interest ID, such as SAP_HYBRIS_MARKETING .
DESCRIPTION : ●
SPRAS
●
INTEREST_ITEM_DESC
●
Language
This is a component with a table contain
●
Description
ing the following fields: ●
This field contains the language key of the product description.
●
This field contains the actual de scription of the interest, such as BIG DATA.
Data Management Upload Interfaces 1702 Appendix
CUSTOMER
121
Field (Technical Name) Used in CSV
OData Property
What It Contains
CATEGORIES :
AssignedProductCategories
This is a component with a table contain
●
HIERARCHY_ID
●
HierarchyId
●
CATEGORY_IDC
●
Id
ing the following fields: ●
This field contains the hierarchy ID of the product category.
●
This field contains the product cate gory ID.
TAGS : ●
TAG_ORIGIN
●
TAG_TYPE
●
TAG
Not in OData
This is a component with a table contain ing the following fields: ●
●
●
This field contains the origin of the tag (currently set to SAP_HDB_TA) This field contains the tag type as defined in Customizing. Tag types are used in the text analysis of en tity types. This field contains the tag itself.
Data Management Upload Interfaces 1702 122
CUSTOMER
Appendix
Important Disclaimers and Legal Information
Coding Samples Any software coding and/or code lines / strings ("Code") included in this doc umentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence.
Accessibility The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of willful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.
Gender-Neutral Language As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.
Internet Hyperlinks The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency (see: http://help.sap.com/disclaimer).
Data Management Upload Interfaces 1702 Important Disclaimers and Legal Information