developing web services with documentum - dell...

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

Upload: lyhanh

Post on 18-May-2018

218 views

Category:

Documents


1 download

TRANSCRIPT

Page 1: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Developing Web Services with Documentum Documentum Technical White Paper

September 16, 2002 Erin Samuels

Page 1 of 50

Page 2: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 2 of 50

Page 3: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Functionality .......................................................................................................................... 29

Implementation....................................................................................................................... 29

Client ...................................................................................................................................... 31

INBOX SERVICE .......................................................................................................................... 31

Functionality .......................................................................................................................... 31

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

BUILDING THE INBOX CLIENT APPLICATION USING VB.NET..................................................... 43

Page 3 of 50

Page 4: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 5: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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 RegistryService Registry

Service RequestorService

RequestorService

ProviderService ProviderBind

PublishFind

Service RegistryService Registry

Service RequestorService

RequestorService

ProviderService ProviderBind

PublishFind

Page 5 of 50

Page 6: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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 programmers and automatically create the client stubs to invoke and call the SOAP interface.

Page 6 of 50

Page 7: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 7 of 50

Page 8: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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 RepositoryContent Repository

DFC

Web Server

DB

OF

Business Object

(Service)

Business Object

(Service)

Adapter Web

Service to Business

Object

Adapter Web

Service to Business

Object

.NET Application(Thick Client)SOAP Client

JSPSOAP Client

Browser

SOAP

SOAP

}

Application Server

Calls out to a Web Service

Calls out to a Web ServiceContent RepositoryContent Repository

DFC

Web Server

DB

OF

Business Object

(Service)

Business Object

(Service)

Adapter Web

Service to Business

Object

Adapter Web

Service to Business

Object

.NET Application(Thick Client)SOAP Client

JSPSOAP Client

Browser

SOAP

SOAP

}

Application Server

Calls out to a Web Service

Calls out to a Web Service

Page 8 of 50

Page 9: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 10: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

• 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

Page 11: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 12: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 4: Three Layers of Web Services

Web Services Compatible LayerWeb Services Compatible Layer

Content RepositoryContent Repository

DFC 4.x

Web Services Server Stub

Developing Web Services1. WSDL2. SOAP/Java

Stub

Developing Web Services1. WSDL2. SOAP/Java

Stub

DFC 5.x

Business Logic HereBusiness

Logic Here Business Logic HereBusiness

Logic Here

Apache BEA Microsoft IBM Oracle Sun

Web Services

Development Tools

Web Services

Development Tools

Web Services Compatible LayerWeb Services Compatible Layer

Content RepositoryContent Repository

DFC 4.x

Web Services Server Stub

Developing Web Services1. WSDL2. SOAP/Java

Stub

Developing Web Services1. WSDL2. SOAP/Java

Stub

DFC 5.x

Business Logic HereBusiness

Logic Here Business Logic HereBusiness

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.

Page 12 of 50

Page 13: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 5: DFC Architecture

DFC to Server Access Layer(Object-based access to Server API)

Type-basedBusinessObjects

Core DFC Layer – Object oriented access to Server API Layer

Workflow Virtual DocumentValidationQuery Builder

Operations

fc.clientDBO FrameworkDBO Framework

Documentum Sample Objs

Documentum Sample Objs

Your Business Objects

Your Business Objects

Other Business Objects

Other Business Objects

DFC Extensions

Intrinsic Business Objects

Core DFC Layer – Object oriented access to Server API Layer

fc.clientDBO FrameworkDBO Framework Session ManagerSession Manager

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

Session Manager CacheSession Manager Cache

Future Intrinsic ObjectsFuture Intrinsic Objects

DFC to Server Access Layer(Object-based access to Server API)

Type-basedBusinessObjects

Core DFC Layer – Object oriented access to Server API Layer

Workflow Virtual DocumentValidationQuery Builder

Operations

fc.clientDBO FrameworkDBO Framework

Documentum Sample Objs

Documentum Sample Objs

Your Business Objects

Your Business Objects

Other Business Objects

Other Business Objects

DFC Extensions

Intrinsic Business Objects

Core DFC Layer – Object oriented access to Server API Layer

fc.clientDBO FrameworkDBO Framework Session ManagerSession Manager

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

Session Manager CacheSession Manager Cache

Future Intrinsic ObjectsFuture Intrinsic Objects

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

