Writing Web Services On The Documentum Platform

Writing Web Services On Documentum

Platform

January 14, 2002

Sachin Chaudhari
Sachin.chaudhari@documentum.com

Docume ntum Developer Program page 1 of 13

Writing Web Services On The Documentum Platform

Writing Web Services On Documentum

Platform
Web services offer the potential for creating highly dynamic and versatile distributed
applications that span technological and business boundaries, allowing service providers
and service consumers to improve the way they do business.

This document can be used as a tutorial to create web services on the Documentum
Platform. This document will walk you through a web service example, which will
import the content and kick off a workflow using the Documentum Foundation Class
library (DFC). This example can be deployed on all the application servers supported by
Apache SOAP v2.2 runtime. For reference, the deployment and usage of the Apache
Tomcat 3.2 container is explained in this chapter.

What is Workflow?

A workflow formalizes a business process such as a medical claims process

or an engineering development process. After the business process is formalized in a
workflow definition, users can use the definition to repeatedly perform the business
process.

Workflow is the integral part of a content management solution. Workflow based web
services can be used to create seamless integration between different applications. For
example SAP can use workflow services to kick off different processes in the
Documentum e-Content server as a part of SAP’s workflow. This way we can have an
inter-organization workflow.

A Workflow Workflow D
Client SOAP Web
Service
P F
SAP DCTM
CRM Solutions
Workflow
I Workflow C
Web SOAP Client
Service

Fig 1.1 Inter-Application WorkFlow

Docume ntum Developer Program page 2 of 13

Writing Web Services On The Documentum Platform

What Does the WorkFlow Web Service Do?

In this particular service, a purchase order-processing scenario is used. The web service
client can be written in Visual Basic, Java or another langauge. The client uses an XML
file (called msg1.xml), which contains the meta-data of the content and workflow
template. The meta-data of the purchase order is the information regarding the purchase
order attribute for example price, quantity, item name and so forth. The content can be in
any file format: a word purchase order or scanned purchase order. The web service client
sends the content to the web service server as a MIME attachment to the SOAP envelope.
Once the server receives the SOAP envelope, workflow service will write the SOAP
envelope to a XML file. Also it will store the attachment on the file system. Then it will
import the content in the Docbase using the attributes specified in the SOAP envelope.
After the import operation, the workflow service will start the workflow specified in the
XML file. The content will serve as the package to the workflow process.

Pre-requisites

1. Working installation of Apache SOAP v2.2 runtime.

2. Basic understanding of how message based web services work.
3. You should have written and built at least one web service using Apache SOAP
runtime.

Docume ntum Developer Program page 3 of 13

Writing Web Services On The Documentum Platform

Writing Message Services

Creating message-oriented services in Apache SOAP is a little more complex than
creating simple RPC-based services, but in the case of Documentum applications a
message-oriented model provides a better fit to the problem. In a message-oriented
service, the service implementation is responsible for processing the contents of the
SOAP envelope.

Because message-oriented services have full control over the SOAP envelopes, any XML
document may be passed as part of the envelope body. When the service receives the
SOAP envelope, it is free to extract the body, and do with it as it pleases.

Following are the major steps to develop the server side implementation of the web
service (Please refer to source code files: workflowTest.java, Dctm_utils.java. These files
can be downloaded from the Developer Program website):

1. Create the interface definition of the service:

Unlike RPC-service implementations, message-oriented service implementations
must all conform to a single interface:
void name(SOAPEnvelope request-envelope, SOAPContext request-
context, SOAPContext response-context)
where name is the name of the method/function, request-envelope is the
SOAPEnvelope containing the incoming message, request-context is the
SOAPContext for the incoming message, and response-context is the SOAPContext
which may be used for a response if one is needed.

In case of workflow example, the interface is:

public void startworkflow (Envelope env, SOAPContext reqCtx,
SOAPContext retCtx) throws IOException,
MessagingException, SAXException, Exception

2. Get the envelope XML document from the reqCtx.

MimeBodyPart rootPart = reqCtx.getRootPart();

Object O = rootPart.getContent();
String env_content = O.toString();
DocumentBuilder xdb = XMLParserUtils.getXMLDocBuilder();
Document doc =
xdb.parse(new InputSource(new StringReader(env_content)));
if (doc == null) {
System.err.println("Failed to parse the envelope.");
}

3. Parse the XML and store data in Hashatables.

NodeList list = doc.getElementsByTagName("package");
for( int i=0; i<list.getLength(); i++ ){
node = list.item( i );

Docume ntum Developer Program page 4 of 13

Writing Web Services On The Documentum Platform

attrs = node.getAttributes();
for (int j = 0; j < attrs.getLength(); j++)
{
attr = attrs.item(j);
package_meta_data.put(attr.getNodeName(),attr.getNodeValue());
}
}

4. Connect to docbase.
//connect to docbase
Dctm_utils util = new Dctm_utils();
session = util.connectToDocbase ("LionelOra1","sachin","****");
//or you can use an ini file to read the docbase connection parameter
Please change the docbase parameters(username,password etc) as per your
configurations.

