1

Configuring WDK Applications Junaid Asifali

.

Date 9/12/2007

2

Copyright © 2006-2007 EMC Corporation. All rights reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. EMC2, EMC, and EMC Documentum product names are trademarks of EMC Corporation. All other trademarks used herein are the property of their respective owners. All other brand names are trademarks or registered trademarks of their respective owners.

3

Table of Contents

Introduction......................................................................................................................... 4 General Configuration Elements......................................................................................... 4 WDK Application Configuration........................................................................................ 5

Application Inheritance................................................................................................... 7 Component Configuration File .......................................................................................... 8 Action Configuration File ................................................................................................... 9 LaunchComponent and LaunchComponentWithPermitCheck......................................... 10 ComponentList and ActionList Components.................................................................... 10 Accessing configuration elements from component code ................................................ 11 Questionnaire .................................................................................................................... 12

4

Configuring WDK Applications

Introduction Configuration allows us to change the functionality or behavior of the application without recompiling or changing code. In most cases, WDK uses XML to store configuration information. This information is managed by the configuration service and is easy to refresh during runtime. Configuration service caches this information in memory for fast lookup. The WDK refresh page (<app>/wdk/refresh.jsp) page can be used to refresh configuration dynamically. This white paper is focused on XML configuration and does not include details on Branding/Localization. Configuration in WDK application can be divided into the following categories:

• WDK Application Configuration - A WDK application is different from a J2EE Web Application. • Component Configuration – This refers to out of the box components like properties, inbox etc. • Action Configuration – This refers to out of the box actions like view, checkin, etc. • Control Configuration – Controls are defined as the smallest units of user interface and are

implemented as JSP tags. • Qualifier Configuration – WDK actions and components can be restricted by roles such as

‘Administrator’, ‘Contributor’ etc.

General Configuration Elements The following are the general configuration elements in WDK config files. The WDK development guide has additional details. 1<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> 2 <config version="1.0"> 3 <scope qualifier_name="qualifier_value"> 4 <primary-element 5 extends="primary-element:path_to_definition_file 6 notdefined="true_or_false" 7 version="version_number"> 8 <nlsbundle>fully_qualified_bundle_name</nlsbundle> 9 <filter qualifier_name="qualifier_value"> 10 <filtered_element>element_value</filtered_element>

</filter> </primary-element>

</scope> </config>

1. As WDK config files are XML based, they start with the standard XML declaration. 2. The ‘config’ element is the root element for all config files. 3. The ‘scope’ tag defines a context to which this configuration is applied. If the scope tag is empty,

the definition applies to all contexts. For example, <scope type=’dm_document’> indicates that the configuration applies to only to ‘dm_document’. Other examples - <scope role=’administrator> implies that this configuration only applies to administrative users.

4. The primary element could be an application, component, action etc.

5

5. The ‘extends’ attribute specifies inheritance. For example, a component that inherits from another component can be defined as <component id=’mycomponent’ extends=’/webtop/config/browsertree_component.xml”>. Please note the full path to the extended component configuration file is specified instead of a name.

6. The ‘notdefined’ element is used for hiding primary elements defined in parent scope. For example, <scope type='dm_folder'><component id="checkout" notdefined="true"></component></scope> hides the checkout component for folders.

7. Indicates the version. If not version is specified, the current configuration is assumed to be current. 8. The ‘nlsbundle’ tag specifies the bundle containing text strings used by the primary element. The

bundle is usually a properties file located in the ‘strings’ folder of a ‘WDK’ application. 9. Using a filter, certain child elements of the primary element can be scoped. For example <filter

role=’administrator’>.

WDK Application Configuration A WDK based J2EE Web application has a root directory which contains a WEB-INF folder. This folder has a web.xml file containing configuration information for the web application. This is mandated by the J2EE Servlet Specification

.A WDK application is a folder within the main J2EE Web application root directory. As shown in the screen shot above – webtop53SP1 is the main J2EE web application. This contains four WDK applications – custom, webcomponent, wdk and webtop. Please note that the name of the J2EE Web application can be the same as a WDK application. By default Webtop gets installed with a J2EE Web app name of ‘webtop’ and it contains a WDK app by the name of ‘webtop’.

6

A WDK application is Documentum specific and contains an app.xml file as the main configuration file. In addition to app.xml it contains a ‘config’ folder for XML configuration files, ‘theme’ folder that contains the style sheets and ‘strings’ folder for NLS strings. Please refer to the screen shot below:

A WDK application can have more folders or files in addition to app.xml, config, string and theme folders. Please observe the screen shot below for the ‘webtop’ WDK application. It has additional folders and files.

7

