Monday, March 4, 2013

Changing Labels on Built-In WebCenter Taskflows

Recently I have a request from a customer to change the label of Comment button of the DocumentViewer TaskFlow in a WebCenter Portal application, from "Comment" to "Post your comment". Here is a screenshot of the standard view of the documentViewer Taskflow with the comment sidebar.








The request itself is a customization request to change a label of a command button inside a built-in WebCenter Taskflow. There are two options to deal with customizations for WebCenter Portal: seeded customization or runtime customization. To give you an upfront warning, the seeded customization will not work for this case, and I will explain why.

First, let's look at the seeded customizations. To enable seeded customization, there are several prerequisites to do.
  1. Make sure in the application adf-config.xml, customization class is is pointing oracle.adf.share.config.SiteCC in the MDS configuration.
  2. Enable the seeded customization option in project property - ADF View.
  3. Change the Jdeveloper role to "Customization Developer" in Jdeveloper Tools and Preference. Restart Jdeveloper.
After the above, you can "show the library" in Jdeveloper and examine the standard task flow. In our case, we are looking for the DocumentView Taskflow. After examination, you would be able to find the comment task flow is wrapped inside a sidebar task flow and represented by a page/fragment called "ObjectCommentsSummary". The source code of the such page is composed of a single library tag ("ObjectCommentsSummary" tag) that cannot be further analyzed. According to Oracle Support, it's bundled and encapsulated within a taglib library and not available to edit from client code. So the conclusion here is it's a dead end.

You may ask - the label is wrapped into the resource bundle file and can we change from there? Unfortunately the resource bundle is also internal and is not available to edit. FYI: the resource key for the comment button label is "#{activityStreamingViewBundle.COMMENTS_LABEL_VERB_POST_COMMENT}".

Fortunately enough, we still have the 2nd option which is easy and straightforward. To enable runtime customization, we need to make sure the taskflow is wrapped by an Oracle Composer component which can render the page in the EDIT mode. You also need to make sure the login user you used to customize have the permission to edit the page. Here are the steps to implement the label change:

1). Open the page with the DocumentViewer Taskflow and click Edit to go to EDIT mode.

2). From the Edit mode toobar, click on "View" and choose "Source".






3). Scroll down the page and look for the comment button under the comment input area.











4). You will notice your mouse changed to a "Magnifier" icon. Click on the "Comment" button.

5). A warning popup will show up to confirm that you want to edit a shared component. The content of the warning message is "You are opening a shared component for editing. The changes you make will affect this instance and every other instance of this component on other pages".
















6) Click on "Edit" and you will notice in the source code view the selected component is highlighted.











7) With the component highlighted, click on "Edit" below the Edit Mode toolbar. The Component Property Edit Popup will show up and looks like this:





















8). Click on the down arrow icon on the right of the Text property and choose "Expression Builder" and type in your proposed text. In this case, the text is "Post your comment".















9) Click "OK" and "OK" to dismiss all popup. Click save button on the Edit Mode toolbar to save the changes and close the Edit mode. You will notice the Comment button's label has been changed to "Post your comment".







Please note since the comment task flow is reused through all WebCenter Portal service. Once the label is changed, all comment button's label will be updated too. You probably already notice this by reading the warning message on step 5. But if you need to update the label only on specific scenario (e.g: only for one page), you need to introduce additional parameters and register the parameter via customization layer.  So the label can be set dynamically on expression language.

There is another question before I wrap up this post - migration of the changes from one instance to another.

For the one change mentioned above, it's simple and you can redo the same steps on another instance. But when there are multiple customization changes OR at least there is a policy that blocks you to do such manual changes on some instance (like Prod), we need to use the script to migrate the changes. The runtime change is stored in MDS and in xml format. We can use WSLT script to export from one instance and import to another instance. Here are the steps:

1). Putty into your linux server. Navigate and run ./ORACLE_HOME/Oracle_WC1/common/bin/wlst.sh (Oracle_WC1 here is your WebCenter instance)

2). Run the following wlst command:

>exportMetadata(application='DomainA',server='WC_CustomPortal',toLocation='/oracle/tmp',docs='/oracle/webcenter/**')

The above command will export all pages into the '/oracle/tmp' directory. We do this step to target the page we need to migrate (See next step).

3). In the '/oracle/tmp', run the following command to find the string recursively.

>grep -r "Post your comment"

The command will return the metadata page. You can view the page and it contains the runtime changes was made.

4). Do an export with the target page (replace the targetPage with the metadata page return from step 3)

>exportMetadata(application='DomainA',server='WC_CustomPortal',toLocation='/oracle/metadata',docs='targetPage')

5). zip & unzip the target page to the target instance.

6). import the metadata on the target instance (replace the targetPage with the metadata page return from step 3):

>importMetadata(application='DomainB', server='WC_CustomPortal', fromLocation='/oracle/metadata',docs='targetPage')

7) Now you can test the changes on the target instance.

2 comments:

Rob de Gouw said...

JayJay,

This might be an old post, but is is the same issue as I'm facing right now.
However, in the current release of WebCenter (11.1.1.8+) it is no longer possible to select the button and edit the text.
Can you post the file that is being exported including content that is generated during the export (which you import later in the test / production environment)

Kind regards,
Rob

JayJay Zheng said...

Hi Rob, you should not look into manually create the MDS xml file and import it. if you cannot edit the button (or if it's disabled), please check if you have the right permission. This feature cannot go away on your version. the latest version is 11.1.1.9 by the way.