X

Best Practices from Oracle Development's A‑Team

Customizing specific instances of a WebCenter task flow

Introduction

Customizing the framework task flows in WebCenter is a common requirement for customers.  With MDS, customization rules are layered but often customers will need to customize specific instances of their task flows, or have different levels of customization on different instances or pages which are all under the same MDS layer. This post walks through an approach to achieve this by providing parameters to the customization to tailor it to suit specific instances. In this article we show an example where we customize a built-in WebCenter task flow.

Main Article

With customization, we can alter or extend the look & feel, features, and functionality exposed by a task flow. The essential concept here is that with MDS customization, we are altering the task flow definition as it appears to the framework at run-time. So in a sense, MDS customization rules are global in nature (within the same MDS layer), or in other words, every instance of that task flow is a customized instance, since we are applying customization to the task flow definition. Some customers however, find it necessary to customize specific instances of the task flow within the same layer of MDS. In this example I use WebCenter Spaces and the Wiki Task flow as an example. We will disable the ‘Organize’ and ‘View’ menus of the Wiki, and provide a parameter that the user can set to turn this customization on or off on a task flow instance level.

If you are new to customization, the Oracle documentation is a good place to start with the basics of customizing task flows and how to deploy the customization:      http://docs.oracle.com/cd/E25178_01/webcenter.1111/e10148/jpsdg_taskflows.htm

Analyzing the Task flow to customize

To begin, we create a new task flow customization project and open it in the customization developer role in JDeveloper (choose this at start-up, or use Tools>Preferences>Roles). To start viewing and editing the built-in WebCenter task flows, we enable the ‘Show Libraries’ option for the Application Navigator.

image001

Now we navigate to the wiki task flow to customize it. Locating the task flow you need to customize can be a bit challenging, especially if this is the first time you are trying to do it. Unfortunately, there is no easy way to isolate the task flow you need to customize from the library or identify the library in which it belongs to. The naming convention used is intuitive and usually gives a good indication of where the various artifacts are.

image003

Once we open up the wiki task flow, we see that there is a nested folder-viewer task flow inside :

image005

We drill in to the folder-viewer task flow, and you should see more nested task flows, and upon examination of the flows and the code, you see that it is the document viewer task flow that is actually rendering the wiki page content. This is a great way to learn how the task flows themselves are constructed and how they are re-used across scenarios. image007

From here we see that its the Document Viewer task flow that actually displays the wiki document. Open up the document viewer task flow to locate the JSF fragment that renders the content:

image009

Opening the ‘shellViewer’ View Activity, which points to the ‘viewer.jsff’ fragment, you can see the markup used by the document viewer. So we now know that the nesting structure is WikiPageFolderViewerDocumentViewer.

Plan your Customization

For the purposes of this example, the customization we are performing is simply to hide the File and Edit menus for specific instances of the task flow. Since we've already identified the nesting structure and the JSF fragments, the next step is to identify the page elements we need to modify in the markup.

 

image011

We also need to drive this customization based on a parameter that users can set on the task flow instance. Therefore before making this customization, the first step is to add the parameter itself. Since the parameter is being added on the wiki task flow, we open it up to edit and customize the task flow definition itself.

image013

 

  1. 1. Open the WikiPage task flow definition
  2. 2. Select the Overview mode to view it.
  3. 3. Select the parameters section.
  4. 4. Add a new parameter on the wiki task flow.
  5. 5. Use a descriptive name to easily identify the parameter, say 'enableCustomization', make the type Boolean and set the value to #{pageFlowScope. enableCustomization}.

We have just customized a task flow definition. We added a parameter to the WikiPage task flow and the parameter value was set to a pageFlowScope variable named enableCustomization. Now we have two more steps before we can use EL expressions on the page markup that is based on the value for the enableCustomization variable. Remember that the wiki task flow is composed of a set of nested task flows, and the actual page fragment we are about to customize belongs to the ‘DocumentViewer’ task flow. Therefore when we use the EL expression #{pageFlowScope. enableCustomization} within the page fragments in the  DocumentViewer task flow, the pageFlowScope object it refers to is the DocumentViewer task flow’s  pageFlowScope object and not the WikiPage task flow’s pageFlowScope. These two pageFlowScope objects are different because task flow calls and regions containing task flows get their own pageFlowScope that is different from the calling task flow.  Therefore, references to #{pageFlowScope.enableCustomization} will resolve correctly only within the scope of the wiki task flow at the moment, and is not valid on views inside the ‘DocumentViewer’ task flow. Holding this value in the session scope is not good enough because that would limit me from having a per-instance level customization toggle. So we need a way to propagate this parameter to the actual task flow where it will be used. To do this, we need to make the task flows in the chain pass on this parameter, by adding the parameter to these task flow definitions and passing on the value through the respective taskflow-call activities. Just the way we customized the WikiPage task flow, we add the parameter to the FolderViewer task flow.

image015

 

Now that the FolderViewer task flow has this parameter, we need to set this parameter by passing on the value the user will set on the WikiPage task flow. To do this, we open up the WikiPage task flow again.

 

image017

  1. 1. Open the WikiPage Taskflow and choose the Overview mode to view it
  2. 2. Choose the activities section
  3. 3. Select the task-flow-call activity that calls the FolderViewer taskflow
  4. 4. Open the Parameters section task-flow-call in the property inspector
  5. 5. You will now see the new parameter we just added to the FolderViewer task flow. Set the value to #{pageFlowScope. enableCustomization}.

Now you have added a parameter to the FolderViewer task flow, and when the WikiPage task flow calls it, you are setting the value for this new parameter by passing in the value that is set in the WikiPage task flow’s pageFlowscope. Now we repeat the same steps to pass in the parameter from the FolderViewer task flow to the DocumentViewer task flow. When completed, all three task flows will have a new input parameter. The WikiPage task flow’s input parameter is set by the user, and is held in a variable in the WikiPage task flow’s pageFlowScope. This value is passed in to the FolderViewer task flow’s input parameter, which holds it in a variable within the FolderViewer task flow’s pageFlowScope. The FolderViewer task flow propagates this value to the DocumentViewer taskflow through the DocumentViewer task flow’s input parameter. The DocumentViewer task flow holds this in its pageFlowScope, making the value accessible to its page fragments through the EL expression #{pageFlowScope. enableCustomization}. Now we can customize the viewer.jsff in the DocumentViewer and the parameter. Set the rendered attribute on the controls and components that we want to be able to hide based on the parameter value.

image019

Deploying the customization

Now to deploy the customization, you need to build the customization as a metadata archive, or a MAR file. The MAR deployment profile is available on the application (not the project).mar_deployment

Although you can deploy directly from JDeveloper, to better keep track of the artifacts, our recommendation is to develop a process (and integrate it with your CI solution) for generating a MAR and deploying it. You can either use WLST or the Enterprise Manager to deploy MAR files. WLST is useful when you needs hands off deployments and can be scripted. Enterprise manager provides you a web based UI to interact with and manage your MDS repository, as shown below.

mar_deployment

Once you have deployed or imported your customization metadata in to your MDS repository, you should see a new parameter on the task-flow. Setting the parameter can toggle the components we have customized. The new parameter can be set on per-instance of a task flow, so in this example, we can have two Wiki task flows on the same page, both looking different.

image021

To recap, the idea here is to create your customization to be dependent on a parameter, which itself can be created through customization. The parameter is globally available to the taskflow, but since the actual end-user customization is dependent on the value of the parameter, which can be independently set on each instance, the customization is applied on a per-instance basis. This enables us to customize individual instances of task flows, rather than customize the task flow across the entire application.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content