Technical info and insight on using Oracle Documaker for customer communication and document automation

How to Permanently Customize Documaker Interactive Columns

Andy Little
Technical Director

If you have Documaker Enterprise Edition deployed at your site, chances are you're also using the Documaker Interactive component of this suite. Documaker Interactive (DI) provides a prebuilt application for creating new document transactions, processing manual documents from batches or real-time transaction, while giving you the power and flexibility of attaching documents from WebCenter Content and using a SOA/BPEL enabled approval workflow. All this and the power of a multi-lingual interface to boot! All in all, it's a very powerful tool in for your customer communication use cases.

There is a common requirement among the user base that hasn't (yet) made it into the product: the ability to permanently set the inbox column display. What exactly am I talking about? When a user enters DI, they are usually presented with the Inbox, which displays transactions they have created or have been assigned to them. The display includes some default columns, which are displayed in the language of the user's OS region/locale, so long as it's one of those supported by Documaker Enterprise. The default looks like this:

Default Inbox Display

Note: I prefer the Alta skin, which is not the default for DI. You can change your default skin by clicking User Preferences in the top right, and selecting "alta". You can also set your Time Zone here as well.

As you may or may not be aware, you can customize the column display by selecting View > Columns > Manage Columns. This will present a dialog in which you can hide or show any of the myriad of data columns that are available in DI.

Manage Columns Dialog Box

But here's the catch: the changes here are only for the user that makes them, and only for the current session. Log out and come back later, and you're back to the default again. Perhaps you have a business requirement that has mapped some data into the TRNCUS* columns, and you always want to display those, so users can sort their transactions. How do you it? Read on!

Before we get started, a few housekeeping items. This was tested with ODEE 12.6.2 on Oracle Enterprise Linux 7, attached to Oracle 12c database. Don't have a system? No problem, check out my previous posts on how to set up your own system, here or here. Keep in mind that these instructions will modify your deployed application, so if you decide to upgrade in the future, or accept a patch, it may overwrite these changes so you'll need to reapply the changes if you perform an upgrade or patch. As always, make a backup of any changed components in case you need to revert your changes. Let's get started!

Locate the DI deployable file -- this is the idm.ear file that's created when you ran the ODEE installer. This file is located in the ODEE Home (aka "ORACLE_HOME") specified during the installation. Navigate your file system to ORACLE_HOME/documaker/j2ee/weblogic/oracle11g/idocumaker_correspondence. (Note: if you're using DB2 or SQL Server, use that directory name in place of oracle11g). Inside this folder, you'll find idm.ear. Make a backup copy of this file. 

I highly recommend doing the following procedure on a Windows system where you can use the 7zip file explorer to navigate the EAR file and it's contents. Otherwise you'll need to unzip the EAR and WAR file, locate the JAR file inside, explode that, edit a file, and then rebuild the JAR, WAR, and EAR. That's a lot of work. With 7zip, you can just navigate the contents of the EAR file. Open idm.ear with 7zip, then double-click iDocuMaker_adf_main_ViewController_webapp1.war. That will open, then navigate to WEB-INF/lib. In here, you'll find oracle.idocumaker.ui.jar. Double-click that, and then navigate to components. Finally, locate Correspondence_Inbox.jspx, then right-click it and select Edit. This will open the file in Notepad.

7zip dialog

This is a rather large file that defines the basic Inbox view using a custom ADF tag library. You don't need to know ADF syntax to do what we're going to do, so no worries! Scroll down a bit in the file and locate the section that looks like this:

<af:column visible="#{attrs.idmkr_resourcebundle['INBOX']['Key3'] ? 'true' : 'false'}" sortProperty="#{attrs.idmkr_table_model.hints.Key3.name}" filterable="true" sortable="true" headerText="#{attrs.idmkr_table_model.hints.Key3.label}"
<af:outputText value="#{row.Key3}" id="ot10"/>

You'll see a lot of repeating information with minor differences, but the key component here is the visible="#{att..." bit. What this actually does is set whether or not a column is visible according to some defaults contained deep within the DI code itself. Here we aren't actually modifying the code at all, we're just going to set the expression to return false  for both cases on any columns that we want to override the default behavior. For example, many implementations don't use the Key3 value, yet by default it is shown. So let's change that to look like this:

 <af:column visible="#{attrs.idmkr_resourcebundle['INBOX']['Key3'] ? 'false' : 'false'}" sortProperty="#{attrs.idmkr_table_model.hints.Key3.name}"
                     filterable="true" sortable="true"

