Developing Web Services with Documentum

Transcription

1 Developing Web Services with Documentum Documentum Technical White Paper September 16, 2002 Erin Samuels Page 1 of 50

2 INTRODUCTION... 4 INDUSTRY MOMENTUM... 4 ABOUT THIS DOCUMENT... 4 THE DOCUMENTUM ECM PLATFORM... 4 WEB SERVICES OVERVIEW... 5 WEB SERVICES DEVELOPMENT... 6 WEB SERVICES AND DOCUMENTUM CONTENT APPLICATIONS... 7 PRESENT DAY ENTERPRISE SYSTEMS... 7 BOF Example... 7 EXTENDING THE REACH OF DOCUMENTUM ECM... 8 Web Services Roles in ECM... 9 EXPOSING CONTENT MANAGEMENT COMPONENTS... 9 Portals... 9 Developers and Architects Corporations INVOKING WEB SERVICES WEB SERVICES AND DOCUMENTUM TODAY Documentum DFC-based Web Services Web Services and Documentum in Production Today DFC 4.x vs DFC 5.x OTHER CONSIDERATIONS FOR DEVELOPING WEB SERVICES BASED APPLICATIONS SESSION MANAGEMENT Overview SECURITY EXAMPLES AND APPENDICES SUMMARY APPENDIX A: GETTING STARTED DEVELOPMENT TOOLS APPENDIX B: INTRODUCTION TO DOCUMENTUM BUSINESS OBJECTS FRAMEWORK Page 2 of 50

3 OVERVIEW BUSINESS OBJECTS IN PERSPECTIVE DOCUMENTUM BUSINESS OBJECTS (DBO) DEFINED APPENDIX C: EXPOSING BOF SERVICES AS WEB SERVICES OVERVIEW CONNECTION SERVICE Functionality Implementation Client DOCBASE SERVICE Functionality Implementation Client INBOX SERVICE Functionality Implementation Client APPENDIX D: USING BOF WITH BEA WEBLOGIC WORKSHOP AND.NET DEFINING THE BOF SERVICE DEFINING THE CONNECTION WEB SERVICE DEFINING THE INBOX WEB SERVICE BUILDING THE INBOX CLIENT APPLICATION USING VB.NET Page 3 of 50

4 Introduction Enterprise Content Management (ECM) is one of the most important technology areas today. Content comes in many forms, but often represents rich business assets, such as contracts, product information, reports that need to flow across both internal and external business systems and delivered in many different ways. ECM is now recognized more as an underlying platform upon which many types of Content Rich Applications are built. For example, e-learning systems, contract management applications, and portal applications are just a few of the types of Content Rich Applications that utilize ECM. Both the importance and usage of content and content management outlines the need for a way to easily integrate content and the content rich services across systems. Web Services provide a standard mechanism for integrating business logic across the Internet. Several leading Documentum customers are using Web Services with the Documentum platform as an integral part of their ECM architectures. Industry Momentum Web Services have gained huge industry momentum, and Documentum is participating with other technology leaders on the development of the standards that form the foundation of Web Services. Documentum is a sponsor of OASIS, a member of W3C, and a member of WS-I and is participating in the Web Services work in these organizations. About this Document This paper outlines usage examples of how you can leverage Web Services as part of your ECM applications and then outlines approaches of creating and invoking Web Services on the Documentum platform. It will begin with a brief introduction to ECM and Web Services. This paper is not designed to be a primer for Web Services, ECM, or Documentum in general. The main sections of this document include: Enterprise Content Management Web Services and Documentum Developing Web Services with Documentum Examples The Documentum ECM Platform The Documentum Enterprise Content Management (ECM) platform is the foundation on which content applications and solutions are built. It is the basis for every information-based project you might be interested in from managing business documents to publishing content on global Web Sites. The Documentum ECM platform provides the core functionality common to each of these deployments. Page 4 of 50

5 Unified content services, our core functionality, refers to not only our robust repository and library services (including security workflow, version control, and so on) but also our more advanced capabilities, such as content intelligence, and rich media management. Figure 1: Documentum ECM Platform Industry Solutions For Documentum developers, this functionality is exposed as a common set of APIs and standards-based components, or Content Applications developer services. Developers can easily leverage this to build customized solutions. A wide variety of content applications are built on Documentum and are designed to Packaged Solutions meet a wide range of business needs. Developer Services Documentum packages its broad set of capabilities into a set of packaged solutions, or Editions, that address specific Unified Content Services content management areas. These packaged solutions provide a convenient way to determine which products you need to meet a particular objective, such as publishing content to the Web, managing rich media, controlling compliance documentation, or enabling enterprise collaboration. To address the business needs in specific industries, Documentum provides industry solutions, which combine Documentum products, partner products, and focused professional services. Web Services Overview As mentioned above, Web Services provide a standard way for integrating and interacting with business logic across the Internet. In essence they provide a mechanism for calling services on remote systems and across applications using standard approaches. The main Web Services standards are Universal Description, Discovery, and Integration (UDDI) for registry and discovery of Web Services, the Simple Object Access Protocol (SOAP) for invocation of and communication between Web Services and Web Services Description Language (WSDL) for describing the service interfaces and bindings. Figure 2 shows how Web Services flow through a continuous cycle. Figure 2: Web Services Cycle Service Registry Find Publish Service Requestor Bind Service Provider Page 5 of 50