Application Inheritance The J2EE web application in the previous application consisted of four different WDK applications. Theoretically, it is possible to have any number of WDK applications within a main web application and these applications can inherit from each other. This inheritance is determined by the app.xml file of the WDK application. The first WDK application to be loaded is determined by the ‘AppFolderName’ parameter in the web.xml file of the J2EE web application. By default, this is custom. Any configuration in the custom folder overrides all other applications. <context-param> <param-name>AppFolderName</param-name> <param-value>custom</param-value> </context-param> For example, in standard out of the box Webtop the inheritance order is shown as below:

As shown in the screenshot above, the following is the order of inheritance: Custom webtop webcomponent wdk If we want to turn off all customizations, we can just change the app folder name in web.xml to ‘webtop’ and it changes the inheritance hierarchy as below: Webtop webcomponent wdk Here is another example involving WebPublisher. In WebPublisher, the default hierarchy is as below: Custom wp webtop webcomponent wdk To convert this WebPublisher to out of the box webtop, we can change the app folder name in web.xml to ‘webtop”. This changes the inheritance giving us standard webtop. Webtop webcomponent wdk

8

Inheritance is controlled by the <application> tag in the app.xml file of the WDK application. The following are the application tags for a standard webtop installation:

- custom <application extends="webtop/app.xml"> - webtop <application extends="webcomponent/app.xml"> - webcomponent <application extends="wdk/app.xml"> - wdk <application>

The ‘wdk’ WDK application does not inherit from any layers as it the core framework. The ‘webcomponent’ layer consists of common components used like the ‘doclist’, ‘inbox’, ‘search’, ‘attributes’ etc. Any tag that is present in an app.xml file overrides the same tag including sub-tags from ‘all’ the extended app.xml files. For example:

- The app.xml for custom has a tag – - - <authentication>

<docbase>dm_notes<docbase> - </authentication> - The app.xml for webtop or webcomponent has the same tag as: - <authentication>

<docbase>support</docbase> <domain>CORP</domain> <serviceclass>MyClass</serviceclass>

- </authentication> If ‘custom’ is the top level application, the authentication tag specified in the app.xml for ‘custom’ overrides other applications including sub-tags. In the example above, the domain and serviceclass specified are not read by the configuration service even though only the docbase is being overridden. The domain and service class tags need to be copied to the authentication tag for the ‘custom’ application in order to be read.

Component Configuration File WDK Applications define components. Logically, a component is an encapsulated piece of Documentum functionality like checkin, checkout, properties etc. A WDK component is composed of one or more JSP pages for UI and a component class that provides the server side logic. The component configuration file ties together UI and the server side class along with additional tags that define the component contract The following are the general configuration elements for a WDK component: <config version="1.0"> 1<scope qualifier_name="qualifier_value"> 2<component id="component_name" version="version_number"> 3<desc>Description goes here.</desc> 4<params> <param name="some_param" required=" true"></param> </params> 5<pages> <start>/custom/.../some_page.jsp</start> <custom_page_name>path_to_custom_page</custom_page_name>

9

</pages> 6<class>com.documentum.webcomponent.library.contenttransfer.importcontent.ImportContent </class> 7<nlsbundle>com.documentum.webcomponent.library.attributes.AttributesNlsProp</nlsbundle> 8<custom_element>custom_element_value</custom_element> 9<helpcontextid>attributes</helpcontextid> </component> </scope> </config>

1. Scope – Components can be scoped by role, type, docbase or any custom scope defined by a qualifier.

2. Component - Defines the name of the component along with its ID and version number. If version is not specified, it is assumed to be the current version.

3. Description – Component description. 4. Params – Defines the component contract. The WDK runtime enforces this contract and throws an

error if the params are not specified when invoking a component. 5. Pages – Defines the pages that are part of the component. The page name may be used in the

component invocation URL for accessing that specific page. For example, http://host:port/webtop/component/component_name/page_name If no page name is specified, the WDK framework uses the start page.

6 Class - Defines the component class. 7 Nlsbundle – Properties file that specifies the localized external strings. This file is located in the

/strings folder of the application directory and the path to the file usually follows the package name.

8 Custom Tags – Any custom configuration tag that can be read by the component class at runtime. 9 Helpcontextid – Specifies the ID that maps to a topic in the help component.

Please refer to the WDK Reference or the Dev. Guide for detailed information on component configuration.

Action Configuration File An action is an atomic operation that can be launched by a user interface element. Actions do not have a UI associated with them. They are typically used for launching components. 1<scope qualifier_name*=qualifier_value>

2<action id=action_id> 3<params>

<param name=param_name required=true|false> </param>*

</params> 4<preconditions>

5<precondition class=action_precondition_class> 6<role>role_name</role> 7<argument>argument_name</argument> 8<custom_precondition_element/>*

