SAPUI5 and C4C. My (un)expected journey. Part 1.

SAPUI5 and C4C. My (un)expected journey. Preparation.

Disclaimer: everything described in this or following blog posts is purely my own findings. Statements made here are my own opinions. Anything mentioned from the technical perspective is subject to change as soon as SAP decides to change things.

The journey continued. As the reader may recall, my initial task was to extend C4C UIs (both HTML client and Fiori client). The extension should be something done with SAPUI5/OpenUI5. In other words, it should embed custom (preferably, SAPUI5) control into C4C. And it should talk to C4C as well.

This brought me to this (un)expected journey. Having all tools in hands from my preparation blog, I started to explore further. The first thing which came to my mind was obviously HTML mashup. There are some very valuable blogs across SAP Community platform available on the topic. Here I’d like to focus on technical aspects as well as on advantages and disadvantages of such approach.

During last SAP TechEd 2017 in Las Vegas, I attended all C4C-related sessions and the main idea I’ve got there is that SAP suggested approach to extend C4C currently is to build your own application and embed it into C4C using HTML mashups. As an example during the session CPL171 “Building SAP Hybris Cloud for Customer Extension with SAP Cloud Platform” (hosted by Vladimir Pavlov , Stanimir Ivanov and Jeff Gebo ) was java/sapui5 combined app to find duplicate tickets in Service Request TI. You can find it here SAP Duplicate Tickets Finder Sample Application

However, this part of the journey was before this very interesting session.

There are two types of HTML mashups available.
The first one is URL HTML mashup. Here you’re providing a URL to your app hosted somewhere. And you’re able to pass parameters available from Port type you’ve selected for your HTML mashup on creation to the defined URL as query (e.g. URL) parameters.
This type of HTML mashup can be used to embed completely new app into your C4C tenant.

Technically what we have in case of URL HTML mashup is iframe with “src” pointing to our URL provided on creation.

Being in the iframe it’s like being in the cage. You can’t talk directly back to C4C. And we’re in a different domain and isolated. Here I’ve learnt a lot about Same Origin policy and CORS.

In this case the only way to talk data back or get additional data to use in your app is through C4C OData services.

But to talk to C4C OData services you need to authenticate yourself from your app to C4C. And this is, from my perspective, the main disadvantage of this approach. You need to get onboard Identity Providers or something else to pass the current user to your app and then back to C4C OData. It’s quite a pain to set it all up and sometimes this requires additional costs if you want, for example, take SAP Cloud Identity Management on board to help you. Thankfully, there is one very good news mentioned during SAP TechEd that we will hopefully have one “magic” button in C4C administration to set up SAP Cloud Identity Management with one click. So the setup topic will be covered with ease.

As a recap, disadvantages of this approach are:
You clearly can talk one way only to your app. And on load of your app only.
To talk back to C4C you need to set up authentication and identity management manually (current state).
And you’re in an iframe.

Advantages: you can easily embed applications which accept query parameters into C4C. E.g. some lists to present the query result. But not only those.

The second type of HTML mashups is Code HTML mashup.
This type of HTML mashup requires you to provide the code of your page during mashup creation.
From my perspective, it was much more interesting here. And here is why.

When I explored this option, read through help documentation <link_to_help> and studied other blogs on the topic, I found out that you can get predefined data from C4C into your app. But here comes the question – can we write back anything? And luckily the answer is yes.

Let me explain myself. When you create an HTML mashup you have to select Port Binding. It’s actually an inport and (!) outport assigned to Mashup Port Binding via Port Type Packages. Some standard Port Binding are two-way enabled. Means they have inports and outports with parameters. And Port Type defines which parameters you can use in both directions. It means you can both pass parameters into your app and write parameters back from your app.

Here the list of current standard port types which have outports:
Business & Finance
– Company Financial and Business Information by Company Name or DUNS
– Credit Card Tokenization for Wirecard
– DNB360 Mashup Integration
– Opportunity Info
News & Reference
– Knowledge Base Search
Productivity & Tools
– Registered Product Info
– Reverse Lookup
– Reverse Lookup by Phone
– Ticket Information

All standard Port Types related to HTML mashup topic can be found in port types package: /SAP_BYD_TF/Mashups/globalmashupporttypes.PTP.uicomponent.
In the folder /SAP_BYD_TF/Mashups/PortBinding you can find all standard Port Bindings.

You can explore which parameters are available in each case yourself.

But the first question I had was “why”? Why should I be restricted to only have port types parameters available to read/write the data?
Well. The answer is the same. You’re still in the cage of the iframe. Here how Code HTML mashup is rendered from the technical perspective:

As you can see we’re here in a double cage, e.g. in two iframes. The first one is coming from the dedicated server. In my case, it was “mashup-aus.sapbydesignmashups.com”. And the first iframe is “Container”. The second iframe “html/render” on the same server. Our code is in the second one. So we trapped again. That’s why we can’t simply write back to C4C.