6 The current generally accepted implementation of a Web Services contract is defined using WSDL; published in a service registry (UDDI); and invoked over HTTP using SOAP, using XML as the format for data transmission. Web Services Development Web Services can be created through a number of methods. In general, the key steps involved in Web Services development are: 1. Creating a Web Service Services can be implemented in any programming language and can be deployed on any platform, such as Windows, UNIX, and Mainframes, as long as it is network accessible. Technically, Web Services are generally a higher-level function/service that performs certain business logic. There is generally some type of interface wrapper that binds it to a particular invocation/communication protocol - this is normally SOAP. They are not normally lowlevel APIs as this would be too chatty. Web Services can be created by encapsulating calls to existing APIs. They can be written in any in any language, but generally implemented in Java as J2EE classes, servlets, or EJBs on the back end. On Microsoft.NET platforms, C#, VB.NET and other languages can be used. There are a number of SOAP toolkits that will allow you to automatically create the SOAP server stubs from EJBs, Java classes, and other programs. These toolkits will often also automatically create a WSDL file to describe your Web Service interface. Toolkits generally have some limitations on what interfaces they can automatically create - but you can also easily write the SOAP binding yourself. 2. Deploy and Publish Web Service Web Services are generally deployed on an application server. The WSDL file can then be published in a UDDI registry (either private or public) to allow discovery of the Web Service. However, publishing could be much simpler. For example, ing the WSDL file or documenting in a manual and so forth. 3. Find and Bind to a Web Service There are two ways to find and bind to a Web Service. Early Binding is when you determine the location of the service at development time. Dynamic Binding is when locating the service is performed just before or at the time the function is called. Web Services defines the UDDI, a Universal Description, Discovery, and Location specification, as the preferred mechanism to dynamically locate and advertise services at run time. Either mechanism will work with Web Services that access Documentum components. Many of the development tools today like, Visual Basic.NET, are WSDL aware. They can use the information in a WSDL file to display lists of functions and their signatures to programmers and automatically create the client stubs to invoke and call the SOAP interface. Page 6 of 50

7 More information on Web Services can be found at: Web Services and Documentum Content Applications Technically, Web Services are a way of calling functions on other computers across the intranet, Internet, or World Wide Web. Web Services have remote benefits, but also have interapplication benefits. For example, a CRM system can communicate with Documentum through Web Services. Web Services provides a mechanism to access to the Content Server remotely through the Web. For Documentum customers, this means broader, industry standard access to content management functionality. Present Day Enterprise Systems Most present day enterprise systems are based on variations of a 3-tier model. The first tier, called the presentation layer, is responsible for user interface. It presents to the users the data from the third tier (data layer) and gathers input from the users. The second tier, called the business logic layer, implements the rules of the enterprise. It is a middle-tier that supplies data from the data layer tier to the presentation layer and dispatches the data gathered by the presentation layer to the data layer. The third tier, called the data tier is implemented by the Documentum Content Server and its underlying RDBMS. Web Services are a suite of technologies that is designed for client-to-middle-tier communication of function requests. The middle tier will implement business rules as to the limitations and filters required for accessing the Content Server on behalf of its clients. Therefore, to overcome the technical and logistical issues related to remote clients, a Web Services layer could be developed to dispatch outside requests to Documentum middle-tier services, which provide stateless content management functionality with the Content Server and the implementation of business rules. The release of Documentum 5 provides a framework to develop Documentum middle-tier services, called Documentum Business Objects Framework (BOF) and is described in the Introduction to Business Objects Framework appendix. BOF provides an environment that makes it easier to develop business layer objects that can be called through Web Services. When the service executes it executes on the server and not on the client. In a content management environment, like Documentum, the services are located in proximity to the content management servers in order to provide good performance to the service operations. BOF Example For example, a BOF service could advertise its location so it can be found from remote locations across the Internet. One Web Services standard component, UDDI, provides the ability to register a service for discovery. Once the remote computer locates where the service is using UDDI, it then needs to send a remote function call to the service. Calling a function to execute Page 7 of 50

