Skip to Content

Table of contents

  • Introduction
  • Use case
  • Component 1: Message API
    • Overview
    • Example
  • Component 2: Servlet
  • Component 3: View in Browser link
  • Bonus: Reusable View in Browser link
  • New with SAP Hybris Marketing Cloud 1802 / SAP Hybris Marketing 1709 SP01
  • Conclusion
  • References

Introduction

What can you do, as a marketing expert, to ensure that the campaign mail you just sent out to your customers is perceived and displayed in the way you intended? Due to the huge variety of email clients and devices, the same email HTML can be displayed differently on different devices. A good way to ensure compatibility to current HTML standards and engines is by using a web browser such as Microsoft Internet Explorer or Google Chrome to render the email content.

How does it work? Using the custom solution presented in the following blog from Tim Nusch; “View in Browser” functionality for SAP Hybris Marketing as a starting point, we have further improved this by implementing an API and reusable blocks in our 1708 release. This can be used to build a browser-based view that can be managed by customers in the Cloud and On-Premise versions of SAP Hybris Marketing. This blog explains its 3 components, which guarantee the best possible HTML fidelity for your email campaign messages across all devices.

Update February 2018: Added new chapter about 1802 enhancements.

Use case

The general use case for your end user is quite simple:

  • Receive a marketing email containing a View in Browser link
  • Click on the View in Browser link
  • The received email is being opened in the devices default browser

For you as a marketing expert the use case is even more simple:

  • Include a View in Browser link in your marketing email

But how does that special link have to look and which functionality does the website where the link points to have to deliver? Let’s dive a bit deeper.

Component 1: Message API

Overview

With 1708 we delivered GetPersonalizedMessage, a new service endpoint to the OData Service API_MKT_CAMPAIGN_MESSAGE_SRV. Its documentation can be found on the SAP API Hub (section Service Operations) and the SAP Help Portal:

Result {
d (API_MKT_CAMPAIGN_MESSAGE_SRV.PersonalizedMessage, optional)
}
API_MKT_CAMPAIGN_MESSAGE_SRV.PersonalizedMessage {
MessageContentText (string, optional): Represents the Entire Content of a Campaign Message
Represents the entire content of a campaign message.
This can be HTML content as well as other types of text-based campaign message content.
}

The service endpoint has two input parameters you have to provide

  • CampaignOutbound: unique ID per sent mail and contact
  • LinkTrackingIsDisabled: describes if links in the email content should be tracked

Generally speaking you provide the link to the original message and contact and get the corresponding HTML email in return. This is what we use as View in Browser content.

Example

Let’s look at a sample request and response to the new service endpoint. We provide an existing outbound ID (D67F8C6C54C34759D4AD80EE726B9FD815947BCB), surround it with encoded sinqle quotes (%27), disable the link tracking (true) and we receive the following API call:

https://{HostOfYourSystem}:{PortOfYourSystem}/sap/opu/odata/sap/API_MKT_CAMPAIGN_MESSAGE_SRV/GetPersonalizedMessage?CampaignOutbound=%27D67F8C6C54C34759D4AD80EE726B9FD815947BCB%27&LinkTrackingIsDisabled=true

There are 2 possible results now: the outbound ID exists in the system and you get the expected response with the HTML email content via the property d:MessageContentText:

<d:GetPersonalizedMessage xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:type="API_MKT_CAMPAIGN_MESSAGE_SRV.PersonalizedMessage">
<d:MessageContentText>
<!DOCTYPE html><html><head></head><body><!--[if mso]><table border="0" cellpadding="0" cellspacing="0" align="left" style="mso-table-lspace:0pt; mso-table-rspace:0pt; border-collapse: collapse; width: 100%"><tr><td style="width: 100%;"><![endif]--><div style="float: left; width: 100%" class="sapMktBlock"><p>This is the first text block!</p> <p><a rel="noopener noreferrer" href="https://www.sap.com?sap-outbound-id=6C0B84B755231EE7A3AB990407D6768A&utm_source=SAPHybris&utm_medium=email&utm_campaign=SEND_TEST&utm_term=Marketing%20Email___Untrackable%20link&utm_content=DE" target="_blank" title="Untrackable link">Untrackable link</a></p> <p><a rel="noopener noreferrer" href="https://www.sap.com?sap-outbound-id=6C0B84B755231EE7A3AB990407D6768A&utm_source=SAPHybris&utm_medium=email&utm_campaign=SEND_TEST&utm_term=Marketing%20Email___Trackable%20link&utm_content=DE" target="_blank" title="Trackable link">Trackable link</a></p> <p></p> <p><a rel="noopener noreferrer" href="https://www.viewinbrowser.com" target="_blank" title="View In Browser">View In Browser</a></p></div><!--[if mso]></td></tr></table><![endif]--></body></html>
</d:MessageContentText>
</d:GetPersonalizedMessage>

If we provide a non existing outbound ID (e.g. 1234), we get an OData error:

<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<code>CUAN_ME/812</code>
<message xml:lang="en">Page not found.</message>
<innererror>
<application>
<component_id>CEC-MKT-BF</component_id>
<service_namespace>/SAP/</service_namespace>
<service_id>API_MKT_CAMPAIGN_MESSAGE_SRV</service_id>
<service_version>0001</service_version>
</application>
<transactionid>51089CA78E2503B0E005998463AD0F06</transactionid>
<timestamp/>
<Error_Resolution>
<SAP_Transaction/>
<SAP_Note>
See SAP Note 1797736 for error analysis (https://service.sap.com/sap/support/notes/1797736)
</SAP_Note>
</Error_Resolution>
<errordetails>
<errordetail>
<code>CUAN_ME/812</code>
<message>Page not found.</message>
<propertyref/>
<severity>error</severity>
<target/>
</errordetail>
<errordetail>
<code>CUAN_ME/810</code>
<message>No execution run found for Outbound ID 1234.</message>
<propertyref/>
<severity>error</severity>
<target/>
</errordetail>
</errordetails>
</innererror>
</error>

Component 2: Servlet

Now you have got basically all you need: a URL which can be displayed in a web browser and contains the HTML email content. What’s missing? Consider the following drawbacks if you would include the URL above as a View in Browser link in your marketing email:

  • The end user will have to provide credentials for the backend system where the OData Service is called. Just clicking the link will lead to a logon popup which is not what we want.
  • The outbound ID is dynamic, meaning each contact has his own unique outbound ID per received email. We can’t just insert the same static URL in the email.
  • The OData response is provided in the XML format, meaning that you will only see the cryptic XML structure and not the original HTML content rendered in your browser.
  • The end user will see an error message in XML if something goes wrong down the line. Wouldn’t it be better to redirect the user to your default landing page as a fallback in case of an error?

How can you solve these issues and offer better usability for the end user? By implementing a web servlet responsible for the tasks mentioned above. There are several technical possibilities to implement such a servlet, e.g.:

The servlet implementation has to deliver the features mentioned above to ensure a seamless end user experience for the View in Browser functionality and be deployed and reachable under a public URL.

We at SAP developed a small implementation example for such a servlet as a Java Servlet (in short: one single .WAR file). You as a customer can deploy that for yourself on your own webserver but also on SAP Cloud Platform (SCP). The SCP deployment is described below:

  1. Activate the communication arrangement for the scenario SAP_COM_0094 with a communication user with basic authentication (for more details on that, see the documentation in the SAP Help Portal)
  2. Take the URL of your cloud application upto “.com” (example: mysystem12345.s4hana.ondemand.com)
  3. Append “-api” after the system ID (example: mysystem12345-api.s4hana.ondemand.com)
  4. Logon to your SCP account, navigate to Java Applications and click Deploy Application:
  5. A popup appears where you upload the provided .WAR file and provide JVM Arguments taken from the communication user (see step 1) and the api URL (see step 3): -DhostSystem=mysystem12345-api.s4hana.ondemand.com -DuserName=XXXXXXX -Dpassword=XXXXXXXXXXXX. Enter an application name and click Deploy:
  6. Click Start on the next screen:
  7. Wait for some seconds until the application switches its state from Starting to Started:
  8. Click on the link with the application name you provided (see step 6) and copy the application URL:

As a result now you have got the application URL to your servlet which we will use in the next step, inserting the View In Browser link into the marketing email. Communicate the URL to the user responsible for the email creation, e.g. via email.

Component 3: View in Browser link

Now you have got an accessible URL to the web servlet responsible for mapping the parameters to the OData Service, changing the HTTP response type for browser rendering HTML content, providing credentials and redirecting to the fallback URL if an error happens. Let’s suppose your servlet URL looks as follows (it’s the same from the step before):

https://www.myservlet.mydomain.com

Before you insert that link as a View in Browser link, you could provide the desired fallback URL base64 encoded as URL parameter or the servlet could have that URL implemented per default. If you decide to append the fallback URL to the link above, it could look like this:

Servlet URL: https://www.myfallback.com
Base64 encoded: aHR0cHM6Ly93d3cubXlmYWxsYmFjay5jb20=
Appended to servlet URL: https://www.myservlet.mydomain.com?FallbackURL=aHR0cHM6Ly93d3cubXlmYWxsYmFjay5jb20

Remember that the parameter name FallbackURL is completely arbitrary, only the called servlet has to parse and decode it to redirect there in case of an OData Service error. Now insert a regular link in your email in Content Studio, assign the URL and check Append Outbound ID:

If Append Outbound ID is checked it is provided in sent emails via the parameter sap-outbound-id in the View in Browser link. Its value has to be passed to the OData Service as parameter CampaignOutbound by the servlet implemented the step before. Uncheck Trackable for Campaign Analytics because you don’t want to track the View in Browser link itself.

Bonus: Reusable View in Browser link

Do you want to use that View in Browser link you just created in multiple emails, e.g. always in the email header? Define the block as reusable and you can reuse it in your marketing emails without further effort:

Just drag and drop the newly created block in your message:

More documentation to Reusable Blocks is available in the SAP Help Portal.

New with SAP Hybris Marketing Cloud 1802 / SAP Hybris Marketing 1709 SP01

As of 1802 the customer-managed scenario described above is no longer needed in SAP Hybris Marketing Cloud. A new SAP-managed scenario is now available. However, if you have the communication arrangement SAP_COM_0094 with your custom servlet up and running, you can, of course, keep using it.

So, what is new about the SAP-managed scenario? We have provided a way to include completely prebuilt “View In Browser” links on the user interface pointing to the SAP-managed servlet. You no longer need to manually compose the links as described above, but simply insert them by clicking on the button as highlighted below

If you have never implemented the customer-managed solution described above, these links always point to the newly implemented SAP-managed servlet without any configuration in the cloud system:

Using your own servlet with its own accessible URL (still mandatory for On-Premise) works as follows:

  • On-Premise: Enter the URL to your deployed servlet in Customizing for SAP Hybris Marketing (transaction CEI_IMG) under Campaigns -> Content Studio -> Set Up View Email in Browser Link. If the value is empty, you will not see the “Insert View in Browser Link” button.
  • Cloud: Enter the URL to your deployed servlet in the communication arrangement SAP_COM_0094, parameter “URL”. If the value is empty, you will see the “Insert View in Browser Link” button, but the links point to the SAP-managed servlet.

Conclusion

You should now be able to understand the technical details regarding the API-based View in Browser functionality in Content Studio for 1708 and the enhancements for 1802 (Cloud) and 1709 SP01 (On-Premise).

Do you like this blog entry? Share on your favorite social media :-). Questions, feedback or additions? Leave it in the comments!

References

To report this post you need to login first.

1 Comment

You must be Logged on to comment or reply to a post.

Leave a Reply