<af:outputText value="#{row.Key3}" id="ot10"/>

The expression syntax is delimited with a #{ }, and inside those delimiters is some logic that looks for an object. If that object (in this example, an object called 'Key3') exists, then the visible attribute is set to true, otherwise it is set to false. We override that behavior by setting it to false no matter the existence of the object or not. Technically you could replace the entire expression with a true or false (e.g. visbile="true" or visible="false"), but in case you ever want to revert back to the original you have it right there.

If you have other columns to set up to hide or show, go ahead and do those now. While you're here, you can also reorder the columns by moving around the <af:column> content -- just make sure you don't accidentally break the XML structure!

You might be tempted to change the column header text too if you were astute and noticed the headerText attribute. Don't do this. If you change this here, you will break the translation capabilities of the system. If you need to change the column headers, you'll need to do this in the DMKR_TRANSLAT tables instead. See the end of this post for more information on this!

Once you're done, save the file and exit Notepad. 7zip will then detect the changed file, and ask if you want to update the archive. Select OK. Next, click the "Parent directory" button to navigate up the directory tree (this is the folder with an up arrow). Once you get to the level of the JAR file that contained the update JSPX file, 7zip will detect the changed file, and ask if you want to update the archive. Select OK. Repeat this process, and you'll be asked if you want to save the changed WAR file, and you do, so click OK. Now you can close 7zip, you're done! Copy the new idm.ear file to the location where the original was located in ODEE_HOME.

Now comes the exciting part -- Deployment! Open up your WebLogic console, and login. Under Domain Structure in the left pane click Deployments. This will open the list of deployed items in the main pane. Scroll and locate DocumakerCorrespondenceAL1. Tick the box next to this app, then click Update above the table. If you replaced the idm.ear file directly on the WebLogic server's filesystem, you can click Finish. If you put your new idm.ear file somewhere else, click Change Path next to Source Path and locate the file, then click Finish.

Once that's done, you'll need to restart the managed server (JVM) where DI is running -- you can do this in WebLogic console too, by expanding Environment > Servers in the Domain Structure pane, then click the Control tab in the main pane. Tick the box next to the JVM running DI (usually this is idm_server_al1_1_1) then select Shutdown > Force Shutdown Now. You can wait a bit and refresh this page, or click the auto-refresh button and wait until the status of the JVM is reported as SHUTDOWN. Once shutdown, tick the box next to the server again, then click Start, and wait (either refresh or use auto-refresh). Once the server is back up, you can login to DI and you should see your brand-spanking new Inbox!

Customized Inbox

I hope this has been helpful - as always if you have questions or comments, you can reply below, or visit the Documaker Community.

Addendum: If you want to know where to change the column headings, fire up your SQL tool and query the DMKR_ADMIN schema:

SELECT GROUP_ID, ID, DISPLAY, DESCRIPTION, LOCALE_ID FROM dmkr_asline.dmkr_translat WHERE app_id = 201 and GROUP_ID like 'INBOX.ENTITY.%' order by GROUP_ID, LOCALE_ID

This will give you the GROUP_ID (which correlates to the "#{attrs.idmkr_resourcebundle['INBOX']['Key3']" attribute in the JPSX file -- just drop the "INBOX.ENTITY." and use the ending token, e.g. KEY3 to understand the correlation. The ID indicates a LABEL or a TOOLTIP. The LABEL is the column heading, and the TOOLTIP is displayed when a pointer is held over a column. The DISPLAY and DESCRIPTION should be set to the same value. DISPLAY is what is shown in the browser UI, and DESCRIPTION should be used for accessibility tools. You can make updates to the DISPLAY and DESCRIPTION here for the appropriate LOCALE_ID, and then restart the IDM server as shown above. An example SQL statement to update KEY3 is shown below:

SET DISPLAY  = 'MyKey3Header',DESCRIPTION  = 'myKey3Header' 

If you have other languages installed, you'll need to update those as well, substituting the appropriate two-character language code:

SET DISPLAY  = 'Clé 3 En-tête',DESCRIPTION  = 'Clé 3 En-tête' 

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.