8 on a remote computer involves sending parameters and retrieving results from the remote function. Web Services uses a new HTTP over XML protocol called SOAP (Simple Object Access Protocol). Unlike the binary protocols used with RPC and RMI, which are also remote function calling protocols, SOAP uses XML and HTTP to transfer parameters and return results in the form of SOAP Envelopes. The SOAP Envelopes were designed so that they can even carry content, like other XML files and binary Word documents, Pictures, etc. Extending the Reach of Documentum ECM Web Services extend the reach of the Documentum Enterprise Content Management platform. Enterprise content management applications clearly demonstrate the benefits of the Web Services infrastructure. The details of development and deployment of Web Services on the Documentum platform will be provided in the "Appendix B: Introduction to Documentum Business Objects Framework" section. This section provides a general overview of how Web Services will be used in combination with Enterprise Content Management. Web Services continues to gather momentum and is rapidly becoming an invaluable part of the software industry. The vast deployment of robust Internet, intranet, and portal applications across the enterprise intensifies the need for alternative delivery mechanisms in addition to the ability to handle any type of content format. No matter what it is or where it must go, content must get distributed quickly, easily, and often with as little human intervention as possible. Combining the flexible capabilities of Web Services with the powerful Documentum enterprise content management platform allows for content control in this new distributed environment while providing a whole solution that is compliant to industry standards. As we have seen, enterprise content management is a broad area that deals with the aggregation, creation, management, and distribution of content assets. Content flows across systems and enterprise boundaries, as shown in Figure 3. Figure 3: Content Flow within Web Services.NET Application (Thick Client) SOAP Client Adapter Web Service to to Business Object SOAP Web Server Browser JSP SOAP Client SOAP DBOF Business Object (Service) DFC Content Repository } Application Server Calls out out to to a Web Service Page 8 of 50

9 Web Services Roles in ECM The various applications of content management involve the combination of business logic and content. There are two main roles for using Web Services with enterprise content management: Exposing and publishing content management services as Web Services Invoking Web Services as part of content management applications For each of these roles, Web Services may be accessed at multiple levels, either within an enterprise, across the extended enterprise with partners and suppliers or as generally accessible Web Services over the Internet. Generally, most enterprises will not freely publish their core content management services over the Internet unless that is their actual business model, but will leverage services to rapidly integrate their applications across enterprise systems, and extend functionality to their extended enterprise (customers, partners, suppliers) where appropriate. As Web Services become more the norm for software deployment and services (e.g., pay-per-usage models), corporations will begin to leverage external services for components of their applications. Exposing Content Management Components Business logic encapsulated in core components can be exposed as Web Services to provide access through other applications (portals, enterprise applications, and external systems) and to rapidly build new applications by leveraging core services of the content management system - reducing overall costs and deployment time for organizations. Web Services will become a natural mechanism for integrating content management across systems, e.g., CRM, ERP, and portals. Vendors of these products will generally provide the integrations, which are key across the e-business stack, and companies nowadays are pushing for tighter, more complete integration out of the box. Portals The portal is one very good example of exposing content management components. The enterprise portal is becoming the dashboard of the enterprise. Companies no longer want to deal with multiple application front-end interfaces for their employees. Content management is central to a portal in two respects: 1. Enabling employees, partners, and customers to participate in content management applications through one seamless interface 2. Powering portals with accurate content Exposing enterprise content management components as services enables portal builders to rapidly include content management capabilities in the various enterprise portals. This can be accomplished in two ways: Using Web Services below the Portlet UI to call to functions in the Content Management System Page 9 of 50

10 Expose Portlets themselves (UI and Business Logic) as Web Services. The WSRP (Web Services for Remote Portlets) technical committee in OASIS is working on a standard for this approach. Exposing these Portlets as Web Services allows for more intelligence within the portal. Instead of having multiple disconnected components, the components can interact through the published interface. For example, for a customer service portal, a sales support person may look up a customer name through a Portlet into the CRM system, while the browse Portlet to the content management system automatically updates the contract view to show contracts just for that customer. Developers and Architects Developers and architects will also leverage core services of the enterprise content management platform to build content management applications more rapidly, and will develop their own applications as services that their customers can readily use within the enterprise. For example, a number of companies develop content management- based applications using Documentum as the foundation, e.g. contract and catalog management systems. These vendors will use the core services of the platform to rapidly build and get their products and services to market faster. They may want to expose their applications as higher level services to include, for example, contract management as part of an e-procurement system, or for market site providers to easily add catalog management and aggregation for their suppliers. Corporations Corporations will also build Web Services to expose their in-house applications both within the enterprise and to external partners. Exposing services will be done using standard interfaces, such as a RosettaNet Partner Interface Processes (PIPs), or by agreed-upon interfaces between partners. One of the PIPS (2A9) is a good example of a content-based service that would be exposed by a corporation to their partners. This PIP is used in the semi-conductor industry and allows for companies to search across partners for information on available components that meet certain criteria. Another example might be a financial services company that would like to provide a new offering to some of its value-added customers by providing access from their portal to certain subscribed research reports. Invoking Web Services Content applications can also invoke Web Services to extend functionality. For example, Documentum has many third-party technology providers who provide complimentary technology, e.g., translation software, and transformation technology. These third parties will be able to expose and publish their components as services so they can be easily plugged into customers' systems either run remotely by the third party or installed at the customer's site. One example could be transformation. Different third parties might offer services for XML to PDF transformation, GIF to JPEG, or even more complex transformation services such as from one catalog schema to another, e.g., RosettaNet to XCBL. Customers could either search for companies that offer these services using a service registry or they could tell the system that they Page 10 of 50

