EMC Developer Network

The Documentum eDK for Workflow - Making Workflow Collaborative

Collaboration within Workflow? "How interesting," you say. "But how does that work?" First let’s review what a workflow is. Workflows map the steps for completing a particular work activity, such as creating a legal contract, conducting a consulting engagement, or performing a financial audit. These steps usually are manual, "review this contract document," for example. Branching paths provide various outcomes depending on whether the reviewer felt the document was complete or not, like sending it back to the writer for more edits. The workflow "engine" delegates and tracks tasks for people to perform.

Now let’s see what happens when we design a workflow to interact with eRoom, where a team is engaging in the creation of contracts, managing a consulting engagement, or executing a financial audit. While traditionally the work items of a workflow are documents, the addition of eRoom Enterprise to the suite of Documentum products has allowed for the implementation of structured business processes that have collaborative or team workspace items as ‘packages.’ For example, a workflow might be designed to draw a user directly to an item in eRoom to review content, vote on resolution, discuss an issue or provide feedback. Further, a workflow can be created that automatically interacts with an eRoom to configure the room for the workflow activities that are to be completed therein, for example through the creation of folders, addition of content, or the insertion of a row in an issues list. Should the specific process warrant it, the workflow can even create an entirely new eRoom and add members to the room. This powerful concept of incorporating collaborative activities within a traditionally task oriented workflow environment is done with a combination of the eRoom Enterprise version 7.2 product and the eRoom Developer Kit for Workflow (eDK for Workflow).