Page 14: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

• 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 RepositoryContent Repository

Client

COM

SOAP

Web Server

SOAP

EJB

DFC

Content RepositoryContent 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

Page 15: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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 applications and access them through Web Services.

Page 15 of 50

Page 16: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 16 of 50

4. Disconnect

Page 17: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 18: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

• 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.)

• Can use advanced toolkits like BEA workshop

Page 18 of 50

Page 19: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 20: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 21: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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.

Page 21 of 50

Page 22: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

DFC to Server Access Layer(Object-based access to Server API)

Type-basedBusinessObjects

Core DFC Layer – Object oriented access to Server API Layer

Workflow Virtual DocumentValidationQuery Builder

Operations High-Level

ServicesLayer

Low-Level

Server Access

fc.clientDBO FrameworkDBO Framework

Documentum Sample Objs

Documentum Sample Objs

Your Business Objects

Your Business Objects

Other Business Objects

Other Business Objects

Service-based Business ObjectsDCTM Sample

ServicesDCTM Sample

ServicesYour Bus. Obj.

ServicesYour Bus. Obj.

ServicesOther Bus. Obj.

ServicesOther Bus. Obj.

Services

DFC Extensions

Documentum Foundation Classes (DFC)BusinessObjects

Intrinsic Business Objects

Workflow Services

Workflow Services

ISubscription Services

ISubscription Services

Future Intrinsic ObjectsFuture Intrinsic Objects

DFC to Server Access Layer(Object-based access to Server API)

Type-basedBusinessObjects

Core DFC Layer – Object oriented access to Server API Layer

Workflow Virtual DocumentValidationQuery Builder

Operations High-Level

ServicesLayer

Low-Level

Server Access

fc.clientDBO FrameworkDBO Framework

Documentum Sample Objs

Documentum Sample Objs

Your Business Objects

Your Business Objects

Other Business Objects

Other Business Objects

Service-based Business ObjectsDCTM Sample

ServicesDCTM Sample

ServicesYour Bus. Obj.

ServicesYour Bus. Obj.

ServicesOther Bus. Obj.

ServicesOther Bus. Obj.

Services

DFC Extensions

Documentum Foundation Classes (DFC)BusinessObjects

Intrinsic Business Objects

Workflow Services

Workflow Services

ISubscription Services

ISubscription Services

Future Intrinsic ObjectsFuture Intrinsic Objects

Page 22 of 50

Page 23: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

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

Page 24: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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:

Page 24 of 50

Page 25: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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

Page 26: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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 ContainerServlet Container

Connection ServiceConnection Service Inbox ServiceInbox Service Docbase ServiceDocbase Service

IDocbaseIDocbaseIInboxIInbox

DFCDFC

Web ServicesLayer

Business ObjectsLayer

BOFBOF

AXIS Servlet

Servlet ContainerServlet Container

Connection ServiceConnection Service Inbox ServiceInbox Service Docbase ServiceDocbase Service

IDocbaseIDocbaseIInboxIInbox

DFCDFC

Web ServicesLayer

Business ObjectsLayer

BOFBOF

Page 26 of 50

Page 27: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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:

Page 27 of 50

Page 28: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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.

Page 28 of 50

Page 29: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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.

The Docbase BOF service is implemented as follows:

Page 29 of 50

