Developing a Documentum Web Application. Developing a Documentum Web Application Featuring Documentum Web Development Kit 4.2

Transcription

1 Developing a Documentum Web Application Featuring Documentum Web Development Kit 4.2 1

2 Table of Contents OVERVIEW...4 USER INTERFACE DEVELOPMENT WEB DEVELOPMENT KIT (WDK) PRODUCT GOALS BENEFITS THE TOOLKIT SOFTWARE REQUIREMENTS WDK 4.2 ARCHITECTURE WHAT IS A WDK COMPONENT? CONFIGURABLE APPLICATION FRAMEWORK Actions and Action Service Configurable Menus Configuration Service Qualifiers WDK 4.2 COMPONENTS EXAMPLES OF WDK 4.2 COMPONENTS Checkin, Checkout, Cancel Checkout Import Inbox Properties Basic and Advanced Search VDM Workflow OTHER FEATURES Configurable Content Transfer Multiple Selection Support (Checkboxes) Multiple econtent Repository (Docbase) Support WEB DEVELOPMENT STANDARDS JAVA DEVELOPMENT JSP Servlets Java Classes APPLICATION SERVERS INTEGRATED DEVELOPMENT ENVIRONMENTS J2EE COMPLIANCE FOR WDK J2EE BLUEPRINT INTERNATIONALIZATION WHAT IS INTERNATIONALIZATION? WHAT IS LOCALIZATION? Locales Language selection FONTS, CHARACTER SETS, AND ENCODING Fonts Character sets and encoding (codepage) Client display limitations

3 6.4 ECONTENT SERVER SUPPORT Supported encodings Attribute field limitation DMCL initialization of client codepage Localized data dictionary labels WDK 4.2-POWERED SAMPLE APPLICATIONS WDKSPACE WDKAUCTION LEVERAGING BUSINESS LOGIC DOCUMENTUM FOUNDATION CLASSES (DFC) INTRODUCTION TO DFC PACKAGES DFC PROGRAMMING CUSTOMIZING THE DATA MODEL DOCUMENTUM DEVELOPER STUDIO WHAT IS DOCUMENTUM DEVELOPER STUDIO? FUNCTIONALITY DDS AND WEB CLIENT WORKFLOW MANAGER SETTING UP AN XML APPLICATION XML ROLE OF XML IN CONTENT MANAGEMENT XML SUPPORT IN DOCUMENTUM NEW CLASSES IN DFC AUTHORING AND PARSING XML IN DOCUMENTUM WHAT IS AN XML APPLICATION? The XML Application Folder XML Application Configuration File The DTD or Schema Application Support Documents THE DEFAULT XML APPLICATION HOW IS AN XML APPLICATION USED? Documentum XML_APP Processing Instruction NEW OBJECT TYPES IN DOCUMENTUM SUMMARY...37 APPENDIX A: LIST OF WDK 4.2 COMPONENTS

4 OVERVIEW Documentum Foundation Classes (DFC), Documentum Developer Studio (DDS), Web Development Kit (WDK), and XML are powerful options for developing Documentum-based applications. They can be used together or separately, depending on the application. This document will cover WDK 4.2 in the greatest detail, but will also provide information on DFC, DDS, and XML in order to provide you with a broader look into developing web applications with Documentum. USER INTERFACE DEVELOPMENT 1.0 Web Development Kit (WDK) WDK 4.2 is a set of presentation components and an application framework that is highly configurable. It is built on the Java platform. Together, these components and framework comprise a robust, flexible, scalable toolkit for building web applications that leverage the Documentum platform. Over 50 content management library operations are prepackaged to build rapid applications by gluing the components together. This includes both basic components, such as checkin, checkout, and import and many advanced components, such as the Workflow, Lifecycle, Rich Permissions, and Virtual Document Manager (VDM). In addition to this, there are sophisticated content transfer services that can handle operations involving multiple document selections. WDK 4.2, in addition to an application server, is functionally equivalent with RightSite and SmartSpace in a Java-based environment. Since WDK 4.2 is built in accordance to industry standards (JSP 1.1 and Servlet 2.2), developers can utilize the standard Java IDEs, tools and languages that they are already familiar with. This means rapid application development and deployment. The application developer can take this toolkit and produce custom web applications that leverage the power, flexibility, and security of the Documentum platform. The WDK architecture, at a high level, is displayed in Figure 1. In this diagram, presentation components, a configurable framework, and the J2EE development environment represent WDK. DFC provides the business logic. Figure 1: Web Development Kit 4.2 4

5 1.1 Product Goals WDK 4.2 provides an abundance of tools to the application developer, reducing development time and increasing the scope of the Documentum platform. It also lays a strong foundation upon which to deliver increased value. To summarize, the goals of WDK 4.2 are as follows: 1. To clearly separate the services/business logic layer of WDK from its presentation layer 2. To increase the breadth of WDK components and services to be functionally equivalent to RightSite and SmartSpace 3. To improve product deployment 4. To broaden platform support in terms of web client/server operating systems, application/web servers, web clients, and integrated development environments. 5. To fix bugs not fixed in previous product releases. 6. To provide a scalable run-time that can be included in custom web applications built to leverage Documentum content management capabilities. 7. Leverage the industry leader application servers like Apache Tomcat, ATG Dynamo, BEA Weblogic, IBM Websphere, Macromedia JRun, and Sun iplanet. 1.2 Benefits WDK speeds deployment as a result of component flexibility and reusability, reduces the learning curve for development teams, and provides a more immediate return on investment in standard technologies. WDK 4.2 was designed and developed to provide approximately 80% of the functionality that would be needed to build web application that utilizes the power of the Documentum platform. The other 20% of the application will be up to the individual developer or development team. This percentage may also change, of course, as the complexity of the application increases. On the other hand, if the developer decides to take full advantage of the configuration services, there may not be any additional programming necessary to create a custom application. WDK is the ideal solution for developers who want to quickly engineer applications that utilize common Documentum functionality. And since WDK is Java-based, developers can work within a familiar environment. Reusable components, the essence of WDK, can be used for rapid development of applications that perform common operations or customized as needed to accommodate diverse Web application requirements. Benefits Summary: Rapid application development. Reuse is the cornerstone for rapid application development. WDK comes with over 50 pre-built components, based on JavaServer Pages (JSP), to help developers build new applications faster than ever. For more information on JSP, please go the following: 5