11 would like this particular document transformed from X to Y and it would automatically find a service that offers this and invoke the transformation. Web Services and Documentum Today Documentum provides a rich open platform that enables you to leverage Web Services today. One of the key differentiators for Documentum is our rich platform API that enables you to create your own services on our platform. Our Business Process Automation services and extensibility of our platform allow you to use external Web Services to extend the content management services to meet your needs. Documentum allows you to work with your preferred development environments, toolkits, and application servers for working with Web Services. In the reference section, we provide references to some of the available toolkits for Web Services and also in our examples we show the use of a few different development environments (.NET and J2EE based). One of the important aspects of Web Services is the ability to encapsulate your business logic in your services - Web Services are only as good as the service they provide. In Documentum 5 we concentrated on addressing this and have added the Documentum Business Object Framework that allows you to easily add your own business logic and services to our platform. Please refer to Appendix B: Introduction to Documentum Business Objects Framework for more information. In Documentum you will develop your Web Services over our API. You can use any development environment to do this. You can expose your Web Services in a UDDI registry and create a WSDL file if you choose. Your Web Services will be deployed on a web server. These will generally be accessed using SOAP. A Web Services client can be any networked client - a desktop application calling Documentum backend over the web, a web application or portal, or even another Web Service or remote client/system. Lets take a closer look at the Documentum Architecture for Web Services. Figure 4 shows three layers for Web Services: Page 11 of 50

12 Figure 4: Three Layers of Web Services Developing Web Services WSDL SOAP/Java Stub Business Logic Here Apache BEA Microsoft IBM Oracle Sun Web Services Server Stub Web Services Compatible Layer DFC 4.x DFC 5.x Content Repository Web Services Development Tools Business Logic Here 1. The first layer is DFC 4.x or DFC 5.x. DFC provides a rich API to develop a Web Service and is described in more detail in the Documentum DFC-based Web Services section. 2. The next layer is the actual implementation of your service. In Documentum 4.x, this will contain the business logic of your service implemented using DFC. In Documentum 5.x this layer will be very thin, if present at all, because Documentum 5 allows you to encapsulate business logic using the new Business Object Framework. 3. The third layer is the actual binding of your service to SOAP, and the WSDL interfaces. As we already mentioned there are many toolkits that provide the ability to automatically create the SOAP server stubs and WSDL files. Some of these are listed in the upper layer of the diagram. Documentum DFC-based Web Services Ideally, you will have well encapsulated business logic within your organization that you would like to expose through Web Services. Regardless of the size or complexity of the business logic, content management Web Services should be written using DFC. Figure 5: DFC Architecture provides a detailed look at the DFC architecture. Page 12 of 50

13 Figure 5: DFC Architecture DFC Extensions Type-based Business Objects Other Business Objects Your Business Objects Documentum Sample Objs Intrinsic Business Objects Future Intrinsic Objects Operations Query Builder Workflow Validation Virtual Document Core DFC Layer Object oriented access to Server API Layer DBO Framework fc.client DFC to Server Access Layer (Object-based access to Server API) Core DFC Layer Object oriented access to Server API Layer DBO Framework Session Manager Session Pool fc.client BO Registry (DBOR) Session Manager Cache The DFC provides a rich set of classes and interfaces that establishes an object-oriented framework and API with which to perform Documentum Repository operations. You can use DFC in any of the following ways: Access Documentum functionality from within one of your company s enterprise applications. For example, your corporate purchasing application can retrieve a contract from your Documentum system. Customize or extend Documentum products like Documentum Desktop or WDK. For example, you can modify the Documentum Desktop functionality to implement one of your company s business rules. Write a method or procedure for Content Server to execute as part of a workflow or document lifecycle. For example, the procedure that runs when you promote an XML document might apply a transform to it and start a workflow to subject the transformed document to a predefined business process. The Documentum Content Server Fundamentals manual provides a conceptual explanation of the capabilities of Content Server and how they work. DFC provides a framework for accessing those capabilities. Using this framework makes your code much more likely to survive future architectural changes in the Documentum system. The core of DFC is a set of Java classes, but it includes other elements as well: Page 13 of 50