5. Import the 2nd body part which is the content file attached. The 1st body part is
the SAOP message. The docbase attributes are obtained from the hashtable
which is populated after parsing the XML file(SOAP envelope).

String destionation_folder =
package_meta_data.get("destionation_folder").toString();

//set DFC tracing

DfTrace.setTraceLevel(3);
DfTrace.setTraceFileName("h:\\temp\\dfctrace.txt");

// set up the main body of an "import" operation.

IDfImportOperation importOperation = new DfImportOperation();
importOperation.setSession(session);
importOperation.setDestinationFolderId(new DfId(destionation_folder));

// iterate through the files and add only those files that have the
// appropriate properties attached to them i.e. name, format & type.
IDfImportNode node =
(IDfImportNode)importOperation.add(attachment.getAbsolutePath());
node.setNewObjectName(package_meta_data.get("name").toString());

node.setFormat("msw8");

// Execute the operation.

String r_object_id = "";
bExecuteSucceeded = importOperation.execute();
IDfList nodes = importOperation.getNodes();
node = (IDfImportNode)nodes.get(0);

Docume ntum Developer Program page 5 of 13

Writing Web Services On The Documentum Platform

r_object_id = node.getNewObjectId().toString();

//set the meta_data like author, keyword etc for package

IDfPersistentObject attachment_object =
session.getObject(node.getNewObjectId());
attachment_object.setRepeatingString
("authors",0,package_meta_data.get("author").toString());
attachment_object.save();

//Store r_object_id for later use

package_meta_data.put("r_object_id",r_object_id);

6. Store the workflow meta-data into a hashtable:

list = doc.getElementsByTagName("workflow");
for( int i=0; i<list.getLength(); i++ ){
node = list.item( i );
attrs = node.getAttributes();
for (int j = 0; j < attrs.getLength(); j++)
{
attr = attrs.item(j);
workflow_meta_data.put(attr.getNodeName(),attr.getNodeValue())
}
}

7. The object imported in step 5 can be used as a package to the workflow.

Following code explains the steps required to add the workflow package and to
start the workflow.

IDfWorkflowBuilder workflowBuilder =
session.newWorkflowBuilder( new DfId( processId ) );

// Fetch the start activity and check a few limitations. We

// currently only support a single start activity.

IDfList idList = workflowBuilder.getStartActivityIds();