6 Faster deployment. Supplied WDK components allow development teams to hit the ground running, providing a more immediate return on investment. Increased customer satisfaction. Because WDK operates on J2EE (Java2 Platform, Enterprise Edition, developers can take advantage of faster, more efficient debugging and other standard development practices, yielding a high quality application that meets the stringent requirements of today s business customers. For more information on J2EE, please go to the following: The Toolkit The WDK consists of the following tools: Java classes that conduct econtent Repository (Docbase) operations. These classes include: Command classes that conduct econtent Repository operations. Content transfer classes that manage checkout, checkin, import, and export of documents and XML between clients and a econtent Repository. The content transfer classes install and use content transfer applets in the client browser. The command classes and content transfer classes rely on the Documentum Foundation Classes (DFC) to provide basic econtent Repository functionality. Java classes for models and views of Documentum objects, such as models and views of the folder hierarchy in a econtent Repository or the document hierarchy in a virtual document. Java classes that manage configuration, context, menus, localization, events, and exceptions. JavaServer Pages that provide Documentum functionality by instantiating objects based on the Java classes and creating standard user interfaces. JSP pages can contain both server-side Java code and client-side HTML and JavaScript code, allowing you to generate dynamic content on the server and control its presentation and behavior on the client. You can customize these JSP pages as desired for your application. JavaScript functions and event handlers that support the user interfaces in the JSP pages. Some JavaScript functions reside in associated JSP pages, while others reside in files that contain only JavaScript. Services that allow you to configure your application and its components with XML, which reduces the amount of time and programming expertise required to develop your application. API documentation (Javadocs) for the WDK and DFC classes, and online help (Javahelp) that contains documentation for the JavaServer pages and application development tasks. 6

7 1.4 Software Requirements Before you develop a web application using WDK, you must install and configure the following server software: An HTTP server, which can reside on your development machine or on a separate machine. A Java application server, which communicates with the HTTP server and typically (but not always) resides on the same machine as the HTTP server. The Java application server must support both the Java Servlet Specification, version 2.2, and the JavaServer Pages Specification, version 1.1. A Documentum econtent server and econtent Repository (Docbase), which is accessed through a Docbroker and can reside on any machine. 2.0 WDK 4.2 Architecture The WDK Java classes can be used in your existing web development environment. You can deploy the WDK classes in your web server application. The WDK Architecture is built with the following elements: Presentation components: JavaServer Pages (JSP) that present static and dynamic content through WDK model and view classes and perform econtent Repository transactions through command classes. A configurable application framework for your application JSP 1.1 and Servlet 2.2 web application infrastructure Business logic encapsulated in the Documentum Foundation Classes (DFC) 2.1 What is a WDK component? We define a component as being all of the 'bits' that are required to implement a single piece of functionality. A component has a container and may have one or more supporting files. If the component has a UI then the container will be a JSP file, otherwise it will be a servlet. The supporting files could include Stylesheets; class files; config files; internationalization (I18N) resources - in fact any files that the component makes use of. The components are configurable, so they leverage the configuration of action services. This means that the components also have associated configuration files. The configuration files are XML files. This configurable application framework allows the application to be context sensitive. Example (Note: This example component has been simplified for illustrative purposes) 7

8 A WDK component might implement a tree control that represents a Cabinet/Folder hierarchy. This component is deemed to be all of the 'bits' needed to implement the tree-view. As this component has a UI, (the tree-view itself), it would be contained within a JSP page. The JSP page would make reference to the basic DFC class files, other Java class files, a stylesheet and would get configuration information from an XML file. The component may also need internationalization information which would also be included in the component. Figure 2 illustrates the 'pieces' that make up this typical component. Figure 2: WDK 4.2 Component 2.2 Configurable Application Framework The framework is all of the pieces that the WDK components use to operate and interact. It determines their behavior, look-and-feel and allows them to communicate with each other. The framework lets you configure the component's localization (L10N), branding/style, contentsensitivity, logging, behavior (redirection, error-handling etc.), presentation etc. Configuration is based in XML and allows components to be data-driven without the traditional coding that customization involves (e.g. extending a Java class). It is this approach that makes the WDK suited to rapid, flexible and very powerful application development. 8

9 Components Menus Widgets Action Service Configuration Service econtent Repository XML File System Figure 3: WDK Configuration "Stack Figure 3 outlines some the services that will be discussed in the next few sections Actions and Action Service Actions provide the ability to register handlers with the action service, so that these handlers get called first. Application logic gets placed here and then the commands get dispatched. This is one level of indirection that WDK provides, which means more capability to add application logic. The action service provides the ability to make the UI context sensitive. This is done by the construct preconditions. The preconditions are put into a configuration file. An example of a precondition would be: If the role is consumer, then the action add cabinet will not be available. The action service also provides: Data Driving Custom logic for your applications Configurable Menus Figure 4: WDK 4.2 Menu Figure 5: WDK 4.2 Menu WDK 4.2 has the ability to setup menus within XML configuration files. These menus are based on actions and the action service. Therefore, separate menus can be created for different 9

10 econtent Repository object types. For example, Figure 4 displays a menu that was created for a dm_folder object. Figure 5 displays a menu that was set up for a dm_document object Configuration Service The configuration service is the infrastructure layer that all components use. This layer provides the ability to read the configuration files that are available with the WDK components and the application. Then they take these files and store them in a namespace Qualifiers The easiest way to map roles will be to put them into a configuration file. The developer will still have the flexibility of creating a new role. The configuration services will read all of this data and store it into a namespace. You can then use this context from within the component. This allows custom application logic. A qualifier in the WDK encapsulates a set of values associated with a specific form of context. Role and type are examples of implementations of qualifiers that are provided with WDK 4.2. For example, you can configure a UI using: role = contributor, coordinator, etc. type = dm_document 10

11 3.0 WDK 4.2 Components 3.2 Examples of WDK 4.2 Components Checkin, Checkout, Cancel Checkout Figure 6: WDK 4.2 Checkin Component The checkin component gives the user several useful options. For example, as displayed in Figure 6, this component allows a user to create a version label and description, which are optional. The other optional settings available and can be used as needed Import Figure 7: WDK 4.2 Import Component 11

12 The Import component will has been enhanced to provide the ability of importing multiple files. It also has the built in intelligence to recognize certain file types and pre-define the import settings, which can be changed. For other file types, such as the ScreenCam movie that is displayed in Figure 7, the user will be able to select from a list of file formats. The XML Category can be selected for appropriate file types Inbox Figure 8: WDK 4.2 Inbox Component 12

13 3.2.4 Properties The Properties component has an associated XML file that sets up attributes that are editable and those that are for display purposes only. For example, Figure 9 displays the standard properties for the type document. This particular document has the editable properties of name, title, subject, keywords, and authors. These properties can be edited via this component and saved into the econtent Repository. The non-editable, or view only, properties are also available to be displayed. The XML file for this component can be edited, as all of the available options may not be necessary or even valid for the resulting application. In addition, custom types may have their own XML configuration file for the properties component as these custom types would often have unique attributes that are not a part of any other object type. Figure 9: WDK 4.2 Properties Component Basic and Advanced Search Figure 10: WDK 4.2 Basic Search Component There are different types of search options available in WDK 4.2. A basic search, also known as one box search, is the most simple search option available. The advanced search options, as displayed in Figure 10, will also the user to refine the search criteria. 13

14 Figure 11: Advanced Search Component VDM Figure 12: WDK 4.2 VDM Component Figure 12 displays the generic user interface of the VDM component. The user will be able to view the VDM tree, as well as have access to a menu with previously specific items. WDK

15 will provide support for several VDM operations. Some of these operations will have an associated user interface and others will not. For example, the VDM component will support the following VDM operations: Create New Document Add Child Remove Child Levels to Show Set Default Binding For View Show Different Version Set Binding Rule Set Copy Behavior Assign Version Label Save Changes Add Child Figure 13: WDK 4.2 VDM Component - Add Child Figure 13 displays part of the Add Child user interface. 15

16 3.2.7 Workflow Start Workflow Component This component displays a form that will allow a user to select from a list of available workflows and then additional optional information that may be helpful to the next set of recipient(s). Once that information has been entered, the user will then be able to start a workflow. In this release, the user will not be able to actually create the workflow itself. Figure 14: WDK 4.2 Workflow Component Start Workflow Workflow Status In addition to simply viewing the status of a workflow, users can drill down and look at the individual tasks. The capability to either halt or abort a workflow is also a part of this component. Figure 15: WDK 4.2 Workflow Component - Workflow Status 16

17 3.3 Other Features WDK 4.2 comes with several new features. The next three sections cover some of the other new features in more detail Configurable Content Transfer The content transfer services provide the ability to import, checkin, and checkout items via the web. The first time a user logs on to the WDK-powered application, a content transfer applet will be loaded. Even though some users may not like the idea of having an applet installed on their browsers, it is necessary for this set functionality. A web browser is stateless by nature and the applet is vital to creating the vital intelligence necessary for successful and secure content transfer Multiple Selection Support (Checkboxes) In previous versions of WDK, users were not able to select more than one item at a time. This option will continue to be available, if the developer decides it is appropriate. However, WDK 4.2 will include support for multiple selections (checkboxes) as part of the folder contents component. For example, a user may want to checkout two documents at the same time in order to make necessary changes. This option is now available Multiple econtent Repository (Docbase) Support Another new feature of WDK 4.2 is multiple econtent Repository support. This will allow a user to log into more than one econtent Repository during their session. This will also allow the developer to more easily create a federated environment. 4.0 Web Development Standards Web developers have a wide variety of options available to them today. There are multiple development platforms, as well as development tools. WDK 4.2 has been developed to utilize the Java platform due to its maturity in the marketplace. A Microsoft version of this product will be developed upon the.net platform once it is available. 4.1 Java Development JSP WDK leverages the investment in Java ServerPages (JSP). JSP is a server-side scripting environment that is used to create and run dynamic, interactive web applications. With JSP, you can combine HTML pages and script commands to create interactive web pages or powerful Web-based applications Servlets JSP pages compile into Servlets. Therefore any standard Java compiler can be used to develop with WDK. 17

18 4.1.3 Java Classes Developers who wish to extend the Java classes that come with WDK 4.2 can do so as long as they use standard Java methodology. The same is true if they would like to add additional custom classes to their applications. 4.2 Application Servers Application servers that are compliant with the JSP 1.1 and Servlet 2.2 specifications may be used. WDK 4.2 is designed to be compliant with these standards and there should not be any additional application server configuration required in order to start using the product. 4.3 Integrated Development Environments Individual Integrated Development Environments (IDE) will not be certified as a part of WDK 4.2. The developer may choose to use any IDE that is J2EE compliant. There are many IDEs that are a Java compiler and some that also contain support for JSP. There are also IDEs that are designed specifically for JSP. 5.0 J2EE Compliance for WDK 4.2 In an application stack, WDK serves as presentation layer and DFC serves as business logic. WDK is a set of presentation components and framework. It is written using JSP 1.1 and Servlet 2.2 specifications as defined in J2EE. 5.1 J2EE Blueprint Figure 16 is a snapshot of the blueprint that Sun published regarding what a J2EE compliant application would look like. On the presentation side there is JSP and Servlet technology. WDK provides that. On the business logic side, there are EJB containers. Today, DFC provides a set of Java classes. DFC does not live in an EJB container. It does not extract into an entity bean. When DFC was developed, EJB containers were not mature. DFC was implemented as a set of Java classes that are available to both the Java platform natively and to the Windows platform via a Java-COM bridge in the Microsoft JVM. 18

19 WDK DFC 4i Figure 16: J2EE Blueprint Internationalization 6.1 What is Internationalization? Internationalization is the process of enabling the translation of a program without modification of its executable code. An internationalized program supports user interfaces (UI) and user input in multiple languages. Internationalization is sometimes referred to as I18N, which represents the first and last letters of the word Internationalization and the 18 characters in between. The user can select a locale for the web session. All pages displayed in the application will be in the selected language, if the user has the proper display fonts installed for the browser. The user can enter data using characters from the selected language, if the user s system has keyboard support for the selected language. 6.2 What is localization? Localization is the translation of user interface and message elements into multiple languages. All visible text in WDK server pages has been externalized to simple text resource files which can then be translated into other languages. Localization is sometimes referred to as L10N, which represents the first and last characters and 10 characters between them. You can add UI resource bundles, in addition to the bundles supplied with the WDK. Your resource bundles extend standard Java internationalization classes. 19

20 Your application s user interface will be displayed in one of the languages you support, but you must also consider the fonts and encoding for those languages Locales A locale represents a specific geographical, political, or cultural region. A locale is specified in the WDK, and in all Java applications, by a locale code, which consists of an ISO language code and an ISO country code. See Java Locale Names and Country Codes in the Internationalizing and Localizing WDK-based Applications manual for more information. Your application specifies its supported locales in the application config.xml file. The list of supported languages will be displayed when the user logs in to your application Language selection The WDK login page detects the user s current system locale setting (language) and by default uses a compatible locale for the user s session. For example, if the user s locale is French Canadian, and your config.xml file lists French and Spanish, the default locale will be set to French. See Language negotiation in the Internationalizing and Localizing WDK-based Applications manual for more information. 6.3 Fonts, character sets, and encoding Fonts Application users select a locale for their operating system -- French, English, Spanish, Italian, German, Japanese, Korean, or other. There are dozens or even hundreds of fonts that can display all of the characters for the selected locale. A font renders the language characters through an encoding scheme, also called a character set. Users can select default fonts for their browsers using browser preference settings. If their selected font does not use the encoding of your WDK application pages (XML and JSP), then the content will not be rendered properly. Your localization process must specify the encoding for your pages, and optionally, specify in style sheets the fonts that should be displayed by the browser. WDK style sheets do not specify fonts. As a result, the HTML pages that are generated from WDK JSP pages will be displayed in the default font of the user s browser. The sample application, wdkspace, uses a style sheet that specifies font faces for Latin-1 languages. If you wish to change the fonts in the sample application to display double-byte characters such as Japanese or Korean, specify your fonts in wdkspace.css. 20

21 6.3.2 Character sets and encoding (codepage) Character sets (code sets) Languages are rendered with character sets. For example, the English alphabet is a character set that contains 52 upper- and lowercase letters. The Japanese character set kanji contains 1945 characters. Characters sets that have assigned binary values for each character are called coded character sets, or code sets. The most widely used character set in web pages is ASCII, which can represent very few languages, mainly English, Indonesian, and Swahili. The ISO character set, known as Latin-1, supports more languages. Because character sets are rendered with encodings, you will often see the words used interchangeably. However, some character sets do not have assigned encodings. Encoding A character set is encoded in binary octets. The mapping of the character to the binary sequence is called an encoding method or scheme. Languages can often be encoded with several different schemes, and no single encoding is used for every language. Character set names are registered with the Internet Assigned Numbers Authority (IANA) at character-sets. Names are case-insensitive and are specified in the HTTP and MIME Content-Type headers that are sent from the browser to the server and from the server to the browser. WDK default encoding The lack of a standard encoding scheme is a problem for multilanguage web sites or intranets. The Unicode standard addresses the need for an encoding that can represent all character sets. Unicode defines a 16-bit, fixed-width character encoding scheme. The standard assigns each character a unique code point, with the capability of encoding over a million unique characters. Unicode includes several encoding schemes: UCS-2: double-byte encoding (default Unicode encoding) UTF-8: 8-bit encoding The WDK specifies UTF-8, one of the Unicode encoding schemes, in every XML and JSP page. Unicode encodings are designed to be capable of rendering every known language character. Unicode is represented by several encodings, including UTF-8, UTF-16, and UCS-2. Some of the encodings used by current Documentum customers include Latin-1 (French and German), K EUC (Korean), SJIS and EUC (Japanese), none of which is a Unicode encoding. Even though Unicode can represent all characters, most of the world s thousands of fonts do not use a Unicode encoding. Changing the encoding Encodings other than UTF-8 are not supported by WDK. If you change the encoding, you must translate form data from your encoding to the Java String encoding (UCS-16), in the same way 21

22 that DwFixEncoding translates form data from UTF-8 to UCS-16. Certain elements of your application must be in Unicode: XML files must be in a Unicode encoding scheme. Attributes stored in the econtent server must be in Unicode. URLs must be in ASCII format. Non-ASCII characters must be in escaped hexadecimal format. If you change your application s encoding scheme, you must change the encoding specification in every WDK XML and JSP file. See Specifying the encoding in the Internationalizing and Localizing WDK-based Applications manual for implementation details. If you do not specify the encoding, client browsers will default to rendering content in the ISO (Latin-1) encoding, which will look like gibberish to non-latin1 language speakers. The encoding of your web pages affects only the display and user input, not the content of objects that are imported into or exported from the econtent Repository. The econtent server is unaware of the encoding for documents stored in the econtent Repository Client display limitations There are two ways to display fonts correctly in your user s language of choice: Create CSS files that specify fonts that are compatible with your encoding. The font faces that you specify must be a set of fonts that are likely to be found on the systems of all users of your application. Do not specify fonts. Set the encoding in your JSP pages and XML files, and let users change their browser font preference to one that is supported by your encoding. See Localizing styles in the Internationalizing and Localizing WDK-based Applications manual for information on creating locale-specific style sheets. 6.4 econtent server support Versions of the econtent server prior to 4.2 did not support data dictionary data or attribute values in non-latin1 languages. With the 4.2 server, attribute data and data dictionary data are stored in UTF-8, and localized versions of the data dictionary in several languages is supported Supported encodings The following encodings are supported by the econtent server: Documents stored in an econtent Repository can be encoded with any encoding scheme. 22

23 Object attributes can be encoded in any encoding scheme. They are translated into UTF-8 for storage in the econtent Repository. Object type names and attribute type names are limited to ASCII characters, although you can escape non-ascii characters using their hexadecimal representation. Data dictionaries can be localized to display messages, error strings, and labels for object types and attribute names. Data dictionary entries must be in a UTF-8 encoding Attribute field limitation Field length for attributes is an important consideration in localization. Asian languages typically use three bytes in the UTF-8 encoding, which limits field length. For example, a 32-byte author field will hold only 10 Asian characters DMCL initialization of client codepage The 4.2 econtent server requires a new dmcl.ini setting to enable Unicode (UTF-8) support. See DMCL client codepage in the Internationalizing and Localizing WDK-based Applications manual for instructions on setting the client codepage for the WDK HTTP server Localized data dictionary labels WDK has externalized all user interface strings to properties files for localization. This includes labels for common attributes such a authors, keywords, or creation date. These labels can also be localized in data dictionary files. The WDK provides all strings in accessible properties files so that you can localize all strings for a given interface in one or two files. If wish to leverage data dictionary localization, however, you can remove the labels from component configuration files, and the WDK will display labels from the data dictionary, passing in the user s locale. 7.0 WDK 4.2-powered Sample Applications For the convenience of the developer, there are several WDK 4.2 Powered sample applications that are available. There is an example of a library services client, an example of a custom application, and an example of a role-based client. Each of these applications will be shipped as a WAR file, which is part of the J2EE standard. 23

24 7.1 WDKSpace Figure 17: WDKSpace Sample Application WDKSpace is a sample library services application that can be added during the installation process of WDK 4.2. The user interface is similar to that of the Intranet Client purely to demonstrate functional equivalence. This application will ship as a WAR file and if the user chooses to deploy this application at a later time, then that option is available. Please note that WDKSpace is an unsupported sample. WDKSpace is also not a supported product and can not be installed as such in a production environment. This application is only to be used for educational purposes. 24

25 7.2 WDKAuction Figure 18: WDKAuction Sample Application WDKAuction is a sample of a customized application that will also be available as a WAR file. However, it will not be part of the WDK 4.2 installer. This application is also for educational purposes as it is not a supported product. LEVERAGING BUSINESS LOGIC 8.0 Documentum Foundation Classes (DFC) Documentum applications depend heavily on the Documentum object model, which is the object-oriented structure by which econtent Server organizes the contents and control mechanisms of econtent Repositories (Docbases). Therefore, it is a good idea to get a general overview of the Documentum Foundation Classes (DFC). The following section on the DFC is more deeply technical than the rest of the sections included in this document, but will provide the background necessary in order to understand how it fits in the development cycle. 25

26 8.1 Introduction to DFC DFC exposes the Documentum object model as an object-oriented client library. It is leveraged by both client/server architecture such as Desktop Client and web such as WDK. DFC consists of the following: A set of interfaces that provide the DFC programming model. This programming model specifies how an application interacts with the DFC objects that implements these interfaces and the relationship between these DFC objects. The objects in this model consist of persistent objects stored in a docbase and non-persistent objects returning from a query or generated by DFC. A Java implementation of this model. It consists of several Java packages each contains a number of Java classes and interfaces. These packages will run in both the Microsoft and Sun s Java virtual machine that support JDK 1.1. On-line documentation (JavaDoc) of this class library is provided. It also provides tracing and exception handling. A set of COM interfaces and wrapper classes are provided with the DFC to make its Java implementation available to COM components. Since the DFC appears as a set of COM components, it is accessible by clients written in Visual C++ and Visual Basic. 8.2 Packages DFC is organized into packages, that is, sets of related classes and interfaces. The names of DFC Java classes begin with Df (for example, DfWorkflow). Names of interfaces begin with IDf (for example, IDfWorkflow). Interfaces expose DFC s public methods and constants. Each interface contains a set of related methods. Table 1 describes the purpose of the classes and interfaces of DFC packages. Table 1: Description of DFC Packages Java Package Name Com.documentum.fc.client Common.documentum.fc.client.qb Com.documentum.com Com.documentum.fc.common Purpose Provides basic functionality Establishing DFC sessions Retrieving and validating data Managing workflows Manipulating virtual documents Working with document versions Constructs and runs queries and Smartlists Facilitates accessing DFC from COM. Supplies utility methods for other DFC classes 26

27 Com.documentum.operations Com.documentum.operations Com.documentum.registry Supports econtent Repository (Docbase) sessions. Provides high-level functionality, such as checking documents or virtual documents in and out. Maintains Documentum information on the client s system, using the Windows registry on Win32 platforms, and.ini files otherwise. 8.3 DFC Programming The picture below shows a subset of the DFC interface interaction. The application developer will first call the static method DfClient.getLocalClient() to get back an IDfClient interface. Then call the IDfClient.newSession(...) to establish a DFC session. From there, you can retrieve a persistent object by calling IDfSession.getObject() and pass in an object id. IDfClient getlocalclient() getremoteclient( location ) getclient() getsharedsession( docbase, IDfLoginInfo, key) newsession( docbase, IDfLoginInfo ) findsession( dfcsessionid ) adoptdmclsession( dmclsessionid ) IDfSession getsharedsession( docbase, key ) newsession( docbase ) getsession() getobject( objectid ) getobjectwithtype( objectid, objecttype, classname ) getobjectbyqualification( qual) getobjectbypath( path ) newobject( typename ) IDfQuery execute( DfSession, querytype ) gettype(typename ) IDfCollection IDfPersistentObject gettype() IDfType gettypedobject() IDfTypedObject getattr( index ) IDfAttr getid( attrname ) IDfId DFC exposes most of the Documentum object hierarchy as a set of interfaces. An interface defines a contract between an implementation class and any client that uses instances of that class. Interfaces do not specify implementation. They simply define a set of methods with specific signatures and specific semantics. A class provides the implementation, but as an application programmer, you usually don t need to know which class. If you hold a reference to a class that implements a given interface, you know that objects of that class have all of the 27

28 functionality that the interface promises. DFC includes a default implementation for each interface. In Figures 19-22, you can see how the interfaces that derive from the Documentum hierarchy fit into the total DFC interface hierarchy. Figure 19: IdfTyped Object 28

29 Figure 20: IdfOperation Figure 21: IDfOperation Node Figure 22: IDfClientRegistry Object A Small DFC Program The following fragment from a Java program that uses DFC contains three blocks of code. They implement the first three steps of the procedure. IDfClient client = DfClient.getLocalClient(); IDfLoginInfo logininfo = new DfLoginInfo(); logininfo.setuser("mary"); logininfo.setpassword("gandalf"); logininfo.setdomain(""); session = client.newsession("mydocbase", logininfo); IDfDocument document = null; document = (IDfDocument) session.newobject("dm_document"); document.setobjectname("report on Wizards"); document.setcontenttype("crtext"); document.setfile("c:\temp\wiz.txt"); document.save(); The first block creates the client object, which encapsulates the Documentum client software. The second block creates and populates an object to hold login information and uses it to manufacture an IDfSession object, which encapsulates a session for this application program with the specified econtent Repository (Docbase). 29

30 The third block of code creates and populates an IDfDocument object and saves it in the econtent Repository. Notice that the newobject method of the session object manufactures the object. The newobject method returns an IDfPersistentObject object. The program explicitly casts it to an IDfDocument object, then uses the document object s save method, a method that IDfDocument inherits from IDfPersistentObject. COM does not support interface inheritance, so the Visual Basic and C++ versions of the above code explicitly cast the document object to a persistent object before saving it. Most DFC methods throw DfException to report errors. Java code like that in the above example normally appears within a try/catch/finally block, with an error handler in the catch block. Visual Basic code uses the On Error Goto statement to handle exceptions. More information on DFC can be found in the Using DFC in Documentum Applications manual. CUSTOMIZING THE DATA MODEL 9.0 Documentum Developer Studio Documentum s Developer Studio provides the application developer the ability to define application specific data such as custom types, lifecycles, etc. that are utilized in building Documentum applications. Figure 23: Documentum Developer Studio 30

31 9.1 What is Documentum Developer Studio? DDS is the facility used by application developers to create and maintain their DocApps. A DocApp is a collection of econtent Repository objects that make up a Documentum based application. DDS provides the ability to externalize the application in the form of a DocApp Archive. These archives can be installed in the customer's deployment econtent Repository using the DocApp Installer (DAI). An important aspect of the DocApp is that parameters can be used for econtent Repository specific information. This makes the DocApp Archives portable from one econtent Repository to another. The DocApp Installer replaces the parameters with values that the user provides when she installs the DocApp in a deployment econtent Repository. Before the advent of DDS, users accomplished the deployment using a combination of scripts and econtent Repository dump and load mechanism. The successful transfer of an application from the development to a deployment econtent Repository required considerable expertise and significant custom development effort. Documentum based applications consist of econtent Repository elements such as Object Types, Document Lifecycles (DLC), Workflow Templates, Methods, Jobs, Procedures, Folder Hierarchies as well as business logic and presentation code. In general, DDS only deals with the econtent Repository objects and does not address the business logic or the presentation logic. However, the DocApp architecture was intended to address all aspects of applications and DDS does provide some facilities to organize the functional components of applications associate them with the econtent Repository hierarchy, even distribute the components to end user machines. 9.2 Functionality The DocApp architecture introduced the notion of Functionality. A Functionality is a system capability that the end user uses to manipulate an object or several objects in a econtent Repository. It is implemented by a component that encapsulates the business logic and the presentation facility that the user can use to perform the operation. Functionality can be broadly classified as Object Type Specific and Global. Type Specific Functionality is applicable only to the instances of the Object Type it is defined for. For example, the 'Check In' functionality is applicable only to instances of dm_document (objects that have content). Global Functionality is applicable to all objects. The 'Import' Functionality is applicable to instances of all object types. Type Specific Functionality can be inherited down the type hierarchy. For example, the 'Check In' functionality is inherited by all the descendants of dm_document in the object hierarchy. 9.3 DDS and Web Client The DocApp Architecture does not assume that Functionality is implemented using a particular technology. It is possible that Functionality is implemented as a WDK component or even as a JSP/ASP page. However, the Documentum Intranet Client chose not to use this facility. 31

32 We plan to address issues in the present implementation of Functionality support and to extend the support to WDK components. The benefit will be a uniform Object Type base customization scheme for DTC and WDK. This will present a more coherent view of application development to the users and reduce their learning curve. 9.4 Workflow Manager The Workflow infrastructure is a vital part of the Documentum system. The econtent Repository would be an inanimate lump of information but for Workflow. Workflow has given us the edge in Document Management and will be an important differentiator in the Content Management. Robust Workflow will be an essential prerequisite for any B2B initiative. The Workflow infrastructure consists of the engine that is built into the Server, client Inbox capabilities built into the client applications (DTC, Intranet Client, WebPublisher, WDK) and the Workflow Manager that is a part of DDS, DTC and Intranet Client. SETTING UP AN XML APPLICATION 10.0 XML The Documentum platform has rich capabilities for handling XML content (chunking, assembly, zone searching, etc). This is built into our DFC layer and exposed seamlessly to both Web (WDK) and Desktop clients Role of XML in Content Management XML is rapidly becoming the standard language for e-business, including catalog creation, Web publishing, and transactions between trading partners. XML enables businesses to create, publish, and repurpose content from one source and reuse it throughout the enterprise. An XMLbased product specification, for example, can be used in a variety of different ways, publishing this information on a company Web site, developing marketing collateral describing product features, and composing catalog content distributed to customers. Within Documentum, individual pieces of documents, chunks, have access to all the features of a econtent Repository, including lifecycle and workflow capabilities. Documentum also provides standard document library services to XML content, including check in, check out, and editing. Individual chunks of XML are treated as individual objects in the econtent Repository. A configuration file controls how XML content is processed within a econtent Repository XML Support in Documentum The XML support in Documentum allows you to: Configure the storage, parsing, and searching XML content Specify validation against a document type definition (DTD) 32

33 Decompose XML into fragments that can be processed as individual objects with properties and behaviors. This is commonly called chunking. Specify, query, and extract metadata (properties) associated with XML content and chunks. Populate Documentum attributes automatically Manage links in an XML file Transform XML from an econtent Repository to a schema for exchanging business information, or to a format for publishing. Enable searching of XML documents using Verity zone searching Use XDQL to embed queries in an XML file. XDQL is an extension to the Document Query Language (DQL). An XDQL query can return a DOM object, a file, or a stream. You can call XSLT from XDQL, and you can call XDQL from XSLT New Classes in DFC The XML capabilities of DFC are provided by a number of new classes in DFC. For most of the basic document processing operations within Documentum, a new step has been added for processing XML, apply XML application. This step uses the XML configuration file to tell Documentum how to process and store the individual chunks within the EContent Repository. The other two operations that are specific to XML processing are transformation and validation. Transformation allows native XML content to be changed into a different format, like HTML, for example. Style sheets control how XML will be transformed into different formats. Validation requires that XML content conform to the rules of a document type definition (DTD). Documentum allows validation to be included in a lifecycle operation, for example. Documents composed in XML are treated as virtual documents within the EContent Repository. The same rules regulating processing virtual documents apply to XML documents. Rules within the XML configuration file control how parent and child chunks are treated. For detailed information on the new classes, see the Javadocs for DFC. The Javadocs for DFC are being shipped with the DFC Authoring and Parsing XML in Documentum The XML that you use with Documentum must be well-formed, written in accordance with XML language criteria. If your XML application requires that the XML be valid, there must be a DTD or schema associated with a particular document. The DTD is included in the XML application folder within an econtent Repository. To author XML, use any text editor or XML editor that meets your needs. Documentum integrations with both Softquad and Arbortext provide authoring and editing capabilities for XML. For information about third-party XML editor integrations, please refer to the release notes for Desktop Client. The Web Publisher Editor from Documentum allows you to author and edit XML in templates that enforce business rules. To parse and transform XML, DFC uses the Xerces XML parser and the Xalan XSLT stylesheet processor from the Apache Software Foundation. 33

34 10.5 What is an XML Application? A Documentum XML application defines the rules for processing XML documents. The information in an XML application defines: Validation rules using DTDs or schemas when the document is imported or checked in Rules for storing the XML content as objects in the econtent Repository Setting properties on the resulting objects Interpreting and managing links Processing parsed entities Handling the XML content during standard document processing operations, including check in, check out, export, and delete Note: There are no limits to the number of XML applications you can have in Documentum. The exact number depends on the different types of XML documents you have and the business rules governing them. To support XML functionality, an XML application contains these new Documentum objects: A folder of type dm_xml_application Named the same as the XML application name Stored in system/applications folder Detects the XML application An object type dm_xml_configuration Stores rules for processing an XML document Customer-specific DTD or schema, if desired Cascading style sheets, XSL style sheets, and FOSIs, if desired Note: DTDs and schemas are not required by an Documentum XML application. They are needed only if document validation against a DTD is desired The XML Application Folder The XML application folder holds the components included in an XML application, including DTDs, configuration files, and supporting documents. The attributes in the folder object determine which XML application is applied to any given XML document. These folder attributes must be set up before creating an XML application. For information concerning how to setup folder attributes, refer to the section on Creating XML Applications XML Application Configuration File Each XML application has a configuration file that describes what kind of documents the application can process and the rules by which the documents are processed. A configuration file specifies: What objects are created in the econtent Repository for XML content 34

35 The mapping between XML elements and object attribute values in the econtent Repository The location of parent and child documents in the econtent Repository Processing of links in the XML The configuration file is an XML document. The DTD required for all XML application configuration files is supplied by Documentum and is named config.dtd. All XML application configuration files must conform to this config.dtd, and it must not be modified. For information about the config.dtd used to define the XML application, please refer to the config.htm file provided by Documentum on the FTP site The DTD or Schema If a customer-supplied DTD for an XML application is in the econtent Repository, Documentum will use it for validating an XML document, if validation is required. Documentum downloads the DTD to client machines and patches the system declaration to the location of the DTD Application Support Documents An XML application may require additional documents to support authoring in XML. These documents include cascading style sheets, FOSIs, and the like. If your particular application requires these kinds of documents, create a subfolder in the XML application folder called Application Support Documents. These files are downloaded to clients during standard Documentum document processing operations The Default XML Application Documentum provides a default XML application, named Default XML Application, stored in systems/applications. The default application is used whenever an XML document is not associated with a user-defined, custom XML application. The default application has a configuration file that is also named Default XML Application, stored in the application folder as an object of type, dm_xml_configuration. For details about setting up the configuration file, see the Creating XML Applications section of Creating Documentum XML Applications. You can modify the Default XML Application to set up rules for processing XML content How is an XML Application Used? An XML application manages how XML content is processed during standard document processing operations in an econtent Repository. When a user imports or checks in an XML document, for example, the system first determines which XML application to use to handle the specific XML document Documentum XML_APP Processing Instruction If the document has an XML_APP processing instruction at the beginning of the file, the application named in the instruction is used. This overrides any other user selection. The processing instruction is: 35

36 <?dctm xml_app= xml_application name?>. If processing is not desired, put the following: <?dctm xmlapp= ignore?> If no matching XML application is found, the default XML application will be used to process the content. During the apply XML application step, the configuration rules for the given application determine subsequent processing of XML content. If validation is required, then the document is parsed in validation mode. If there is a DTD in the application folder, it will be applied to the document and the XML content validated against it. If a schema is specified, then schema validation will be performed. If there is no processing instruction, the system extracts the following values from the prolog of the document: Root element System identifier Public identifier Namespace of the root element These values are indicated in the prolog of the XML document, as follows: <?xml version=1.0> <DOCTYPE cellphone-catalog PUBLIC '/Documentum/DTD CellPhoneInlineEntity//EN CellPhoneInlineEntity.dtd > <cellphone-catalog> <?xml version= 1.0?> <!DOCTYPE cellphone-catalog SYSTEM CellPhoneInlineEntity.dtd > <cellphone-catalog> Then, the system queries the attributes of the XML applications in /Systems/Applications to find potential XML applications for the document. The Documentum client presents all potential matches to the user. If the user fails to choose a match from the list of potential matches, the system chooses the first XML application returned by the query New Object Types in Documentum XML applications are supported in econtent Server by five new object types: dm_xml_application (subtype of dm_folder) 36

37 dm_xml_config (subtype of dm_document, contains configuration information for the application) dm_xml_style_sheet (subtype of dm_document) dm_xml_custom_code (subtype of dm_document, stores custom code for XML processing) dm_xml_zone (subtype of dm_document, stores the names of elements displayed as search zones in a Find dialog) For details of the attributes for these object types, refer to the econtent Server Object Reference Manual. SUMMARY Documentum Foundation Classes (DFC), Documentum Developer Studio (DDS), Web Development Kit (WDK), and XML are powerful options for developing Documentum-based applications. They can be used together or separately, depending on the needs of the application. DFC DFC exposes the Documentum object model as an object-oriented client library. It is leveraged by both client/server architecture such as Desktop Client and web such as WDK. Documentum applications depend heavily on this object model, which is the object-oriented structure by which econtent Server organizes the contents and control mechanisms of econtent Repositories (Docbases). DDS DDS provides the application developer the ability to define application specific data such as custom types, lifecycles, etc. that are utilized in building Documentum applications. In general, DDS only deals with the econtent Repository objects and does not address the business logic or the presentation logic. XML The Documentum platform has rich capabilities for handling XML content (chunking, assembly, zone searching, etc). This is built into our DFC layer and exposed seamlessly to both Web (WDK) and Desktop clients. WDK WDK speeds application development and deployment, reduces the learning curve for development teams, and provides a more immediate return on investment in standard technologies. And, WDK leverages application servers so that they benefit from XML and content management functionality. Reusable components, the building blocks of WDK, facilitate customization of applications within a familiar J2EE-compliant environment. 37

38 Appendix A: List of WDK 4.2 Components browse browserrequirements cancelcheckout checkedoutobjects checkin checkout choose contents copy copylinkmove create import newcabinet newdocument newfolder delete documentlifecycle attach demote detach doattach doresume promote resume suspend edit error export inbox link locations login logout menu move permissions properties renditions search basicsearch advancedsearch 38

39 transform tree vdm addchild cancelcheckout convertvirtual movechild removechild savechanges setbindingrule versions view workflow abort complete createnote deletenote editnote halt insertdoc reassignform resume reviewnotes selectinsertdoc selectnexttasks sendto start status taskinfo taskmanager 39