14 A collection of DLLs to provide the DFC functionality. A type library for accessing DFC via COM from Visual Basic or Visual C++. A set of C++ wrapper classes that hide many details of the DFC/COM interface when you access DFC through the Microsoft foundation classes (MFC) framework. Whenever writing programs that access the Documentum Repository, the best approach is to use Documentum DFC. This API provides an object-oriented framework for programmatic access and control of content. DFC encapsulates and abstracts the features and details of advanced session management, transaction processing, XML parsing and transformation, and a myriad of necessary features described in the official DFC documentation. Web Services and Documentum in Production Today Many of Documentum s leading customers are leveraging Web Services with Documentum today. These customers have developed these services using Documentum 4.x. Currently the applications of Web Services we have seen across the customer base are leveraging Web Services internally as a core part of their architectures. These applications bridge the interaction between end user desktops and portal applications with the Documentum content management system running on the server. For example, one of our customers is currently providing a comprehensive set of Documentum operations to their users through a SOAP aware client application. EJBs were developed that wrap some of the most common content management operations. This application provides their end-users with a rich desktop experience without Documentum code running on the client machine. Another benefit of this approach is that, because many of their users are in remote locations all over the world, this enables remote users to more easily interact with the content management system. The end user client actually consists of customizations to Microsoft Word and other Visual Basic clients that use SOAP to interact with the Documentum system running on the application server. Figure 6: Production Documentum Web Services Application COM Client SOAP SOAP Web Server EJB DFC Content Repository In this application, a standalone program performs a Content Repository (Docbase) operation with the help of a Web Service, which follows the following execution process: Page 14 of 50

15 1. A standalone client application calls a service method through a local SOAP client request interface. 2. The SOAP client wraps these calls into a SOAP Message. 3. The SOAP Message is sent to the Web Service interface and the SOAP Message is unpacked. 4. The Web Service calls the associated server method with the parameters extracted from the SOAP Envelope. 5. The method performs any necessary Documentum Repository processing and passes the results back to the Web Service. 6. The Web Service wraps the results into another SOAP Message and sends the results back to the client. 7. The client presents the response to the user. Examples of the services created are as follows: Service Session oriented services Basic Library services Query services Business Policy services Workflow services Security services Business specific services Description of Service Methods Log in, log out, etc. Check in, check out, import, export, etc. Basic and Advanced searching using DQL Promote, demote, suspend, resume Start workflow, halt workflow, send to distribution list, get task, reassign task, etc. User and group administration Methods that automate their business processes This is just an example of one of many possible applications of Web Services on the Documentum Platform. We have not yet begun to fully realize the true potential of this powerful combination. DFC 4.x vs DFC 5.x Documentum 5 introduces the Business Objects Framework. In the example above, the customer leveraged EJBs to create their services using the library service API in DFC 4.x. In 5.x, it is now possible to encapsulate the business logic at a lower level within the DFC using the BOF. The BOF also provides more advanced session management and transaction processing. For example, a BOF service can perform cross-docbase queries previously not available. Another feature of BOF is the support for cross-docbase transaction processing. This allows a single managed transaction to be started on several Docbases and committed or rolled back if needed. Therefore, with Documentum 5, it has become easier to add business objects to content applications and access them through Web Services. Page 15 of 50

16 Some of the advantages of DFC 5 version over DFC 4.2 for Web Services are the following: A BOF service implemented with DFC 5 conceptually and logically matches a Web Service: Both represent a functional component of server side business logic. To expose a BOF service as a Web Service only a thin wrapper is required to adapt to the Web Service runtime environment. BOF 5 provides a session manager that optimizes the session resource utilization for connection oriented Web Services. BOF allows the reuse of business logic more easily because it requires a standardization of how to represent business logic. The approach is the same as when trying to represent business logic as a Web Service. Existing BOF services can be exposed as Web Services. The Documentum Business Object Registry (DBOR) allows dynamic changing of the implementation of a service by configuration. Using BOF enables special applications, such as JSP applications that are not Web Services enabled (and where Web Services are not efficient), to use the same business logic components. DFC 5 has a new logging mechanism that enables application specific logging in an application server. See "Appendix B: Introduction to Documentum Business Objects Framework" for a more detailed description of BOF. Other Considerations for developing Web Services based applications Programming with Web Services opens up some new challenges and considerations that current Documentum developers may wish to keep in mind. Below we describe some important topics such as how to approach session management when working with Web Services, security, and developing with EJBs. Session management Overview To be able to use Web Services with Documentum, some kind of session management is required. Session management is mainly used for performance reasons. In an application based on Web Services typically the following happens: 1. Start application 2. Login 3. Send a series of requests with corresponding results 4. Disconnect Page 16 of 50

