Seeded Customizations using MDS in Oracle ADF

In the last post Personalization using MDS in Oracle ADF we saw the power of MDS Framework in Oracle ADF using which Users can personalize pages, components etc according to their own need. MDS saves these changes in MDS Store based on every user and applies on the runtime to the base document.

In Personalization, user is at the driver seat , changing things according to the needs. But there are cases where the application is developed and after there is a requirement of two different flavours of the same application. For example, there is a ADF application and there are two clients. One client wants some fields to be visible and some specific color settings while other client wants other fields to be hidden and different color settings. We can also put in this way, that one client want some regions (task flows) to be displayed and other client says other regions to be displayed.

Now in these cases the , making changes to the existing application will be difficult. Most common solution will be we create two versions of application , each version having specific changes required by the client. Hmm that works good for two clients but what will happen if there are hundreds, thousands of clients. One has to create / maintain same number of versions of applications. More to it, what will happen if there will be a common functionality change which needs to go to all versions. Maintenance will become a nightmare.

So by using Seeded Customizations provided by MDS, changes for specific needs / clients can be done on base document. There will be a single Base Application and changes corresponding to all the clients/layers will be done and these changes will be applied on runtime depending upon which client is using it..


Use Case :
There is a requirement that there is a ADF application which has one ADF Form on the page. There are two clients "ABCCorp" and "XYZCorp" which will be going to use this application. ABCCorp does not want to show Salary attribute to its users and want Employee ID to be in color "AQUA":

XYZCorp wants to show salary component to users and wants Employee ID background to be in color "LIME"

Lets get started with this Use Case :
Created a simple ADF Applications in Jdev 11.1.1.7 . Created ADF BC using HR schema with Employee EO and VO and AppModule.

In the VC Project, created a simple jspx page and used EmployeeVO to create a af Form.

Now we have a basic application with a form. We need to start customizing the application for both ABCCorp and XYZCCorp.

First step will be to enable Seeded Customizations in the projects.

This is done by ViewController -> Properties -> ADF View -> Enable seeded customizations.

Now the next and most important step is to create Customization Layer which will return the Name of the client, whether it is ABCCorp or XYZCorp.

So let us create a Customization class ClientCC which extends oracle.mds.cust.CustomizationClass provided by framework.

Now when you extends from CustomizationClass, one has to override these three methods. I will explain these methods and how to implement them in my next post. For now consider that getName method returns the name of CC layer and getValue method returns the current layer value. Here we are reading the value of client Name from Initialization Parameter in web.xml . If that parameter is set to ABCCorp, getValue method returns ABCCorp and so on.

Now we need to add this Customization Layer Class ClientCC to our application. But to make this class available, the project containing it needs to be deployed as ADF Shared jar and placed at <Jdev Home>/jdeveloper/jdev/lib/patches.

So after placing this jar to above path we are good. Now lets add this class to adf-config.xml.
adf-config.xml -> MDS Configuration

Now project is added with ClientCC Layer Class. Our setting in project is done.

Next step is to modify CustomizationLayerValues.xml . This file is available at <JdevHome>/jdeveloper/jdev
This XML file basically defines the design time values which can be returned from getValue method of CC class.

Add below XML to CustomizationLayerValues.xml

<cust-layers xmlns="http://xmlns.oracle.com/mds/dt">
    <cust-layer name="client" id-prefix="s">
        <cust-layer-value value="ABCCorp" display-name="ABCCorp" id-prefix="ABCCorp_"/>
<cust-layer-value value="XYZCorp" display-name="XYZCorp" id-prefix="XYZCorp_"/>
</cust-layer>
</cust-layers>

As one can see, there are two values defined ABCCorp and XYZCorp. This means when Jdev is open for customizations, these two values will be shown and one can select the values and make necessary changes for that value. Same these two values will be returned by getValue method of ClientCC class. Thus changes done to any value will be applied to the Layer returned by ClientCC get value method.

Next step is to open Jdeveloper in Customization Role. For doing this, go to Tools -> Preferences -> Roles -> and select option "Always prompt for role selection on startup".

After OK Restart the Jdev.

On Restarting, you will be prompted for the role. Select Customization Developer.

Jdeveloper will be opened in Customization Developer role and there will be a window , Customization Context in which by default one Value from CustomizationLayerValues.xml will be selected.

Now whatever changes one does, applies to this value returned by the layer. When ABCCorp is selected in Customization Context window -> Tip layer, whatever changes are applied on base application are for ABCCorp client.

Lets open our JSPX page which has Form.

Remember, there will be many things, component which will be read only. One cannot modify things which are core functionality of base document. Only things related to behaviour that can be customize will be editable. Also one can add new component for this particular value  

As per the requirement, on clicking on EmployeeId attribute of the form, we set the back ground color as aqua.

And made the Salary attribute of the form Render as false because ABCCorp does not want to show Salary Component.

We are done with change to ABCCorp. Save and close the jspx. Now select XYZCorp from Customization Context window and again open the JSPX.

For EmployeeID, XYZCorp needs background color as Lime, and Salary attribute should be visible.

Great we are all done. The only thing left is setting In Parameter. Lets first set it to ABCCorp. Restart jdeveloper in Default Role. Open Web.xml. Enter ClientName as "ABCCorp".

Now lets run the the JSPX page.

We can see that page comes up according to ABCCorp. Employee Id background is AQUA and Salary attribute is not visible.

Now lets change Parameter in Web.xml to XYZCorp.

Save and run the page again. 

Page Comes up according to XYZCorp. EmployeeId background is Lime and Salary attribute is Visible.

Also if we see the project structure , there is a folder MDSSYS created in View Controller project which has two folders ABCCorp and XYZCorp and they consist of CommonCorpPage.jspx.xml which is our JSPX. So these folders contains all the customized artifacts values in form of XML and are applied on runtime to the base document.

Thats it. By using powerful features of MDS provided by ADF, Customizations of the applications can be done according to specific requirements.

Thanks !!

Sample Application