However, in the opposite to URL HTML mashups, here under the container we have an interesting thing. It’s an XDM (cross-domain messaging) implementation (last <script> tag in iFrame 2 and script mashup-xdm.js included on the screenshot above) which allows us to write back the data. Along with the read and listening to update of the context.

Ok, then how to use them? Here we can refer to standard SAP documentation.

Let’s assume we’re dealing with “Reverse Lookup” port binding under “Productivity & Tools” mashup category.
If you select for example, “CompanyName” parameter in Input Parameters section and press Copy above this table, system will insert the parameter’s name as the first line in your code. It will look like:

sap.byd.ui.mashup.context.inport.CompanyName

If you select, again, “CompanyName” parameter in Output Parameters section on the right and press Copy above this table, the system will insert the parameter’s name as the first line in your code. It will look like:

CompanyName

Variable sap.byd.ui.mashup.context has all variable defined as inport parameters (those we can read in our mashup).
For example, as it has been mentioned above, sap.byd.ui.mashup.context.inport.CompanyName comes from this context and is available to build a logic in your app. So you’re simply reading this context whenever you need access to inport parameters in your app.

To write back the data we need to use function:

sap.byd.ui.mashup.fireResultUpdate({
  "<outport_parameter_name>" : <parameter_value>
});

where <outport_parameter_name> is the one we can get with Copy button above the outport parameters table. For example:

sap.byd.ui.mashup.fireResultUpdate({
  "CompanyName" : "ACME"
});

To subscribe to the context update event (in case if some fields might be changed in C4C and we want to capture an update of those) you need to create a function and assigned it to sap.byd.ui.mashup.onContextUpdate:

sap.byd.ui.mashup.onContextUpdate = function() {
  var oContext = sap.byd.ui.mashup.context;
  ...
}

You can even call REST service defined in C4C as described in the documentation:

sap.byd.ui.mashup.callService({
  serviceId: 'CW00001'
  parameter: {'query': 'SAP',},
  onComplete: 'serviceCallback_CW00001',
  onError: 'exceptionHandler_CW00001'
});

And the part which is not documented is you can send an error message to end user as well. It will be always an error message, no warnings or infos yet available:

sap.byd.ui.mashup.sendErrorMsg(<MessageText>);

Actually, there are more parameters there. The complete signature of this function is sendErrorMsg: function(sMsg, sUrl, line).
I didn’t use sUrl and line at all, so have no clue what they are for. Something to explore yourself 🙂

And one more thing here. Certainly, I’d prefer to use some different tool to develop this HTML mashup. But since we can only paste one HTML page, I couldn’t use WebIDE for example in full power. And here one-page template came in handy. I found the one on the web here SAPUI5 single file template using XMLViews, Controllers, Fragments and Custom Controls for bug illustrations, support requests or demos and adapted to C4C requirements.

If there is no Port Binding suitable for your needs you can create the one yourself. The approach I used was:
– Create Port Type Package defining both inport and outport structures.
– Create Mashup Port Binding, select category for it (it will be useful when you create a new HTML mashup to find your port binding), maintain Inport and Outport information.
– Create Embedded Component to put it into standard UI and bind via available standard outports.
– In this Embedded Component define data model required and perform required Read BO operations.
– Create an Outport with your custom port type and map parameters from this outport to your data fields (to read the data)
– Create an Inport with your custom port type and map parameters from this inport to your data fields (to write the data back)
– Create a section in your Embedded Component where you’ll put HTML mashup
– Create anchors for any element you can find in your Embedded component. Specifically, you must assign Referenced Anchors for outport and inport you’ve created. Otherwise, you won’t be able to add HTML Mashup to your EC.
For example, refer to COD_Account_TI and its outport Reverse_Lookup_Info_Out and inport Reverse_Lookup_Info_Result_In.
– Create HTML mashup with your custom port binding.
– In administration mode (changing master layout) add your HTML mashup to your Embedded Component.

This is it for now.

As a recap again.
Advantages of Code HTML mashup are:
– no need to deal with authentication and identity to write the data back;
– we can handle delta updates via onContextUpdate function;

Disadvantages of the Code HTML mashup approach are:
– the one-page restriction (your complete code should fit into one page);
– parameters are only available from the predefined set of inport/outport parameters;
– restrictions on what you can do (read, write back, handle updates, send an error message);
– you’re still in the cage of iframes.

Code HTML mashup worked quite well for my requirements. But I was not fully satisfied. Coming from ABAP and the on-premise world of SAP I’m eager to have more control over what’s happening within my app or UI control and how I can interact with the other parts of the system.

With Code HTML mashup I got my foot in the door.
But as you understand and the hint is in the heading of this blog post it was only the first part of the journey. The journey is over. Well, the journey is never over. However, this particular part of the Journey is over. So please wait for the second part of my (un)expected journey. And this one will be for sure the most unexpected one of all. Stay tuned.

Continue reading: SAPUI5 and C4C. My (un)expected journey. Part 2.