17 5. Stop application This means that once the user is logged in the application logic would like to be able to use a session until the user disconnects. It would not be practical to have the user log in for every request. Even worse, it would not be practical to not to use user authentication at all as a means of solving this login dilemma. There are several possible solutions listed below, each with pros and cons. The Session Manager is provided as a mechanism to solve this issue. Authenticate with every message The client application could store the user name and password and pass this information into every service message. Advantages: Truly stateless Never times out Disadvantages: Potential security hole since every message contains user name and password (just capture one message and you have full access) Requires special logic on client side to cache user name and password and to pack it into every single message Web Service has to connect to the Docbase with every message (expensive operation) This approach may work well when there are only very few messages sent to the server. For example, a user wants to upload something and then disconnect. Otherwise, it is not recommended to use this approach mainly for security and performance reasons. Ticketed Login Documentum servers can generate a temporary password called a ticket which can be used only once. This can be generated only for super users and every user currently logged in, allowing the super user (or a service connected as a super user) to act as a proxy for the specified user. The approach used here is that when the first SOAP message is sent the message contains normal user name and password provided by the user. When the first service call is made, the service requests that the server generates a login ticket and sends it back with the result message. The client then retrieves the ticket from the response and uses it in lieu of the password when establishing a new session with the Repository. Advantages: Better security than sending plain password because a ticket can only be used once. Disadvantages Ticket times out Pollutes request and response message (could be fixed by passing ticket in the SOAP header) Page 17 of 50

18 Web Service has to connect to the Docbase with every message (time expensive operation) Connecting with Session Manager When the application is started, a connection with the Web Service is established. This connection is identified by an ID. This ID could use the standard HTTP cookie mechanism and is supported by several SOAP toolkits. The connection ID could also be passed along with the message. On the application server side, the Documentum BOF session manager can be associated with the connection. For every request, the session pooling capabilities of the session manager could be used. This means the Documentum session is cached and reused for requests that follow shortly one after the other, even if the session is specifically released. These pooled sessions are dynamically released when no messages come in for a while. Advantages: User name and password is sent once and then the connection ID is used. Optimized performance. Messages are not impacted when using the session mechanism of the SOAP toolkit. Disadvantages: Connection may time out (but is configurable) Lose statelessness With Documentum 5 the session manager provides additional scalability that releases sessions not used for a while and caches sessions where required. With Documentum 4.2 a connectionoriented approach was supported but the programming model was dependant on the session pooling settings - either the Docbase session was released at the end of the program only once, or it is released after every service call. EJB Environment Web Service Toolkits like BEA Workshop are based on an EJB environment. Web Services are implemented using stateless session beans. The current version of BOF does not yet fully support this environment but can use a stateful session bean to cache the identity information between service calls. This means the user name and password are stored in an EJB when the connection is established. When a Web Service is invoked the EJB that runs the call requests the user name and password from the session bean and connects to the Documentum server. When the call is done it disconnects and sends back the result. Advantages: User name and password is sent once and then the connection ID is used Fully supports EJB clustering (load balancing, recovery etc.) Can use advanced toolkits like BEA workshop Page 18 of 50

19 Disadvantages: Web Service must connect to the Docbase with every message (expensive operation) An EJB enabled version of the session manager will be provided in the future to provide session caching. The question here is to find the right balance between clustering with load distribution and session caching. Both mechanisms provide some kind of scalability with different means. When using a cluster, what is important is the kind of clustering strategy used: round robin for every session vs. random distribution vs. round robin with each call. Security Web Services as implemented by major vendors like Microsoft or BEA are not very secure by nature. When using Web Services with Documentum these fundamental security problems still exist but no additional security holes are opened. This means when using Web Services with Documentum, standard security holes of using Web Services exist but once Web Services security gets enhanced a Documentum solution would benefit from this as well. The security problems currently known with Web Services are: Authentication requires sending of user name and password along with the SOAP message SOAP messages are not encrypted unless sent to an SSL port May use HTTPS protocol but weak links still remain after the message has reached the server or client Secure Web Services are not the reality yet but major vendors and different committees like OASIS are working on it today. Examples and Appendices So far we have given you a fairly high level introduction into Web Services and how they are supported and developed with Documentum. We have included in the appendix several references, and working samples that will clarify in more detail what we have been discussing. Appendix A: Getting Started Development T: provides references to toolkits and development environments for working with Web Services. Appendix B: Introduction to Documentum Business Objects Framework: Provides a more detailed introduction to Business Objects. Appendix C: Exposing BOF Services as Web Services: Uses the Apache AXIS toolkit to demonstrate how to build the SOAP and WSDL elements. Appendix D: Using BOF with BEA WebLogic Workshop and.net: Demonstrates how to expose a BOF service as a Web Service using BEA WebLogic Workshop and how the new Web Service can be accessed from a.net client. The example code exposes a Documentum inbox as a Web Service using the Apache Axis toolkit. The JWS mechanism is used that provides the thin wrapper between a BOF service and Page 19 of 50