</precondition>* </preconditions>]

10

9<execution class=action_execution_class> 10<permit>permit_level</permit> 11<olecomponent enabled="true_or_false"/> 12<navigation>jump_type</navigation> 13<component>component_name</component> 14<container>launch_container</container> 15<custom_execution_element>* 16<arguments>

<argument name='argName' value='argValue'/>* </arguments>

</execution> </action> </scope>

</config>

1. Scope – The action can be scoped by a type, role etc. 2. Action Id – It uniquely identifies an action. 3. Params – Action contract. Please note that these params are passed to both the pre-condition and

execution classes. 4. Precondition – This is optional and contains one or more pre-condition elements. 5. Precondition – This tag contains one or more custom elements that are passed to the pre-condition

class. 6. Role – The user role who can execute this action. 7. Argument – This indicates a parameter in the parameter list that cannot be empty (like objectId). 8. Custom element – The custom values are passed to the pre-condition class. 9. Execution class – Specifies the execution class that implements the IActionExecution interface.

Both pre-condition and execution classes can be the same class. 10. Permit – This is specific to the scenario where the LaunchComponentWiithPermitCheck class is

used. 11. The rest of the tags specific to the scenario where the LaunchComponent class is used.

LaunchComponent and LaunchComponentWithPermitCheck Actions are typically used to launch components in response to a UI event. The ‘LaunchCoomponent’ and ‘LaunchComponentWithPermitCheck’ are convenience action classes provided by the framework for launching components. This saves developers the need to write a new action class just for launching components. Please refer to the dev. Guide for more details.

ComponentList and ActionList Components WDK framework provides a ‘componentlist’ component that displays a list of all the components (both custom and standard) that are part of the Web application. The component name is indicated along with a link to the XML configuration file. This is very useful for debugging if we are searching for a particular component and want to determine if different scopes have been defined for the component. Similar to the ‘componentlist’, an ‘actionlist’ component is also available as a separate download from the EMC developer website. This lists all the actions (standard and custom) that are part of the application and provided links to the XML configuration.

11

Accessing configuration elements from component code Consider the following component xml file: <config version='1.0'> <!-- this component has unqualified scope --> <scope> <!-- the About Webcomponent component definition --> <component id="test"> <!-- Description (not NLS'd) --> <desc> Test Component </desc> <!-- Component Contract --> <params> <param name="enableTools" required="false"></param> </params> <!-- Component Layout --> <pages> <start>/custom/component/test.jsp</start> </pages> <!-- Component Behavior --> <class>com.documentum.custom.Test</class> <!-- Component specific Configuration --> <test> <test1>testvalue</test1> <test2>testvalue2</test2> </test> <dummytag>dummy</dummytag> <nestedtag> <level1> <level2>level2</level2> <level1> <nestedtag> </component> </scope> </config> From a component method, we can use the lookupString method. The tag is specified in the dotted notation as specified below: //Get the value of test1 tag String val = super.lookupString(“test.test1”); //Get the value of dummytag String val = super.lookupString(“dummytag”); //Get the value of level2 tag String val = super.lookupString(“nestedtag.level1.level2”);

12

Component class also has ‘lookupInteger’ and ‘lookupBoolean’ for Boolean and integer values specified in the XML configuration file. Alternatively, we can use the’ Config Service’ as well to get a specific element. Config service allows access to all the configuration elements of different elements and actions. Please refer to the config service javadocs. A detailed description is beyond the scope of this paper.

Questionnaire

1. How do you define application inheritance in WDK applications? 2. How to you convert a WebPublisher install to a regular wdk (not Webtop) installation? 3. How do you extend components? Please give an example.

About EMC EMC Corporation (NYSE: EMC) is the world leader in information storage systems, software, networks, and services, providing automated networked storage solutions to help organizations get the maximum value from their information, at the lowest total cost, across every point in the information lifecycle. Information about EMC’s products and services can be found at www.EMC.com About Documentum Software from EMC Documentum software from EMC Corporation includes enterprise content management solutions that enable organizations to unite teams, content, and associated business processes. With a single platform, EMC Documentum software enables people to collaboratively create, manage, deliver, and archive the content that drives business operations, from documents and discussions to e-mail, Web pages, records, and rich media. The Documentum enterprise content management platform makes it possible for companies to distribute all of this content in multiple languages, across internal and external systems, applications, and user communities. As a result of deploying Documentum, thousands of the world’s most successful organizations are harnessing corporate knowledge, accelerating time to market, increasing customer satisfaction, enhancing supply chain efficiencies, reducing operating costs, and improving their overall competitive advantage. For more information about Documentum enterprise content management, visit www.emc.com/documentum or call 800.607.9546 (outside the U.S.: +1.925.600.5802).