Abstract

DFC 5.3 introduced the web services framework that allows a developer to expose a Service-based Business Object(SBO) as a web service. This article walks you through the process of enabling a SBO as a web service and then consuming it from a .NET client.

Software Environment

Introduction

DFC 5.3 introduced the web services framework that allows a developer to expose a Service-based Business Object(SBO) as a web service. Documentum Application Builder(DAB) is used for registering a SBO and also to convert it into a web service. The process of conversion takes the SBO jars and packages them in a Web Application Archive (war) file that also contains the Apache Axis framework.

Web Services Framework

To enable a SBO as a web service, you need to install the Documentum Webservices Framework. This is a separate install from DFC and will need to be downloaded from the products download site. On the products download site it is in the category 'Documentum Foundation'. Before installing ensure that you have your global registry configured correctly.

AutoNumber SBO

We will use a sample AutoNumber SBO that generates a unique number every time you invoke its method getNextNumber(...). The interface and implementation jars are available in the download package available at the end of this article. You will need to register the SBO using Documentum Application Builder. Here are the SBO attributes -

Name: com.documentum.devprog.autonumber.IAutoNumberService
Interface Jar: autonumberService.jar
Implementation Jar: autonumberServiceImpl.jar
Implementation Class:com.documentum.devprog.autonumber.impl.AutoNumberService

Enable as a Web Service

The SBO can be converted to a web service either during its registration or at a later time by editing the SBO properties from DAB. The SBO properties dialog has a tab called 'Web Service'. On this tab select the checkbox to 'Enable as Web Service'. Then select the '.war' file that will contain the SBO as a webservice. Note that if you don't see '.war' files, it means that the Webservices Framework has not been installed.



Fig - Web Services Tab in Documentum Application Builder

Once that is done, DAB will package the SBO jars into the selected '.war' file. This '.war' file is placed in the repository. The '.war' file is created when the docapp is checked in. The file is created and placed in the folder /System/Modules/SBO.

You will then need to export this '.war' file from the repository onto the local filesystem and then place it in your application server. For example, with Apache Tomcat, simply dropping the file into TOMCAT_HOME/webapps and restarting Tomcat should be sufficient. Here is a screenshot of the Tomcat console that shows the web services application loaded by Tomcat -



Fig - Web Service Application Loaded by Tomcat

The webservices can then be accessed from the application server using a webservices client such as MS Visual Studio.NET.

Accessing the Web Service from a .NET Client

In MS Visual Studio.NET create a new Windows Application project. Within this project, add a new webreference. Note that you can consume the web service from a ASP.NET application too. We have chosen a Windows Application project for the sake of simplicity.



Fig - Add Web Reference

Specify the URL to the web application that contains the SBOs. The web application name would typically be the same as the war filename. In Tomcat, if you just dropped the file ws.war into the webapps folder, the name of the web application is 'ws' and the URL for example would be http://localhost:8080/ws. Opening this URL presents you with an Apache Axis Menu. From this menu, click on View link to view all the available web services.



Fig - Web Services URL

The important web services to notice are the DocbaseCredentialsService and the AutoNumberService. The first one is a standard web service bundled by Documentum. This web service manages authentication with the Repository and creates an authentication token (a.k.a security token) that should be used by a client with every call to a SBO web service. The second one is the AutoNumber web service, which is our SBO enabled as a web service.



Fig - View all Web Services

Click on the wsdl link for DocbaseCredentialsService. This will show you more details about this service. Provide a name for this web reference and click on 'Add Reference'. This will create a new web reference and a namespace for the DocbaseCredentialsService within your project.



Fig - DocbaseCredentialsService

Repeat the above steps and add a reference for the AutoNumber web service.



Fig - AutoNumberService

You should now have two web references within your project. You can find out more information about these web references using the Visual Studio object browser (double-click on them from the Solution Explorer view).



Fig - Web References

For the sake of simplicity create a button and a textbox on your Windows Form. Include the namespaces for the web references within your Form source code. In the figure below, 'TestWebService' is the project name and hence the default project namespace.



Fig - Namespaces

Within the event handler of the button create a DocbaseCredentialsInfo object and populate its properties. Use this object and create a security token from a DocbaseCredentialsService object.



Fig - DocbaseCredentialsInfo

The Documentum Web Services Framework inserts an additional field in our SBO that allows a caller to specify the security token to use when calling the web service. The security token needs to be encapsulted in an instance of DocumentumSecutiryToken when invoking a SBO web service. Using the security token created above, invoke the auto number service and print the unique number generated in the text box on the form.



Fig - Invoke the AutoNumberService

Download

EnableSBOAsWebService.

The above file contains the SBO jars, the Visual Studio.NET project and the source code for the SBO. The C# code is contained in the Form1.cs file within the Visual Studio.NET project.