20 the Axis runtime environment. It also registers the service automatically and a WSDL representation of the service can be generated automatically from the JWS file. Additionally, a sample VB.NET project is provided that implements a Windows based simple inbox tool. A user can display and remove inbox items. Summary Web Services extends the reach of the Documentum Content Management platform by making the content management services available across the Internet and providing a vehicle for application-to-application communication with little or no human intervention. Why is Documentum the preferred platform for building Content Applications? Here are just a few reasons: Experience Scalable Proven Platform Rich Set of Content Management Services Open Platform and Development Environment Technology Leadership in XML Full set of Partners Documentum clearly understands the importance of Web Services and the application of Web Services to Content Management. Documentum is playing a leading role participating in the development of the standards that will shape the future and application of Web Services. We will be continuing to address support of Web Services in the Documentum platform. As we have illustrated in this paper, Documentum today provides a rich open platform that enables our customers to fully leverage Web Services. In Documentum 5 we have addressed the fundamental requirement of Web Services by allowing our customers to easily encapsulate their business logic in the core platform. Moving forward Documentum will provide some out of the box services and will continue to allow our customers to develop and leverage our open platform. Page 20 of 50

21 Appendix A: Getting Started Development Tools Development tools are rapidly becoming available from IDE or application server vendors. Some of the tools, such as Sun's JWSDP, are free to developers. Others are available free to developers for a trial period. These tools can be easy to use, but are not always flexible. You are not restricted to the development environment. A service can be generated in Java, C++, C#, Visual Basic.NET, or any other language. Some of these development environments provide better assistance with the development process. For example, Sun s Forte' IDE provides the ability to debug EJBs on an application server. Each vendor has its own area of strengths to offer to the developer. Others, like Visual Studio.NET, provide different methods of assisting the developer with deploying and testing the generated service. In general, there are two approaches to development of a Web Service, using an Integrated Development Environment (IDE) or using raw Web Services compliant development libraries. Some of the currently available Web Services development tools are as follows: Apache Axis: BEA BEA WebLogic Workshop: Microsoft Visual Studio.NET: IBM Web Services Toolkit: Oracle Oracle9i JDeveloper: Sun Java Web Services Developer Pack (JWSDP): Many of these tools have comprehensive tutorials, which are extremely beneficial in getting a base understanding of Web Services development. Some Web Services require an application server or servlet container. If you do not have access to an application server, download and install the Apache Tomcat Servlet container. Tomcat is free and can be found at: If you choose to use JWSDP as your development tool, a copy of Tomcat is provided as part of the installation of the tool. There are also tools to develop raw SOAP, WSDL, and UDDI. This approach can be more flexible, but more code is often required. So it is important to choose a tool that you are comfortable using. Page 21 of 50

22 Appendix B: Introduction to Documentum Business Objects Framework The Documentum Business Objects Framework (BOF), new with DFC 5, provides an object oriented framework for building, testing, discovering, and deploying business logic as Business Objects. Overview BOF is part of the DFC library and consists of several Java classes and interfaces for constructing and running Documentum Business Objects (DBO). There are two types of Documentum Business Objects, type-based business objects, and service-based business objects. A type-based business object can extend a Documentum Server persistent object type (e.g. "com_accelera_catalog" or "com_accelera_autonumber" might extend "dm_document") and extend its capabilities by providing new methods for those types (actually, new user defined Java classes) and allowing overriding of existing methods, like checkin() and checkout(). A service-based business object provides methods that perform more generalized procedures that are not usually bound to a specific object type or even Docbase. The specific business logic within the business objects is implemented using the standard DFC framework allowing developers to implement a new DBO without a steep learning curve. Since BOF objects are based on the Documentum Foundation Classes (DFC), the developer can maintain a high degree of compatibility with existing DFC applications. Figure 7: DFC Provides DBO Framework Service-based Business Objects Other Bus. Obj. Your Bus. Obj. Services Services DCTM Sample Services ISubscription Services Workflow Services DFC Extensions Type-based Business Objects Other Business Objects Your Business Objects Documentum Sample Objs Documentum Foundation Classes (DFC) Intrinsic Business Objects Future Intrinsic Objects Operations Query Builder Workflow Validation Virtual Document Core DFC Layer Object oriented access to Server API Layer DBO Framework fc.client Business Objects High-Level Services Layer Low-Level DFC to Server Access Layer (Object-based access to Server API) Server Access Page 22 of 50

