C4C UI extensibility overview
Cloud for Customer(C4C) use Personalization & KUT Adaption to do extension on UI. Let’s begin with the concept.
The phrase personalization is used if we talk about any changes that an End User is doing just for his own user. Technically that means the End User gets its files from the XRep layer $CUST plus all Change Transaction files from the layer $PERS.
The phrase adaptation is used if we talk about any changes that a Key User or a Partner is doing. Then it applies not only for one user but for the whole XRep layer which applies to all users which have assigned this layer. The changes are applied by the backend mergers in ABAP and not on the client.
To make a clear understanding on them, firstly we should have basic knowledge of XRep(XRepository) and Layer. We know every UI(we call it floorplan) has its own file described in XML stored in XRep as UI metadata. XRep provides lots of APIs to read, parse, active and do any other actions on the file. Layering is a concept to logically separate content that is provided either by SAP, Partner, Customer and End User. Layers are a hierarchy of levels in the XRepository content that enable you to make changes and additions without interfering with the content in a lower layer. When you make a content change on one layer, the change overshadows the content on the lower layer. UI files in $Load(load layer) will be fetched to frontend UI at runtime, change transactions(CT) created by adaption(customer layer & partner layer) are already in $Load, but CTs created by personalization(user layer) will be merged when each time opening the frontend UI.
Another obvious difference is that personalization can only do some adjustments on UI, without creating something like adding an extension field. Field extension is a big topic, which involves so many other topic to tell it, we may introduce it separately in the future.
Let’s try to adjust something on the UI and look at what happens. First open adaption mode by click “Adapt” on shell menu and select “Edit Master Layout”. Then move cursor over manager field in employee detail view and select Mandatory by clicking the checkbox, apply this change. This page will get reloaded after a short while.
Open the CT and check the details.
• UsedAnchor – Determine which element this CT affects.
• TargetFile – The floorplan where CT will be merged to.
• AddCondition – Property type, visible/read only/mandatory/enabled.
• fallbackValue – Property value.
Anchor is required for UI changes, in another word, if anchor is not existed, no options provide to users to carry out the change. For example, I open this floorplan in UI designer, and select the section group which contains field “Manager”. Open collections of anchors, then will see the stable anchor is here, this means all element included in this section group will be able to be adjusted via personalization and adaption.
Meanwhile there are some tools you can get CTs from frontend UI as well. This may make your work more efficient. First add this parameter “debugMode=true” to system URL, and reload the current UI. After finished, press CTRL + left click on “Manager” field, will get a popup window.
• Id – which can identify a unique control
• Get CTs – Retrieve CTs on this control
If you click “Get CTs”, all CTs will be quickly displayed, this is really a fast way. Note the id and switch to “Component Model XML”, search it.
You can quickly find the effect by CTs on current UI file. But this is only to show them, if you want to delete one CT, need to try another way. Enter adaption mode again and click the icon in the picture, in the next popup window select one item, you will get a detail page to show more information for on CT, there also provided “Delete” button.
SAP partners create UI changes within their solution. Usually partner developers launch UI designer in cloud studio. Open a floorplan, based on what element/node selected, there will be different options appear in extension explorer. Just click the buttons to do what they need. CT deletion is also from here, click the expand icon will show all CTs, each one has a remove button. CTs are included in solution package and can be transported to target tenant.
So far, these approaches are mostly a key user or partner developer can achieve, but for a C4C developer who may provide technical support, this is far away from enough. Completely understanding of XRep, BO metadata, UI metadata are required. Anyway, let’s first know some basic things.
How a CT created.
In client programs we define same change type in one class, like change properties (visibility/readonly/mandatory…) is handled in PropertyChange.js, these classes are in path sap/client/flex/change, dispatched in ChangeHandler.js, from where we get the exact handler class which defined in ChangeRegistory.js
when change happening, create CT is called.
Details of change content is in method parameter. CT creation is handled finally in ChangeTransaction.js, CT content is assembled here.
How a CT merged.
Key user CT is merged from ABAP backend. Handlers are in package AP_UI_FLEX. Different CT type has different merging logic. For example, visibility change logic is always delete old CTs firstly before merge new CT file. This is because multiple CTs for visibility change have “AND” conditions. If one CT setting visible to false, the results will always be false until this CT get deleted. CT merge will also trigger $load generation, which means, after CT merge finished, UI files in $load should be refreshed as well, to make sure next time open this UI changes are affected.
For a complex change, there may create more than one CT, for example set property fallback value depend on conditions. “AddCondition” & “AddBusinessLogic” CTs are both created to work together to achieve that.
Finally, CT will not only simply affect UI metadata, “AddExtensionField” CT will also make changes on BO model, so consistency become important. If extension field get lost from BO, it should not exist in UI anymore, otherwise there will be backend dump at runtime when parsing UI metadata.