IDfActivity activity = (IDfActivity)
session.getObject( (DfId) idList.get( 0 ) );
if ( idList.getCount() > 1 )
System.out.println("ERROR: Currently we support only one start
activity!");

// Find the input port. Note that this command can only
// support start activities with a single input port.

int inputPortIndex = 0;
boolean inputPortFound = false;

Docume ntum Developer Program page 6 of 13

Writing Web Services On The Documentum Platform

for ( int i = 0; i < activity.getPortCount(); i++ )

{
if ( activity.getPortType( i ).compareTo( "INPUT" ) == 0 )
{
if ( inputPortFound == false )
{
inputPortFound = true;
inputPortIndex = i;
}
else
System.out.println("ERROR: Currently we support only one
input port!");
}
}

// Initialize the workflow and start it running.

workflowBuilder.initWorkflow();
workflowBuilder.runWorkflow();

// Insert the initial package to get things flowing.

workflowBuilder.addPackage(
activity.getObjectName( ),
activity.getPortName( inputPortIndex ),
activity.getPackageName( inputPortIndex ),
activity.getPackageType( inputPortIndex ),
note, notePersistence, componentIdList );

8. Send the response to the workflow client. In this example, the reponse is just a
string with status of the workflow operation.

//Send back string saying workflow successful or unsuccessful

retCtx.setRootPart(response_string.toString(),"text/xml");

If the communications transport which you are using supports two-way interaction, such
as HTTP, then you can use the response context to send a response back to the client. If
you want to send a SOAP Envelope back to the client, you can use the
org.apache.soap.Envelope's marshall(...) method to marshall your envelope to a
java.io.StringWriter, and then invoke the response context's setRootPart(...) method,
passing the StringWriter as the first argument. If you want to send back any other data
types, then you may need to invoke other methods in the response context.

Docume ntum Developer Program page 7 of 13

Writing Web Services On The Documentum Platform

Writing WorkFlow Web Service Client

The example code accompanied explains how to write WorkFlow client using Apache
SOAP API’s. Writing clients to access SOAP message-oriented services requires that
you interact with a lower-level set of Apache SOAP APIs than you would otherwise have
to if you were writing a SOAP RPC-based client. However, message-oriented services
provide you with a finer grain of control over what is actually being transmitted over
SOAP. In fact, the RPC mechanism is built on type of this message-oriented layer. For
more information on message oriented services please look at the SOAP specifications.

The basic steps for creating a workflow client which interacts with a SOAP message-
oriented workflow service are as follows:

1. Obtain the interface description(WDSL or Deployment Descriptor) of the

SOAP service, so that you know what the format of the SOAP message
should be (i.e. what headers it should have, what the body should look like,
etc.) as well as the type of message exchange which will take place.
The deployment descriptor for workflow service looks as follows:

<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
id="urn:workflowtest" type="message">
<isd:provider type="java"
scope="Application"
methods="startworkflow">
<isd:java class="documentum.workflow.workflowTest" static="false"/>
</isd:provider>
</isd:service>

It has only one method called startworkflow.

2. Construct an org.apache.soap.Envelope which contains the information that

the SOAP service requires. In workflow case the envelope contains the meta-
dat information about the package and the workflow. The content itself is
attached as a MimeBodyPart.

Docume ntum Developer Program page 8 of 13

Writing Web Services On The Documentum Platform

The SOAP envelope will look like:

<?xml version='1.0' encoding='UTF-8'?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<startworkflow xmlns="urn:workflowtest">
<package location="myfile0"
name="purchase_order.doc"
author="Sachin"
destionation_folder="/sachin/web services/data" />
<workflow name="purchase_order"
note="web service test"
processId="4b3cca4c80061ac3"/>
</startworkflow>
</s:Body>
</s:Envelope>

3. Create an org.apache.soap.messaging.Message object.

If you need to add MIME attachments to your message, then you can use
addBodyPart(...) method to do so.

Attach content to the Message as an MimeBodyPart

Message msg = new Message();
// Add attachments.
for (int i = 2; i < args.length; i++) {
ByteArrayDataSource ds =
new ByteArrayDataSource(new File(args[i]), null);
DataHandler dh = new DataHandler(ds);
MimeBodyPart bp = new MimeBodyPart();
bp.setDataHandler(dh);
bp.setFileName(args[i]);
bp.setHeader(org.apache.soap.Constants.HEADER_CONTENT_L
OCATION,
"myfile" + (i - 2));
msg.addBodyPart(bp);
}

Read the XML file which contains the SOAP envelope:

FileReader fr = new FileReader (args[args.length-1]);
DocumentBuilder xdb = XMLParserUtils.getXMLDocBuilder();
Document doc = xdb.parse (new InputSource (fr));
if (doc == null) {
throw new SOAPException Constants.FAULT_CODE_CLIENT,
"parsing error");
}

Docume ntum Developer Program page 9 of 13

Writing Web Services On The Documentum Platform

Envelope msgEnv = Envelope.unmarshall(doc.getDocumentElement());

4. Invoke the send(...) method on the Message object, providing the URL of the
endpoint which is providing the service (i.e.
http://localhost/soap/servlet/messagerouter), the actionURI, and your
envelope.

// Invoke.
msg.send(url, "", msgEnv);

5. If your service is returning data, and assuming that the transport supports
two-way interaction, then you need to retrieve the SOAPTransport object
from the Message object (assuming that you don't already have a handle to
it) by using the getSOAPTransport() method. You can then invoke the
receive() method on the SOAPTransport object to retrieve the returned data.
In this example, web service return a String with all the relevant information like
weather import/workflow was successful or not.

// Receive response as DataHandler.

printObject(msg.receive());

Docume ntum Developer Program page 10 of 13

Writing Web Services On The Documentum Platform

How to Build and Run Example

1) Make sure SOAP 2.2 and Apache Tomcat 3.2 is installed and running.
2) Run the SOAP samples shipped with Apache Soap to test the installation.
3) Copy the documentum folder in the same directory where sample
directory exists.

4) To build: Make whatever changes you need to make in the source code.
In the source code directory you will find a build script. Run the script to
build and install the web service client as well as server. The script creates
a staging directory to keep the compiled classes, creates a jar files, copies
the jar files to the %TOMCAT_HOME%\webapps\soap\WEB-INF\classes
directory so that tomcat server can pick it up. Also copies the client
classses to working directory so that testmessaging.cmd script which runs
the client can pick it up.
5) Open command prompt and run $tomcat_home\jakarta-tomcat-
3.2.1\bin\tomcatEnv.bat to set the environment.
6) Create the workflow template you want to use. The r_object_id of the
template corresponds to the processId in the msg1.xml. Also change the
other parameters in the msg1.xml file as per your requirements.

<workflow name="purchase_order"
note="web service test"
processId="4b3cca4c80061ac3"/>

Docume ntum Developer Program page 11 of 13

Writing Web Services On The Documentum Platform

7) Modify the package meta-data as per your requirements. Make sure the
destination_folder already exists in the docbase & it has enough
permissions.

<package location="myfile0"
name="purchase_order.doc"
author="Sachin"
destionation_folder="/sachin/web services/data" />

8) Start tomcat server in separate command prompt and run

testmessaging.cmd.
9) You will see output similar to following:

Docume ntum Developer Program page 12 of 13

Writing Web Services On The Documentum Platform

As you can see, the script first deploys the services and then lists all the services.
One of the services is the workflowtest service. This script calls the workflow
client class with appropriate parameter and deploys the result from workflow
service, then undeploys the service. If you look into the docbase inbox of the
appropriate user, you should see the activity. Also you will find the content file
imported into the specified folder.

Docume ntum Developer Program page 13 of 13