Developing Web Services with Documentum

(1)

Developing Web Services with

Documentum

Documentum Technical White Paper

September 16, 2002

Erin Samuels

(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 ... 10

Corporations ... 10

INVOKING WEB SERVICES... 10

WEB SERVICES AND DOCUMENTUM TODAY... 11

Documentum DFC-based Web Services ... 12

Web Services and Documentum in Production Today ... 14

DFC 4.x vs DFC 5.x ... 15

OTHER CONSIDERATIONS FOR DEVELOPING WEB SERVICES BASED APPLICATIONS ... 16

SESSION MANAGEMENT... 16

Overview... 16

SECURITY... 19

EXAMPLES AND APPENDICES ... 19

SUMMARY ... 20

APPENDIX A: GETTING STARTED –DEVELOPMENT TOOLS ... 21

APPENDIX B: INTRODUCTION TO DOCUMENTUM BUSINESS OBJECTS FRAMEWORK... 22

(3)

OVERVIEW... 22

BUSINESS OBJECTS IN PERSPECTIVE... 23

DOCUMENTUM BUSINESS OBJECTS (DBO) DEFINED... 24

APPENDIX C: EXPOSING BOF SERVICES AS WEB SERVICES ... 26

OVERVIEW... 26

CONNECTION SERVICE... 27

Functionality ... 27

Implementation... 27

Client ... 28

DOCBASE SERVICE... 29

Client ... 31

INBOX SERVICE... 31

Client ... 32

APPENDIX D: USING BOF WITH BEA WEBLOGIC WORKSHOP AND .NET... 33

DEFINING THE BOF SERVICE... 33

DEFINING THE “CONNECTION” WEB SERVICE... 33

DEFINING THE “INBOX” WEB SERVICE... 36

(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.

(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

For Documentum developers, this functionality is exposed as a common set of APIs and standards-based components, or

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 meet a wide range of business needs.

Documentum packages its broad set of capabilities into a set of packaged solutions, or Editions, that address specific 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.

Content Applications

Packaged Solutions Developer Services

Unified Content Services Industry Solutions Content Applications

Packaged Solutions Developer Services

Unified Content Services Industry Solutions

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 Service Registry Service Requestor Service

Requestor _ProviderService Service Provider Bind Pu bli_sh Find Service Registry Service Registry Service Requestor Service

Requestor _ProviderService Service Provider Bind Pu bli_sh Find

(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 low-level 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, emailing 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

(7)

More information on Web Services can be found at:

• www.webservices.org • www.uddi.org

• www.oasis.org

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

inter-application 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

(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

Content Repository Content Repository DFC Web Server D B O F Business Object (Service) Business Object (Service) Adapter Web Service to Business Object Adapter Web Service to Business Object .NET Application (Thick Client) SOAP Client JSP SOAP Client Browser SOAP SO AP

}

Appl

icati

on

Se

rv

er

Calls out to a Web Service

Calls out to a Web Service Content Repository Content Repository DFC Web Server D B O F Business Object (Service) Business Object (Service) Adapter Web Service to Business Object Adapter Web Service to Business Object .NET Application (Thick Client) SOAP Client JSP SOAP Client Browser SOAP SO AP

}

Appl

icati

on

Se

rv

er

Calls out to a Web Service

(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 exposingcontent 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

(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

(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:

(12)

Figure 4: Three Layers of Web Services

Web Services Compatible Layer

Content Repository

Content Repository DFC 4.x

Web Services Server Stub

Developing Web Services 1. WSDL 2. SOAP/Java Stub Developing Web Services 1. WSDL 2. SOAP/Java Stub DFC 5.x Business Logic Here Business

Logic Here _Business

Logic Here Business Logic Here

Apache BEA Microsoft IBM Oracle Sun

Web Services Development Tools Web Services Development Tools

Web Services Compatible Layer

Content Repository

Content Repository DFC 4.x

Web Services Server Stub

Developing Web Services 1. WSDL 2. SOAP/Java Stub Developing Web Services 1. WSDL 2. SOAP/Java Stub DFC 5.x Business Logic Here Business

Logic Here _Business

Logic Here Business Logic Here

Apache BEA Microsoft IBM Oracle Sun

Web Services Development Tools Web Services Development Tools

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.

(13)

Figure 5: DFC Architecture

DFC to Server Access Layer

(Object-based access to Server API)

Type-based Business Objects

Core DFC Layer– Object oriented access to Server API Layer

Workflow Validation Virtual Document Query Builder Operations fc.client DBO Framework DBO Framework Documentum Sample Objs Documentum Sample Objs Your Business Objects Your Business Objects Other Business Objects Other Business Objects DFC Extensions Intrinsic Business Objects

fc.client DBO Framework

DBO Framework Session Manager_{Session Manager}

BO Registry (DBOR) BO Registry (DBOR) Session Pool

Session Pool

Session Manager Cache Session Manager Cache

Future Intrinsic Objects Future Intrinsic Objects

(Object-based access to Server API)

Type-based Business Objects

Workflow Validation Virtual Document Query Builder Operations fc.client DBO Framework DBO Framework Documentum Sample Objs Documentum Sample Objs Your Business Objects Your Business Objects Other Business Objects Other Business Objects DFC Extensions Intrinsic Business Objects

fc.client DBO Framework

DBO Framework Session Manager_{Session Manager}

BO Registry (DBOR) BO Registry (DBOR) Session Pool

Session Pool

Session Manager Cache 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.

(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

Client

COM

SOAP

Web Server

SOAP

EJB

DFC

Content Repository

Client

COM

SOAP

Web Server

SOAP

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:

(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 Description of Service Methods

Session oriented services Log in, log out, etc.

Basic Library services Check in, check out, import, export, etc. Query services Basic and Advanced searching using DQL Business Policy services Promote, demote, suspend, resume

Workflow services Start workflow, halt workflow, send to distribution list, get task, reassign task, etc.

Security services User and group administration

Business specific services 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

(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

(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)

(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 connection-oriented 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.)

(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

(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

(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:http://xml.apache.org/axis/index.html • BEA – BEA WebLogic Workshop:

http://www.bea.com/products/weblogic/workshop/index.shtml

• Microsoft – Visual Studio.NET:http://msdn.microsoft.com/vstudio/default.asp

• IBM – Web Services Toolkit:http://www.alphaworks.ibm.com/tech/webservicestoolkit

• Oracle – Oracle9i JDeveloper:

http://www.oracle.com/ip/develop/ids/index.html?websvcs.html

• Sun –Java Web Services Developer Pack (JWSDP): http://java.sun.com/webservices/webservicespack.html)

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:

http://java.sun.com/products/jsp/tomcat/. 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.

(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

(Object-based access to Server API) Type-based

Business Objects

Workflow Validation Virtual Document Query Builder Operations High-Level Services Layer Low-Level Server Access fc.client DBO Framework DBO Framework Documentum Sample Objs Documentum Sample Objs Your Business Objects Your Business Objects Other Business Objects Other Business Objects

Service-based Business Objects

DCTM Sample Services DCTM Sample

Services Your Bus. Obj.

Services Other Bus. Obj.

Services

DFC Extensions

Documentum Foundation Classes (DFC) Business Objects Intrinsic Business Objects Workflow Services Workflow Services ISubscription Services ISubscription Services

(Object-based access to Server API) Type-based

Business Objects

Workflow Validation Virtual Document Query Builder Operations High-Level Services Layer Low-Level Server Access fc.client DBO Framework DBO Framework Documentum Sample Objs Documentum Sample Objs Your Business Objects Your Business Objects Other Business Objects Other Business Objects

Service-based Business Objects

DCTM Sample Services DCTM Sample

Services Your Bus. Obj.

Services Other Bus. Obj.

Services

DFC Extensions

Documentum Foundation Classes (DFC) Business Objects Intrinsic Business Objects Workflow Services Workflow Services ISubscription Services ISubscription Services

(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 Object Hierarchy

• Aggregated Business Data

• Common Schema

Core Content Management Services

• Library Services

• Process Automation

• Content Authentication

Content and Data Schema Presentation Layer

• Generic Components

• Custom Components

• Industry / Company specific behavior

• Application Specific Abstraction

• Business Rules and Policies

• Common Object Model

Data Layer

• Content Object Hierarchy

• Aggregated Business Data

• Common Schema

Core Content Management Services

• Library Services

• Process Automation

• Content Authentication

Content and Data Schema

•

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.

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

(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 higher-level 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:

(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.

(26)

Appendix C: Exposing BOF Services as Web Services

Overview

In order to expose BOF services as Web Services, integration with a SOAP toolkit is required. Different vendors provide SOAP toolkits. Please refer to Appendix A: Getting Started – Development T for links to some of the different toolkits. To illustrate how to integrate with such a toolkit, the Apache Foundation has developed a public domain SOAP toolkit called AXIS. Axis is used in the following examples.

To build this integration a wrapper must be built for every BOF service to expose as a Web service. In addition, two other helper services provide some basic Docbase operations, such as login, DocBroker map etc., along with a service that maintains a connection across multiple service calls. This is required for convenience and performance reasons since it does not make sense to create a new Docbase connection with every call. The two helper services form the foundation for implementing all other services that might be required.

To illustrate the integration a very simple service is created that implements a Docbase inbox for the current user. A simple set of operations is provided that:

• • •

Lists inbox items Gets item details

Removes item from inbox

Of course, we could add additional services that would all use the basic functionality of the two helper services. New services can be plugged in as needed.

The following diagram shows what components are required and how they relate to each other: Figure 9: Required Components

AXIS Servlet Servlet Container Servlet Container

Connection Service

Connection Service Inbox Service_{Inbox Service} Docbase Service_{Docbase Service} IDocbase IDocbase IInbox IInbox DFC DFC Web Services Layer Business Objects Layer BOF BOF AXIS Servlet Servlet Container Servlet Container Connection Service

Connection Service Inbox Service_{Inbox Service} Docbase Service_{Docbase Service} IDocbase IDocbase IInbox IInbox DFC DFC Web Services Layer Business Objects Layer BOF BOF

(27)

The Apache AXIS Servlet is running in a Servlet container such as Apache Tomcat. Three Java Web Service (JWS) files (ConnectionService, InboxService, DocbaseService) are deployed and registered into the Axis Servlet repository to provide an adapter to the BOF Inbox and Docbase services. Using JWS makes deployment very easy. JWS files just need to be copied into the web application folder of the Axis Servlet and they are automatically registered.

These JWS services then call the applicable BOF service interface. The main benefits of using JWS to provide SOAP wrappers on top of BOF services are:

• • •

•

Service registration: Services become available on a web server

Selective exposure of service method: BOF service methods may be shielded from Web Service access

Parameter conversion: BOF services usually define DFC based method parameters. In a SOAP environment, it is more convenient to use basic type such a String, integer, etc. Therefore it is often required for example to convert a Documentum ID of type IDfId into a string and vice versa

WSDL generation: The JWS files can be easily converted into WSDL files

The subsequent sections describe the functionality that each of the three services provides.

Connection Service

Functionality

The connection service is a simple helper service (without BOF implementation) that maintains a connection across multiple service calls. When a connection is opened a unique connection ID string is returned to the client. With every subsequent service call, this connection string must be maintained until the connection is explicitly closed. If the client forgets to call the close()

method, the connection will eventually time out.

The connection service maintains a static list that stores a BOF session manager for each unique connection ID. This takes advantage of the basic session pooling provided by BOF and therefore provides optimized performance.

Implementation

The following code shows how the connection service is implemented. It is implemented as ConnectionService.jws (JWS file is a normal Java class file where the extension is changed from .java to .jws) and it is deployed for example into the <tomcat_home>/webapps/axis directory:

(28)

ConnectionService.jws

public class ConnectionService

{ /**

* Open a connection. Returns connection ID. */

public String open() throws Exception {

return ConnectionServiceManager.open(); }

/**

* Close a connection */

public void close(String connection) {

ConnectionServiceManager.close(connection); }

}

This service just provides two methods that allow opening and closing of a connection. The open() method returns the unique connection ID string, which is later used to close() the connection.

The ConnectionServiceManager.java is a static helper class that generates a unique ID and stores a BOF session manager instance associated with each connection. It also ensures that the session times out and returns the session back to the session pool. There are other approaches that provide the same functionality (e.g. using servlet sessions), but for convenience, we provide the following implementation:

ConnectionServiceManager.java

public static String open() throws DfException {

String id = generateUniqueId();

sMgrList.put(id, DFClient.getLocalClient().newSessionManager()); return id;

}

public static void close(String connection) {

sMgrList.remove(connection); }

The open method just stores the generated ID (code not shown) in a hashtable and creates a new instance of a session manager. When the connection is closed, the hashtable entry for the given connection is removed.

Client

Once the service JWS file is deployed into the AXIS Servlet, a WSDL file can be generated using the standard AXIS utility Java2WSDL. The client interface can then be generated e.g. using .NET.

To illustrate how to call the Web Service we use Java and the AXIS toolkit. The following code shows how the connection can be opened and closed.

(29)

Service service = new Service();

Call call = (Call) service.createCall();

call.setTargetEndpointAddress( baseUrl+"ConnectionService.jws" ); call.setOperationName("open");

call.setReturnType( XMLType.XSD_STRING );

String connection = (String)call.invoke(new Object[]{});

First, a service is created and a call is constructed that sets the target service, the operation and the return type. When the service is invoked, the connection string is returned. This connection is required for all subsequent method calls including the close() method. The baseUrl variable contains the address of the web server when the service is running, for example

"http://myhost/axis/".

call = (Call) service.createCall();

call.setTargetEndpointAddress(baseUrl+"ConnectionService.jws"); call.setOperationName("close");

call.addParameter( "connection", XMLType.XSD_STRING, ParameterMode.IN ); call.setReturnType( XMLType.XSD_ANY );

Object[] params = new Object[] {connection}; call.invoke( params );

The next call closes an open connection. We pass the connection string a parameter but the service invocation does not return a result.

Docbase Service

Functionality

The Docbase service is a second helper service that provides basic Docbase handling

functionality like retrieval of a list of valid Docbases, setting identities, and removing identities. To be able to use the Docbase service a connection must be established. The Docbase service is independent of DFC Docbase sessions since stateless sessions are managed by the BOF

framework.

Implementation

The Docbase service is implemented as a BOF service with the interface IDocbase and requires a JWS service that is deployed to the AXIS Servlet as DocbaseService.jws.

(30)

public interface Idocbase extends IDfService {

String[] getDocbaseList() throws DfException;

void setIdentity( String docbase, String user, String password, String domain) throws DfServiceException;

void clearIdentity(String docbase); }

It defines a method to retrieve all Docbases names known to the Docbroker. This method returns an array of strings for each Docbase name.

A second method is for setting an identity for authentication on a given Docbase. Using this mechanism, you can set identities for multiple Docbases. When an identity is cleared, Docbase access to that Docbase is disabled. Before a service like the IInbox service is called, an identity must be set.

A JWS file needs to be created to provide an adapter to expose the service as a Web Service. It is also deployed into the AXIS Servlet repository. The following code shows how the

DocbaseService JWS is implemented:

public class DocbaseService {

public String[] getDocbaseList( String connection ) throws Exception {

IDocbase docbaseService = (IDocbase)

ConnectionServiceManager.getService( IDocbase.class.getName(), connection);

return docbaseService.getDocbaseList(); }

public void setIdentity( String connection, String docbase,

String user, String password, String domain ) throws Exception

{

docbaseService.setIdentity( docbase, user, password, domain ); }

public void clearIdentity(String connection, String docbase) throws Exception {

docbaseService.clearIdentity(docbase); }

}

Each method gets the connection string as a parameter plus additional parameters if required. It then calls the corresponding BOF service and returns the result if applicable.

In addition, the connection session manager is used to provide a convenience method to pass the connection and the service name and it then instantiates the service.

(31)

Client

The following Java sample code shows how to use the AXIS client toolkit to call the Docbase service. We assume that we already have an open connection with the connection ID stored in the "connection" variable. The following code calls the DocBroker list and gets back an array of string names of Docbases that project to this DocBroker:

call = (Call) service.createCall();

call.setTargetEndpointAddress(baseUrl+"DocbaseService.jws"); call.setOperationName("getDocbaseList");

call.addParameter( "connection", XMLType.XSD_STRING, ParameterMode.IN ); call.setReturnType( XMLType.SOAP_ARRAY );

String[] strDocbases = (String[])call.invoke( new Object[]{connection} );

Inbox Service

Functionality

The IInbox service is a sample service that provides simple Documentum inbox manipulation. It allows itemizing of the user's inbox items, to display item details, and to remove an item. This service could be any other BOF based service that you may want to add that is provided by Documentum or Documentum’s partners.

Typical BOF services would probably be more complex but the IInbox service shows the basic mechanism.

Implementation

The Inbox service is implemented as a BOF service with the interface IInbox and requires a JWS service that is deployed to the AXIS servlet as InboxService.jws.

The Docbase BOF service is implemented as follows:

public interface Iinbox extends IDfService {

IDfList getList(String docbase) throws DfException;

IDfList getDetail(IDfId item, String attributes) throws DfException;

void remove(IDfId item) throws DfException; }

It defines a method to retrieve all items of the current user’s inbox. The result is returned as a list of IDfId objects. Each item can then be looked up using the getDetail() method. This method allows you to specify a comma separated string to indicate what attributes you are interested in. This method returns an IDfList of values. Finally, the remove() method removes an Inbox item.

The IInbox service is implemented in a Java class, named Inbox, which is mapped to the interface using the business object registry (DBOR) provided by BOF.