Page 30: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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 { IDocbase docbaseService = (IDocbase) ConnectionServiceManager.getService( IDocbase.class.getName(), connection); docbaseService.setIdentity( docbase, user, password, domain ); } public void clearIdentity(String connection, String docbase) throws Exception { IDocbase docbaseService = (IDocbase) ConnectionServiceManager.getService( IDocbase.class.getName(), connection); 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.

Page 30 of 50

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.

Page 31: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

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.

Page 31 of 50

Page 32: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

To provide an adapter to expose the service as a Web Service a JWS file must be created that is deployed into the AXIS servlet repository. The following code shows how some of the InboxService.jws JWS is implemented (for simplicity, only one method is shown): public class InboxService { public String[] getList(String connection, String docbase) throws Exception { IInbox inboxService = (IInbox) ConnectionServiceManager.getService( IInbox.class.getName(), connection); IDfList list = inboxService.getList(docbase); int count = list.getCount(); String[] result = new String[count]; for (int i = 0; i < count; i++) result[i] = list.getId(i).toString(); return result; } … }

This example shows the wrapper nature of the JWS file. It uses the connection service manager to instantiate a service that contains the right BOF session manager and then just calls this service. The service returns an IDfList of IDfId objects, and since they are not very suitable for Web Services, the list is first converted into a string array if ID strings and then returned.

Client The following sample code shows a Java client using the AXIS toolkit. It assumes that the connection is established (using the connection service) and that an identity is defined (using Docbase service). Then, calling the getList() method returns an array of strings. Each string represents the name of a Docbase. call = (Call) service.createCall(); call.setTargetEndpointAddress(baseUrl+"InboxService.jws"); call.setOperationName("getList"); call.addParameter( "connection", XMLType.XSD_STRING, ParameterMode.IN ); call.addParameter( "docbase", XMLType.XSD_STRING, ParameterMode.IN ); call.setReturnType( XMLType.SOAP_ARRAY ); String[] items = (String[])call.invoke(new Object[]{connection, docbase});

Page 32 of 50

Page 33: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Appendix D: Using BOF with BEA WebLogic Workshop and .NET The first part of this example demonstrates how to expose a BOF service as a Web Service using BEA WebLogic Workshop. WebLogic Workshop has a graphical user interface that shows the main features of a Web Service. The second part of this example shows how the new Web Service can be accessed from a .NET client.

Defining the BOF Service The first step is to develop or obtain a BOF service. This example uses a simple inbox service. The goal of this exercise is not to develop complex business logic but to show how BOF components can be exposed as Web Services.

The following is the inbox service: public interface IInbox extends IDfService { /** * Read inbox items. Returns a list of item IDs */ IDfList getList(String docbase) throws DfException; /** * Get details of a given item. Specify item id and attributes * (comma separated list). Data is returned as an IDfList. */ IDfList getDetail(IDfId item, String attributes) throws DfException; /** * Remove an item from the inbox. */ void remove(IDfId item) throws DfException; }

The getList() method retrieves all IDs of the current user’s inbox items. For each item, the getDetail() method can be called to obtain the details of the item, such as task name and priority. The remove() method simply removes the specified item from the inbox.

Please note that this service uses Documentum specific data types such as IDfId, which is used to pass Documentum specific data types.

Defining the “Connection” Web Service Since Web Services are naturally stateless, some kind of connection or session management is required for the following reasons:

• Security: We want to send the password once and then use the connection ID

• Performance: We want to cache session information on the server side for performance reasons

Page 33 of 50

Page 34: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

To achieve these two objectives, an EJB is created to store connections with associated identities. In addition, a Web Service is needed to allow opening a connection, setting identities, and closing the connection.

Figure 10 shows the “Connection” Web Service that is created using BEA WebLogic Workshop:

Figure 10: Connection Web Service Design View

All of the operations of the Web Service are graphically displayed on the left side of the right pane. Clicking on an operation allows it to be implemented or modified. The “connection” control on the right side allows caching of identities. It is implemented as an EJB, as indicated by the EJB icon.

The Connection service is basically a wrapper on top of the EJB. It exposes all operations except getIdentity. This is done purposefully to prohibit access to this information from a Web Service.

In order to use the Connection service, the application must first call “open” to get a unique connection ID. From then on, all operations must provide this connection ID.

The next screenshot shows the implementation of the open operation. It simply calls the corresponding method in the EJB control and returns the string result.

Page 34 of 50

Page 35: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 11: Connection Web Service Source View

The Connection service must be created and registered once. Then other Web Services can be created for each BOF business object and the Connection service is used by all of them.

Page 35 of 50

Page 36: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Defining the “Inbox” Web Service To expose this BOF service as a Web Service we can use BEA WebLogic Workshop and BEA Weblogic 7. The Web Service is defined as follows:

Figure 12: InboxService Web Service Design View

The operations of the InboxService.jws (JWS = Java Web Service) are displayed. In addition, it shows the same methods that the BOF service exposes.

The next step is to add a control that is implemented as an EJB that uses cache identities to create Docbase connections. The purpose of this control is to provide session management for Web Services. This is required for performance and security reasons.

Since the application in this example first connects and then performs several operations on the inbox, the user identity must be cached on the application server. The session could be reused if the user sends several requests within a short period of time.

Page 36 of 50

Page 37: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Clicking the addControl button allows you to define the “connection” control mentioned previously using the Add EJB Control dialog as shown in Figure 13.

Figure 13: Add EJB Control dialog

Here an EJB called “ConnectionManager” is selected. This EJB was already deployed to the WebLogic server.

NOTE: This is done once and the control remains registered in Workshop.

Figure 14 shows how the control is displayed in the graphical view of Workshop:

Page 37 of 50

Page 38: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 14: InboxService “connection” Control

Figure 15 shows the implementation of the remove operation. The source code shows up when the operation is clicked:

Page 38 of 50

Page 39: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 15: InboxService remove() operation Source View

First, the identity is obtained from the connection manager. The connection ID “conn” and the item ID “item” are passed to the remove operation as arguments from the caller using the getIdentity() method. The getIdentity() method returns an IdentityInfo object “info”. Next, the IInbox BOF service is instantiated using the Connection.getService() method. Then the IInbox.remove() method is called and that’s it.

WebLogic Workshop allows testing the Web Service just created and also allows source-level debugging of the service. Figure 16 shows the InboxService test page that provides a mechanism of testing all operations provided by the service:

Page 39 of 50

Page 40: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 16: InboxService test entry form

Connection ID and Docbase Name are entered here.

Figure 17 shows how the getList() method is tested. Figure 16 shows how the connection ID and the Docbase name are entered. The connection ID was provided by the connection open() method. When the “getList” button is clicked, the getList() method is invoked and produces the “<ArrayOfString>” list as shown:

Page 40 of 50

Page 41: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 17: InboxService “getList” test results

Once the Web Service is implemented and tested the WSDL is generated to describe the service for the client applications. Figure 18 shows the InboxService “Generate WSDL from JWS” context menu option.

Page 41 of 50

Page 42: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 18: InboxService WSDL generation

This is also required for the Connection service as shown in Figure 19.

Page 42 of 50

Page 43: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 19: Connection service WSDL generation

Now everything is ready on the application server side.

Building the Inbox Client Application using VB.NET A VB client application is built that consists of:

• A Docbase Login dialog (shown in Figure 20)

• A Documentum Inbox dialog with an inbox item list box along with remove and refresh buttons (shown in Figure 21)

When the application is started the login dialog is called first. All of this is designed using VB.NET.

Page 43 of 50

Page 44: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 20: Docbase Login form

Figure 21: Documentum Inbox form

The Web Services are registered as “WebReferences” using the Add Web Reference dialog shown in Figure 22:

Page 44 of 50

Page 45: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 22: Add Web Reference dialog

Specify URL of the Web Service with WSDL after the question mark.

Enter the URL of the Web Service and then specify “WSDL” after the question mark. Then click the “Add Reference” button. The Web Service is registered and it shows up in the solution explorer window. In VB the service is now known as “ConnectionSvc” as shown in Figure 23.

Page 45 of 50

Page 46: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 23: Connection service as “ConnectSvc” in VB

Figure 24 shows how the service can be called from the VB implementation:

Page 46 of 50

Page 47: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 24: Calling the ConnectSvc from VB

Dim conn As New ConnectSvc.Connection()

Pass the connection ID to the login dialog.

The global variable “conn” is defined the type as returned by “ConnectionSvc.Connection()”. When the form is loaded, the “conn.open()” method is called, which returns the connection ID. This ID is then passed to the login dialog.

For each service there is a global variable in the VB application and we just call the corresponding member functions. Using the WSDL definitions of the services, VB .NET can automatically list all methods that this service exposes as shown in Figure 25:

Page 47 of 50

Page 48: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 25: VB code completion uses WSDL

Once the VB code is implemented we can start the application.

First the login dialog is displayed:

Figure 26: Docbase Login dialog

Once logged in, the Documentum Inbox dialog is displayed:

Page 48 of 50

Page 49: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 27: Documentum Inbox

The Inbox can be refreshed to view new items.

Figure 28: Documentum Inbox – Select Item

Selected items can be removed using the “Remove” button:

Page 49 of 50

Page 50: Developing Web Services with Documentum - Dell EMCdeveloper-content.emc.com/.../DevelopingWebServices… ·  · 2006-10-16Web Services and Documentum in Production Today ... advanced

Developing Web Services with Documentum

Figure 29: Documentum Inbox – Selected Item Removed

Page 50 of 50