Part 1: Forms

Part 2: CSV Import

Part 3: OData Service

Part 4: Extraction from CRM with ABAP program

 

Preliminary note: This text mainly refers to release 1702 of Hybris Marketing.

Section 3 was added to present a new feature of cloud release 1705.

Introduction

 

As mentioned in the previous part of this blog, OData services are the method of choice in productive use to upload subscriptions and permissions into the system.

The OData service used for this purpose is called CUAN_IMPORT_SRV. Its URL is:
https://<customer_host>/sap/opu/odata/sap/cuan_import_srv/
Note that you need a communication user for the superordinate Interaction Contact Integration scenario. In case you don’t already have such a user, you can create one in the SAP Fiori app ‘Create Communication User’. Click the tile ‘Maintain Communication Users’ in the ‘Communication Management’ area.



 

If you are working with an on-premise system, the SAP Gateway Client is a helpful means to perform OData requests. Just enter transaction code /IWFND/GW_CLIENT. If this does not work, it’s most likely due to the slash at the beginning of the code – just add “/n” or “/o”. This should solve the problem. In case you are not yet familiar with the tool, check this blog for a hands-on introduction.



 

To avoid syntactic errors – which often occur when performing PUT, POST and PATCH requests – you should use the button ‘Use as Request’. This provides you with the correct syntactic structure, and you only need to adjust the relevant fields.

 



Later in this post, you will find JSON examples which you can copy and paste to simplify your work.

Another important transaction code is SEGW. It leads you to the SAP Gateway Service Builder.

 



 

The Service Builder shows you the data model CUAN_IMPORT of the OData service CUAN_IMPORT_SRV and its entities with properties and navigation properties at a glance – which is more comfortable than reading an XML or JSON file. Another possibility to see all available properties is, of course, to perform a GET request on
https://<customer_host>/sap/opu/odata/sap/cuan_import_srv/$metadata
 

How does the import of permissions and subscriptions work? At present, it is not possible to upload permissions or subscriptions directly, without any other entity, through the ImportHeader. That’s why you need either the entity ‘Contact’ or the entity ‘Interaction’ to get these kinds of information into the Hybris Marketing system.

You can use the CUAN_IMPORT_SRV service to import:

• • interaction contacts with marketing permissions (see section 1).

• • interactions for marketing permissions (section 2.1).

• • interactions for newsletter subscriptions (section 2.2).

• • permissions and subscriptions directly without contacts or interactions (new as of 1705; section 3)

 

The base attributes for marketing permissions and subscriptions are:



 

In the following diagram, you can see which entities are affected in the different kinds of upload, displayed as a directed tree:

 



Figure 0: Relevant entities

 

The arrows between the entities represent associations. For example, the connection between ImportHeader and Contact is represented by the 1:n association named “HeaderContact”, starting from ImportHeader.

Any upload of permissions or subscriptions is performed through ‘ImportHeaders’ as entity set name.

The Import Header entity requires the following entries:

The timestamp in the header is not to be confused with the timestamp of the permission or subscription. SourceSystemType and SourceSystemId can be chosen arbitrarily as long as you can restore the assignments. The information maintained here is for your own use, for example, in evaluations, to distinguish between different source systems.

When uploading data via OData, pay attention that the recommended load for contacts is 5,000; more than 10,000 will result in error. For interactions, the maximum load is 100,000. Without products and 1 interest, for example, that number decreases to 50,000. If there are 5 products and 5 interests, you should not upload more than 5,000 interactions.

Another good reason to upload smaller packages, is that if an error occurs (in the worst case, toward the end of an upload), nothing is uploaded (“all or nothing”). More on this topic can be found in chapter 7 of ‘Best Practices and Troubleshooting’, in the Data Management Upload Interfaces 1702 document.

 

Section 1: Importing Marketing Permission and Subscription Data with Contacts

 

The situation of this way of importing can be visualized by the left part of the tree above:

Level 1: ImportHeader

Level 2: Contact

Level 3: ContactFacets and ContactMarketingPermission

 



Figure 1: Entities relevant for importing contacts with marketing permissions

 