23 Business Objects in Perspective A typical content rich Documentum application will be logically partitioned into layers also referred to as "tiers". Each tier has a different responsibility in the overall deployment, and within each tier, there can be one or more parts. The three main layers in an n-tier model are the Presentation Layer, the Business Logic Layer, and the Data Layer. Figure 8: Documentum Business Objects N-Tier Model Presentation Layer Generic Components Custom Components Industry / Company specific behavior Business Logic Layer Application Specific Abstraction Business Rules and Policies Common Object Model Data Layer Content and Data Schema Content Object Hierarchy Aggregated Business Data Common Schema Core Content Management Services Library Services Process Automation Content Authentication Presentation Layer The presentation layer contains components dealing with user interfaces and user interaction. It is used to display content and structured information in a web browser or stand alone application. For example, the presentation layer of a stand alone application could be written in Visual Basic or Java Swing. In a web environment, Documentum WDK would be the choice to present the layout and to manage the flow and sequence of user interactions. The presentation layer consists of commercial or custom UI components that display information in different ways depending on such factors as the user role or their privileges. For most implementations, this layer is highly customized and must be very configurable. The presentation layer relies on the components (business objects) of the business logic layer to implement and enforce the rules and policies of the company. Business Logic Layer The business logic layer is completely independent of visualization and of the toolkit used to display information. It provides application specific generalization as a layer of abstraction Page 23 of 50

24 and implements the customer specific business rules and policies. It is based on a component object model with components shared between different application areas. In most cases, the policies and procedures of a given company are not very likely to change greatly so the business object components implement those policies and procedures. Alternatively, if a policy or procedure does change, the implementer can just modify the corresponding business logic component and all the dependent applications and components will automatically conform to the new policy. One of the major improvements of Document 5 is the ability to support both stateful and stateless Docbase sessions. This allows the business object to focus on the business rules and to leave the session management and transaction handling to the framework. Data Layer The data layer is used by the business logic layer to permanently store the state of the objects, content, and other information. Central to the data layer is one or more data servers that house the stored state. The Documentum implementation of the data layer is comprised of one or more Content Servers with their associated RDBMS servers. The data layer is logically separated into two useful parts, the Content and Schema Layer and the Core Content Management Services Layer. Content and Data Schema Layer The data schema layer defines the content object hierarchy as well as the physical schema used to store the aggregated business data. Creation and management of the schema can be achieved using the Documentum Administrator utility or directly by using DFC calls. The business objects in the business object layer provide a logical abstraction of the details of the DFC interfaces to the content and data schema. Therefore, the business objects can manipulate content and its metadata on behalf of the presentation layer applications without relying on those applications being aware of how the data and content is physically organized. Separation of the schema from the business logic layer and the database layer promotes the ability to scale to a different database and continue to use the business objects and applications unmodified. Core Content Management Services Layer The core content management services layer provides the library services, process automation, and content authentication to the business objects. This layer is implemented by the Documentum Content Server. It provides the basic building blocks to construct higherlevel business logic components. Documentum Business Objects (DBO) Defined Documentum Business Objects are designed to provide modular business logic to the presentation layer by hiding the underlying Docbase schema and by using the core services of the Documentum Content Server. DBOs are either type-based or service based: Page 24 of 50

25 Type Based Objects (TBO) Type based objects are implemented as classes that extend basic persistent DFC types such as DfDocument, DfSysObject, DfPersistentObject, DfFolder, etc. They allow you to encapsulate business logic that is specific to a particular Docbase object type. There are two main reasons for creating a TBO: 1. To provide a new behavior for existing or new object types. For instance, a developer may decide to add getter and setter methods for object specific attributes or add new methods like adding a Product to a Catalog TBO. 2. Customizing low-level operations to enforce data validations, referential integrity and object specific business rules. For instance, a developer may decide to override the save() and checkin() methods to be able to validate data before saving them in the persistent storage. Service Based Objects (SBO) Service based objects are not tied to a specific Documentum object type. They are generalized objects that provide a specific service that may operate on different Documentum object types or other business objects. An example of a service-based object is the Documentum IInbox service that retrieves items from a user's inbox and may also perform a number of other operations such as remove item, forward item, etc. Such an object would not be tied to a specific object type. Your SBOs are built using public BOF interfaces and implementation classes supplied by DFC. Service and session manager factory methods are also provided by DFC. Page 25 of 50