The Documentum eDK for Workflow is a toolkit and sample application that enables you to develop and use scripts that can be launched from within Documentum Workflows. These actions provide an automated means for integrating collaboration into a structured business process. Generally these activities will configure an eRoom workspace in preparation for subsequent user task execution. The eDK for Workflow is available for download on the Documentum Developer site, by clicking on the eRoom Enterprise 7.2 eDK for Workflow link from the eRoom resources page (http://customernet.documentum.com/developer/eroom/index.html).

This article will provide an overview of the eDK focusing on implementation of the Java classes for invocation on the eRoom server. The developer is also encouraged to view an on-line recorded event that covers each of the additional steps in more detail; the event can viewed from the following location: http://www.documentum.com/events/2004/Q2/05_05_04_REC_eRoom_eDK.htm.

Overview

The eDK for Workflow consists of Content Server code, eRoom Server code, and a number of sample workflows and server methods. Included in this release are modules that allow you to execute the following tasks from within a workflow.

  • Create an eRoom
  • Add members to an eRoom
  • Create collaborative items in an eRoom (folder, discussion topic, or database row)
  • Create a link to Content Server-stored content in an eRoom
  • Check out a file from Content Server and place a copy in an eRoom
  • Checking in a file to Content Server from a file stored in eRoom

The eDK includes server methods for each of these functions as well as a Service-based Business Object (SBO) that provides Content Server to eRoom Server communication services.

Architectural Overview

When a workflow is designed to include automatic actions, the workflow developer will include and configure an activity that is specified to be performed through the execution of some designated code. This code is executed on the Content Server and, for eDK actions, dispatches requests to the eRoom Server via an HTTP-delivered request/response model. Requests to the eRoom server are made either to the eRoom Web Service interface or to an ASP page included in the eDK (where eRoom’s web service interface did not support the required action, implementation was provided with the included ASP page). The request to the eRoom server includes, for authentication purposes, the login name and a login ticket for the user for whom the automatic method is being performed. (Starting with eRoom Enterprise version 7.2, eRoom authentication may be achieved with a documentum login ticket. Note that this depends on matching usernames between eRoom and Documentum.)

All of the "heavy lifting" in an event-triggered workflow implementation is provided in the eDK’s SBO. The developer need only create and configure a few simple objects in the docbase and implement some simple operations in a Java-based server method. When such an automatic activity is then instanced in a workflow, the activity launches the designated server method, which invokes the specified Java class that in turn uses the SBO to dispatch the request to the eRoom server. This process is depicted in figure 1.

How it’s done

When implementing a workflow that includes event-triggered eRoom actions, the workflow developer must do the following.

  • Create a Java class that will take in a particular invocation signature. This class, which represents an eRoom action such as create database row, is customized by the developer for the intended workflow use. This development process is fully described below.
  • Using the Docapp Builder, create a dm_method in the docbase. In this dm_method, the Type should be set to "java", The Command should invoke the Java class described in Step 1, and the Run as the server and Use as workflow method checkboxes should be selected.
  • Using the Workflow Manager, include an automatic activity in a workflow template. Configure the activity so that it will execute Automatically on behalf of a performer, the performer may be set one of a number of different ways, and a server method is selected.

For further details on Steps 2 and 3, please see the online event referenced in the introduction of this article.

The Workflow Method versus the SBO

If we consider a number of the actions implemented in the eDK, we begin to see the commonalities and the differences between them. For example, let’s compare the "create eRoom" and "create database row" actions, considering the parameters of each. When we are creating an eRoom, we must designate the name of the new eRoom and whether it is to be created from a template or as a blank room. Room names and template names may be fixed, designated through attribute values of other workflow packages, or may be otherwise "computed." By contrast when creating a database row, we will specify the values of the fields of that newly-created record. And again, some values may be fixed, based on attribute values (perhaps different from attribute values used for eRoom naming, for example), or determined through some other mechanism. But even with these significant differences, the two actions share a number of things in common. First, both creations are directed at a particular "location" in eRoom, the create eRoom request being targeted at a particular facility, the create DB row being targeted at a specific database. That is, the request has a target. Second, each request will dispatch a request to the eRoom server via HTTP that will include authentication credentials and will process some response.

The functionality that is in common from one action to another is encapsulated in the eDK’s Service-based Business Object. The SBO includes a constructor that allows the caller of the SBO to designate an eRoom target URL. It also includes private methods that implement the HTTP based communication with the eRoom server. And finally, it includes a public method for each of the functions offered in the eDK (i.e. createRoom, createDBRow, etc.). These methods take in atomic values as parameters (for example, names for room creation), and are blind to the details of any specific workflow (in fact, the SBO may be used entirely outside of the context of workflow—but that is a topic for another month). Under normal circumstances the business object remains unchanged by the workflow developer.

The functionality that differs from one action to another, or may even differ for the same action from one workflow template to another, is implemented in the workflow method Java classes. In the eDK, these classes are named with a WFM (WorkFlow Method) at the end. In these Java classes, the developer will make workflow template-specific adjustments, accessing packages, content attributes, and other elements specific to the workflow template they are designing. In the workflow method, all package manipulation is done, the action parameters are computed, the SBO is instanced, and the appropriate method is invoked.

When implementing a specific workflow template, we recommend that a new Java package be created to contain the WFM Java classes specific to it. An example of that can be seen in the New Product Development (NPD) sample shipped with the eDK. While the com.documentum.eroom.wfactions package contains all of the base WFM classes as described in the eDK help files, the NPDSample package contains customized versions of four of these base WFM classes.

Workflow Methods

Before we examine the source code for one of the eDK workflow methods it is worth describing how the WFM classes are invoked. When the workflow engine invokes the Java class, it does so with a number of command line arguments. The invocation signature is as follows:


-docbase_name <docbase name> -user <username task performer> -packageId <object ID of the task> 
			-ticket <login ticket> -mode 0

That is, the docbase name will be obtained by reading the value of args[1], the username by accessing args[3] and so on.

Once these arguments have been used to establish a DFC-based connection to the docbase, and the task has been obtained, generally four things will occur.

  • Work items are obtained from the work package
  • Action parameters are determined or computed
  • The SBO is instanced, and the appropriate method is called
  • Output work items are adjusted.

The Create eRoom Workflow Method

Figure 2 shows the portion of the CreateERoomWFM code that implements the four steps described above.


 
/** [***** Customize Here *****]
 * Get the package, namely a single content object. Here, we will retrieve
 * the package via name (as assigned in the workflow template). 
 */
String sPackageName = "CSDocument";
IDfSysObject oSysObject = oWorkitemGetter.getNamedPackage(session, oWorkitem, sPackageName);
if ( oSysObject == null ) {
    System.out.println(sErrorPrefix + "unable to obtain the content object required");
    return;
}

/** [***** Customize Here *****]
 * "Compute" the values of the parameters to be passed to the SBO method.
 */
String sDisplayName = oSysObject.getString("object_name") ;
String sURLName = stripString( sDisplayName );
String  eRoomContainerUrl = oSysObject.getString("title") ;
String sDescription = oSysObject.getString("subject") ;
if ( sDescription.length() == 0 || sDescription.equals("") ) {
    sDescription = "This eRoom has been automatically generated as part of a workflow";
}
String sTemplateName = "";
if (oSysObject.getKeywordsCount() > 0 ) {
    sTemplateName = oSysObject.getKeywords(0);
		    }

IERItemCreator oERItemCreator = new ERItemCreator(eRoomContainerUrl );

/** Call the service-based business object ERItemCreator to handle the
 *  request for creating the eRoom room.
 */
IDfSysObject oNewERoom;
oNewERoom = oERItemCreator.createERoom(session, sURLName, 
		sDisplayName, sDescription, sTemplateName, eRoomContainerUrl );
if (oNewERoom != null)
{
    // Make the new eroom_reference object(an eRoom) available as a work package
    IDfList oList = new DfList();   // create a new package object
    try {
        oList.removeAll();
        oList.appendId(oNewERoom.getChronicleId());
        /** [***** Customize here *****]
         *  Add the newly created eRoom as an output port work item. The package name
         *  "ERRoom", must match that designated in the workflow template
         */
        oWorkitem.addPackage("ERRoom", "eroom_reference", oList);
        /**
         * Assuming that the content server document package was only here for this
         * action and is not required by the subsequent task, remove it. 
         */
        oWorkitem.removePackage( sPackageName );
    }

    catch (Exception e)
    { ... }

    // Complete the work item
    oWorkitem.complete();
    System.out.println("WFA (CreateERoom) WorkItem Complete...");
}

First, the work item expected by the WFM is obtained by name. For illustrative purposes we are expecting a content object that has the action parameters stored in various attribute values.

Next, we "look up" or "calculate" the action parameters. In this case, the target eRoom URL is obtained from the "object name" attribute of the content object, the new room name from the "title" attribute and if present, the eRoom template name from the first keyword. Note that this illustration is contrived and was implemented this way in the eDK for ease of installation. More typical will be a case where the workflow developer knows that target facility URL at design time and fixes it here, the template name is likely determined through a lookup table and the name is likely a combination of a fixed literal with some attribute value appended (i.e. "10Q Development Room for Filing Period Ending June 30, 2004").

Then the SBO is instanced with the target URL provided and the createERoom method invoked with the correct parameter values.

Finally, output packages are manipulated, in this case adding a package with a reference to the newly created eRoom.

Conclusion

This article has taken a close look at how event-triggered collaboration can be driven from a Documentum workflow through the use of the eDK for Workflow. We have carefully examined the structure of the primary code components of the eDK, namely the workflow methods and the SBO delivered in the com.documentum.eroom.wfactions Java package. Again, developers are encouraged to augment this article by viewing the eDK online event at http://www.documentum.com/events/2004/Q2/05_05_04_REC_eRoom_eDK.htm.