You create a contact using the POST request here:
https://<customer_host>/sap/opu/odata/sap/cuan_import_srv/ImportHeaders
With this kind of upload, you can avoid shareable conflicts that result from, for example, different contacts using the same email address. This is possible, because the properties of ‘Contact’ allow you to submit more information about the interaction contact in addition to Id and IdOrigin, like FullName, FirstName, and LastName. The system employs all the supplied information to generate an identification key. Use the ContactFacet entity to add additional fields not on hand in the properties of ‘Contact’, or to maintain data that is afterwards not utilized to build the BestRecord. (Facet data will always be ignored in the Best Record.)

Several properties of the Contact entity can be used to prompt marketing permissions. Amongst others, there are fields like PhoneNumber and PhoneOptin, PostalCode and PostalOptin. In the ContactFacet, you need to specify the IdOrigin explicitly, e. g. “EMAIL”, to communicate the OptIn information to the system (“Y” for yes, and “N” for no).

To add the extension fields as properties to the Contact entity (which you can see in the Metadata file with GET https://<customer_host>/sap/opu/odata/sap/cuan_import_srv/$metadata), use the Import Data or Custom Fields and Logic apps.

If you just want to put general marketing permissions into the system, the Contact and ContactFacet entities will do. Though submission of newsletter subscriptions is only possible via the ContactMarketingPermission entity. And, as you can see in the tables below, only with this deep insert entity can you deliver detailed and individual facts and figures about a single permission or subscription.

Note that the system logic, at present, does not imply an update functionality. Thus, if a contact already exists, it will be overwritten with the delivered entries – which leads to undesirable results, particularly in case of empty fields. So be sure to import the full data when you import updates for interaction contacts. Importing only updated attributes will result in deletion of the other attributes, which will be replaced by empty values.

For further information and a full list of all properties of the entities Contact, ContactFacet, and ContactMarketingPermission with descriptions, check the document ‘Data Management Upload Interfaces 1702’. Here you can also see which properties are mandatory.

Let’s have a look at the following example:
The contact “Thomas Schmidt” is created, with his second email address as a facet. Mr. Schmidt has given the explicit permission to be contacted by phone (number +496227123123456789), and by his second email address “thomas.schmidt123@example.com”. This is represented in the ContactMarketingPermission container.

We perform the POST request on
https://<customer_host>/sap/opu/odata/sap/cuan_import_srv/ImportHeaders
and submit the JSON file below. Just replace “UserName”: “<YOUR COMMUNICATION USER>” with a valid communication user. You can also leave the field empty, but a wrong entry results in error.

We enter the following values in the JSON file:



 



 



 

Following is the corresponding JSON coding with:

• • The navigation property Contacts from ImportHeader to Contact

• • The navigation property Facets from Contact to ContactFacet

• • The navigation property MarketingPermissions from Contact to ContactMarketingPermission

{ “Id”:””, “Timestamp”:”2017-04-03T10:01:00″, “UserName”:”<YOUR COMMUNICATION USER>”, “SourceSystemType”:”EXT”, “SourceSystemId”:”ANY”, “Contacts”:[ { “Id”:”+496227123123456789″, “IdOrigin”:”PHONE”, “Timestamp”:”2017-01-01T12:00:00″, “City”:”Neustadt”, “CountryDescription”:”DE”, “EMailAddress”:”thomas.schmidt@example.com”, “FirstName”:”Thomas”, “GenderDescription”:”Male”, “HouseNumber”:”200″, “IsConsumer”:true, “LanguageDescription”:”German”, “LastName”:”Schmidt”, “MobilePhoneNumber”:”+491″, “PhoneNumber”:”+492″, “PostalCode”:”67000″, “Street”:”Rieslingstraße”, “TitleDescription”:”Mister”, “Facets”:[ { “Id”:”thomas.schmidt123@example.com”, “IdOrigin”:”EMAIL” } ], “MarketingPermissions”:[ { “Id”:”+496227123123456789″, “IdOrigin”:”PHONE”, “Timestamp”:”2017-03-01T12:00:00″, “OptIn”:”Y”, “OutboundCommunicationMedium”:”PHONE”, “CommunicationDirection”:”O” }, { “Id”:”thomas.schmidt123@example.com”, “IdOrigin”:”EMAIL”, “Timestamp”:”2017-02-01T12:00:00″, “OptIn”:”Y”, “OutboundCommunicationMedium”:”EMAIL”, “CommunicationDirection”:”O” } ] } ] }
“OData Service Output: HTTP status 201 Created” indicates a successful upload. If the call fails, the HTTP status is “400 Bad Request.”

In case of success, Mr. Schmidt’s profile can be found in your system:





As you can see, the respective phone number and email address are switched over to green:



The settings here represent the situation e.g. in Germany where the default setting is ‘no permission’ (explicit opt-in). You can only contact recipients who have given their prior consent. In case of implicit opt-in (USA for example) you won’t see any change, because all permissions have been granted from the very first. You can change the default setting in the customizing.

 

 

Section 2: Importing Permission and Subscription Data with Interactions

 

Interactions contain information about how, when, and where communication has taken place between the contact and the company, such as phone calls and emails. But they can also indicate when contacts write about the company and its products in social networks.

The mandatory fields are:



 

Examples for further fields:



 

A complete list of all fields, including descriptions, is provided in section 9.4 in the document ‘Data Management Upload Interfaces’.

This section also gives the allowed values for the entities along with descriptions. For example, you can enter Reasons for interactions with tags like ‘HANGUP’ for the interaction type TELEPHONE_OUTBOUND.

When uploading interactions, bear in mind that a contact must be uniquely identifiable by their ID Origin and ID (for example, EMAIL and email address), because, again, the problem of shareable IDs occurs (for example, two people with the same phone number). But this time, it is not possible to add further information to uniquely identify the contact. You should use the contact upload if an ID is shareable.

In the interaction upload, we have two different situations depending on whether permissions or subscriptions are concerned.

 

Section 2.1: Importing Permission Data with Interactions

 

Permission upload only needs the entities ImportHeader and Interaction:

 



Figure 2: Entities relevant for importing interactions for marketing permissions

 

The name of the navigation property from ImportHeader to Interaction is Interactions.

The following example contains an interaction for the contact above (Thomas Schmidt), a general opt-out for his email address thomas.schmidt123@example.com given through WEB (CommunicationMedium). We presume, that only Mr. Schmidt himself uses this email address.

To get this into our system, we execute a POST HTTP request on https://<customer_host>/sap/opu/odata/sap/cuan_import_srv/ImportHeaders with the following JSON coding:
{ “Id”:””, “Timestamp”:”2017-04-03T10:02:00″, “UserName”:”<YOUR COMMUNICATION USER>”, “SourceSystemType”:”EXT”, “SourceSystemId”:”ANY”, “Interactions”:[ { “Key”:””, “CommunicationMedium”:”WEB”, “ContactId”:”thomas.schmidt123@example.com”, “ContactIdOrigin”:”EMAIL”, “InteractionType”:”MKT_PERM_OPTOUT”, “MarketingPermissionCommunicationMedium”:”EMAIL”, “Timestamp”:”2017-04-01T12:00:00″ } ] }
As mentioned above, enter your communication user name, or just an empty pair of quotation marks.

This is what you should see on the screen:



Everything else remains the same.

The timestamp of this interaction must of course represent a later point in time than the given email permission in the first request. Otherwise the request has no effect but a database entry.

 

Section 2.2: Importing Subscription Data with Interactions

 

For subscription data upload, we need the entity InteractionAdditionalObjectReference. This entity contains two mandatory fields:



 

The corresponding navigation property starting from Interaction is named AdditionalObjectReferences.

 



Figure 3: Entities relevant for importing interactions for newsletter subscriptions

To supply a newsletter subscription, we need to create an interaction of the type NEWSLETTER_SUBSCR (see the table above containing the mandatory fields for Interaction). Since a newsletter is represented by a communication category, CUAN_COMMUNICATION_CATEGORY is the correct value for the ObjectType in the additional object reference.

The properties and values of the Interaction entity for newsletter subscriptions are as follows:



Suppose, Mr. Schmidt has subscribed to a newsletter with ID 2, and we want to get this information into the system.

We again perform a POST request on https://<customer_host>/sap/opu/odata/sap/cuan_import_srv/ImportHeaders with the following JSON coding (and with either no user name or your communication user):
{ “Id”:””, “Timestamp”:”2017-04-03T10:03:00″, “UserName”:”<YOUR COMMUNICATION USER>”, “SourceSystemType”:”EXT”, “SourceSystemId”:”ANY”, “Interactions”:[ { “Key”:””, “CommunicationMedium”:”WEB”, “ContactId”:”thomas.schmidt123@example.com”, “ContactIdOrigin”:”EMAIL”, “InteractionType”:”NEWSLETTER_SUBSCR”, “MarketingPermissionCommunicationMedium”:”EMAIL”, “Timestamp”:”2017-04-02T12:00:00″, “MarketingPermissionDirection”:”O”, “AdditionalObjectReferences”:[ { “ObjectType”:”CUAN_COMMUNICATION_CATEGORY”, “ObjectId”:”2″ } ] } ] }
Now the subscription to newsletter 2 (“Camera Newsletter”) is in the system. This appears as follows:



There is still a red symbol on the right side, because there is no general permission for the email address. The subscription is an exception of the general opt-out.

This is how our two interactions are displayed on the screen:



 

Section 3: Direct import of permissions and subscriptions

As of release 1705 of Hybris Marketing (cloud only), you can upload permissions and subscriptions directly through the header.

The corresponding navigation property starting from ImportHeader is called ContactMarketingPermissions.

 



Figure 4: Entities relevant for importing permissions or subscriptions directly.

 

Since no contact is created through the request here, the contact must have already been created. The system will find the corresponding contact by the specified properties Id and IdOrigin. As you already know by now, it is required that the contact be unique. Use the import of Interaction Contacts as outlined above to import marketing permissions or subscriptions for shareable IDs (Section 1).

The update of an existing permission or subscription record will only be effective if the timestamp of the corresponding record (with the ID referring to the respective contact) is more recent than the timestamp of the existing record.

We enter the following values in the JSON file for entity ContactMarketingPermission:



Note that property CommunicationCategoryId is mandatory in case of a newsletter subscription.

We again perform a POST request on https://<customer_host>/sap/opu/odata/sap/cuan_import_srv/ImportHeaders with the following JSON coding (and with either no user name or your communication user):
{ “Id” : “”, “Timestamp” : “2017-06-11T18:52:13”, “SourceSystemType” : “EXT”, “SourceSystemId” : “ANY”, “ContactMarketingPermissions” : [ { “Id” : “thomas.schmidt@example.com”, “IdOrigin” : “EMAIL”, “Timestamp” : “2017-06-11T17:52:10”, “CommunicationCategoryId” : “101”, “OptIn” : “Y”, “OutboundCommunicationMedium” : “EMAIL”, “CommunicationMedium” : “EMAIL”, “CommunicationDirection” : “O” }, { “Id” : “thomas.schmidt123@example.com”, “IdOrigin” : “EMAIL”, “Timestamp” : “2017-06-11T17:52:12”, “OptIn” : “Y”, “OutboundCommunicationMedium” : “EMAIL”, “CommunicationMedium” : “EMAIL”, “CommunicationDirection” : “O” } ] }
The first part of the ContactMarketingPermissions container effects a subscription to the newsletter with ID 102 (in the system used here this is “Newsletter 01”), the second part operates an opt-in for the named email address.

 

This is the result on the screen:

There is a new subscription,…



… and the specified email address is opted in again:



 

For further reading: This is the corresponding part of the 1705 documentation.

Check the other parts of this blog to get to know more about ways of getting permissions and subscriptions into the Hybris Marketing system.

Part 1: Forms

Part 2: CSV Import

Part 3: OData Service

Part 4: Extraction from CRM with ABAP program