Product: Livelink ECM Enterprise Server Version: 9.5.0.1, 9.6.0, 9.7.

.x Task/Topic: Administration Audience: Administrators Platform: All Document ID: 500040 Updated: April 24, 2008

Best Practices

Advanced Workflow Techniques

Eric Saavedra

Best Practices

Advanced Workflow Techniques

Document Title

Contents
Background ................................................................................................................. 1 Purpose .................................................................................................................. 1 Prerequisites........................................................................................................... 1 Design Overview ......................................................................................................... 2 Configuration Details .............................................................................................. 2 Example Map ................................................................................................... 3 Example Map Attributes ................................................................................... 3 Configuring the XML Workflow Extensions Module ............................................... 4 XML Export Step ..................................................................................................... 4 Modify Step ............................................................................................................. 6 Special Note ........................................................................................................... 9

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

Background
When dealing with document automation using Livelink ECM Enterprise Server (Livelink) workflow, a significant shortcoming of the application presents itself when dealing with documents copied into the workflow attachments volume. While certain functionality is handled automatically by the system (such as selecting the attached document for renditioning to PDF when using the eSign module); it is not always possible for the designer to configure the workflow to perform other dynamic functionality (for example, moving a copied document in the attachments package to another folder). The problem with standard functionality is once Livelink copies a document into the workflow attachments package, there is no longer a reference to that copied document. This is because copying a document creates a new object in Livelink, which has a new object ID. To get around this workflow designers are typically forced to require the end-user (workflow task performer) to select the document using an Item Reference attribute after the document has been copied into the workflow attachments package. Once the document is selected, then the workflow designer can act on the document programmatically in a number of ways (move the document, add or modify categories to the document, alter permissions, rename the document, purge versions of the document, etc.). A better design would be for the system to place the copied documents object ID into an Item Reference attribute automatically, thus avoiding user intervention and potential errors.

Purpose
The purpose of this document is to provide a technique for automatically capturing the object ID of a copied document into an Item Reference attribute within a workflow. The document illustrates the basic technique leveraging XML Workflow Extensions functionality. This technique can be extended to handle more complex scenarios (such as multiple documents).

Prerequisites
XML Workflow Extensions Module v3.2.0 or above installed eSign Module installed (or other mechanism for initiating a workflow from a document) Familiarity with the Item Reference workflow attribute and Item Handler workflow step functionality in Livelink workflow Knowledge of XML and XPath language specifications

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

Design Overview
There are a number of different ways we can conceive of to obtain the object ID of the copied document in Livelink. At the lowest level, we know that the information we need is maintained and stored in the Livelink database in the DTREE table. While we know this information is available, it is actually difficult to get to. Leaving aside the need to design a way to execute a SQL statement within a workflow, a number of questions arise pertaining to how we identify the exact row in the database we want to query: How do we select the correct row? By document name? What is the document name and how do we get it? How about by looking for the attachments folder and getting all its contents. Then how do we get the object ID of the attachments folder?

Answering these questions using out-of-the-box functionality is not always possible and makes it difficult to use a database lookup to obtain the information. Fortunately, the XML Workflow Extensions module helps us in a couple of ways: The module inherently exposes the workflow attachments object ID to the workflow designer (using replacement tags or built-in functionality on the steps) The module allows us to use XML Export functionality to export any item in Livelink (including the workflows attachment folder) The module provides functionality to traverse or navigate the exported XML file using either XSLT to transform the file or XPath query language to navigate the XML file

With these capabilities, we are able to do away with the SQL approach and leverage Livelinks XML facilities. Our approach then is the following: 1. Add a document to the workflow attachments folder. This can be done fully automatically through Livelinks Initiate Workflow function menu option on a document, or partially automatically by requesting the workflow user to specify the document in an Item Reference attribute and then copying the document into the workflow attachments folder using an Item Handler step. 2. Use the XML Export step to export the workflow attachments folder and its contents after the document has been copied in. 3. Use the Modify step to extract the attached document Object ID and copy it to an Item Reference workflow attribute. The following section describes how to create and configure these steps in detail.

Configuration Details
In this section, we discuss the configuration details of a workflow that captures a copied documents object ID into a workflow Item Reference attribute. The workflow map is illustrated in the next section, along with some basic settings for the workflow.

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

Example Map
The following screenshot illustrates the map used for this lesson:

Figure 1 Workflow map

While the test map was created using an Item Handler step to copy a document into the workflow attachments, the same method will apply if you initiate a workflow from a document using the Function menu and choose the Initiate Workflow option.

Example Map Attributes

The following screenshot illustrates the default attributes that are part of this workflow definition:

Figure 2 Workflow attributes

Note that there are two Item Reference attributes in this workflow map. The first attribute Source Document is used to identify the initial document from within Livelink. This original document will be copied into the workflow using an Item Handler step after the workflow is initiated. The second attribute Document Under Review will be populated using the XML Technique described below and will contain the object ID of the copied document.

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

Configuring the XML Workflow Extensions Module

Before implementing the XML Export functionality, you must first configure the module on the Administrative Pages. The XML Workflow Extensions module uses the servers file system as a temporary storage facility and most functionality is achieved by writing content to the temporary location, working on that content, and then importing the content back into Livelink. In order for this behavior to function properly, the module must be configured to use placeholders to define output locations and set permissions on the file server. Using placeholders creates a layer of abstraction that promotes portability, flexibility, and provides a more secure configuration, as well as supporting more complex architectural environments (for example, in Livelink clustered environments, the output path might be a common location defined using UNC mapping like \\shared_folder\xml_output). For purposes of the technique described in this document, we only need to configure an output location for the XML files. Please refer to the XML Workflow Extensions Admin Guide for detailed description of these fields.

Figure 3 XML Workflow Extension configuration page

NOTE: Global Placeholder name - This name will be used in the subsequent configurations in the sections below. Also, note that the placeholder name is plain text, but when referencing the placeholder you must use square brackets (the [ and ] characters) when referencing the placeholder.

XML Export Step

When Livelink exports data by XML, there is a large amount of data that can be exported, including: Node Information: information pertaining to the Livelink object being exported, such as the items parent (or container object), permissions, create date, modified date, etc. Version Information: if the object has multiple versions, then each of the version information can be exported

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

Attribute Information: if the object has been tagged with Livelink metadata (in the form of category/attribute information), then that information can be exported as well

This is just a sampling of what information can be exported using Livelinks XML Export functionality. For a complete reference, refer to the document Livelink Enterprise Server XML Export and Import Guide located on the Knowledge Center. The XML Workflow Extensions XML Export step functions by executing an XML Export command to Livelink and writes the results to a file onto the file server. As described in the XML Export and Import Guide, when exporting content using a URL you can provide a series of optional parameters to tailor your results for particular needs. For example, you may want to export Livelink content from a development instance that will be imported into a production instance. This action would require specifying the scope, nodeInfo, attributeInfo, versionInfo, and content parameters to provide the appropriate level of detailed information for Livelink to successfully import the XML. The XML Export step follows this same approach by allowing the workflow designer to specify the export parameters (in the Export Parameter section) and which item should be exported (in the Export Node Id section). For our purposes, we only want a limited amount of information to appear in the export file. More information will mean a more complex XPath query in the next step. So only two parameters are set in the Export Parameter section: Scope, which is set to sub (but could have also been set to one, which is probably more appropriate) NodeInfo is checked to ensure the objects document information is exported

All other parameters are left unchecked or set to None. See the screenshot below for an example of the settings:

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

Figure 4 XML Export step

For the Export Node Id section, simply click the Workflow Attachment radio button to specify that the Workflow Attachment folder be exported. The final configuration setting is to specify the name of the export file that will be produced. Care should be given when naming files since you must consider multiple workflows performing the same operation. To prevent files being overwritten, unique names must be given for the export files so that they are available in the next step. In the example documented here we use the built-in replacement tags [mapid] and [subworkid] provided by the XML Workflow Extensions module to specify the unique workflow ID and sub-workflow ID respectively. Note that the destination location for this file is specified using the global replacement tag [output] as defined in Configuring the XML Workflow Extensions Module section

Modify Step
The Modify Step is a highly flexible step that provides the capability to copy data from one location to another. The most basic example is to copy form field data to a workflow attribute field. Other examples include updating the workflow title from a form field value, or creating complex values by concatenating workflow attribute values with form field values and system information and setting a form field value.

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

For our purposes we will be picking up the XML file produced from the XML Export step above and using an XPath query to extract the attached documents object ID from the XML. In order to achieve this it is important to understand how the XPath language works, as well as understand how Livelinks XML is structured. The XML Path Language (XPath) is a W3C Recommendation that defines how to address parts of an XML document and is used by both XSLT and XPointer specifications for accessing and manipulating XML documents. Full documentation can be found on the web at http://www.w3.org/TR/xpath. A good tutorial can be found at http://www.w3schools.com/xpath/default.asp. In short, the XPath language allows the designer to navigate an XML documents node hierarchy by using a path syntax similar to a UNIX file system (/rootnode/nodename/nodename). Before we can fully utilize the XPath language, we must understand the structure of the Livelink export file. The following is an example XML file that is output from the XML Export step:
<?xml version="1.0" encoding="ISO-8859-1"?> <livelink appversion='9.7.0' src='XmlExport'> <llnode created='2008-02-27T11:19:54' createdby='528393' createdbyname='Saavedra, Eric' description='' id='546805' modified='200803-11T17:47:01' name='Get Attachment DocID Map-546807' objname='Workflow Attachments' objtype='154' ownedby='-3' ownedbyname='&lt;Unknown&gt;' parentid='2068' size='1'> <Nickname domain=''></Nickname> <node cacheexpiration='0' catalog='0' childcount='1' createdate='200802-27T11:19:54' createdby='528393' groupid='-3' groupperm='128' id='546805' maxversion='-1' modifydate='2008-03-11T17:47:01' name='Get Attachment DocID Map-546807' originalid='0' originalvolid='0' parentid='2068' reserved='0' reservedby='0' subtype='154' systemperm='16777215' userid='-3' userperm='128' versionnum='0' volumeid='-2068' worldperm='258207'> </node> <llnode created='2008-02-27T10:05:56' createdby='528393' createdbyname='Saavedra, Eric' description='' id='547127' mimetype='application/msword' modified='2008-03-11T17:47:01' name='sample.doc' objname='Document' objtype='144' ownedby='-3' ownedbyname='&lt;Unknown&gt;' parentid='546805' size='91136' versionnum='1'> <Nickname domain=''></Nickname> <node cacheexpiration='0' catalog='0' childcount='0' createdate='2008-02-27T10:05:56' createdby='528393' extendeddata='A&lt;1,?,&apos;Confidential&apos;=0&gt;' groupid='-3' groupperm='128' id='547127' maxversion='-1' modifydate='2008-0311T17:47:01' name='sample.doc' originalid='0' originalvolid='0' parentid='546805' reserved='0' reservedby='0' subtype='144' systemperm='16777215' userid='-3' userperm='128' versionnum='1' volumeid='2068' worldperm='36995'> </node> </llnode> </llnode> </livelink>

Figure 5 Example XML output

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

What is important to recognize in the example above is the structure of the XML. All XML exports from Livelink will have a root node called livelink. Within this root node will be child nodes typically named llnode. If you analyze the sample closely you will notice that the structure of the XML document is as follows:
<livelink> <llnode> <nickname></nickname> <node></node> <llnode> <nickname></nickname> <node></node> </llnode> </llnode> </livelink> Represents the root Represents the workflow attachments object Nickname for workflow attachments Node info for workflow attachments object Represents child object inside of WF attach Nickname for child object Node info for child object

Figure 6 XML Document Structure

The XPath language allows us to reference these node elements using a simple path structure like the following: /livelink/llnode/llnode/node Once we have traversed the XML tree using the path syntax, we can retrieve the value of an attribute by using the at sign symbol (@). So looking out the example XML in figure 5 above in the node named node there are several attributes defined (cacheexpiration, catalog, childcount, createdate, etc.). We are interested in the attribute named id, so we reference this like the following: /livelink/llnode/llnode/node/@id which translates to In the root node named livelink, in the node named llnode, in the child node named llnode, in the child node named node, get the value of the attribute named id. Once the XPath is defined, the rest of the configuration can be implemented for the Modify step. In order to execute the XPath query against the correct XML file, we must configure the Modify step to pick up the file named in the previous XML Export step. This is where we take advantage of using replacement tags specific to the workflow instance to name the files. In the Copy From section select the XPath radio button and type in the same file specification used in the XML Export step. A requirement of the XPath syntax in the Workflow Extensions module is to specify the file name and location in the XPath syntax directly. This results in our specifying the file location twice, once in the File Name field and again within the XPath expression. In the screenshot below note the specific syntax of the XPath expression, particularly the use of curly braces to encapsulate the file parameter and the Xpath parameter:

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

Figure 7 Modify step

After configuring the Copy From section, specify where you want to results of the XPath query to go in the Copy To section. In this case we will copy the object ID of the document in the attachments into the Item Reference workflow attribute that was defined in section 0 above.

Special Note
If you have paid close attention to the instructions in Modify Step section and compared that to the screenshots, you will no doubt notice that the XPath described in the instructions are not the same as the XPath that is illustrated in the screenshot. What happened? If you observe closely at the example XML output in figure 5 above you will see that the object ID attribute (named id) is in both the llnode node for the copied document and in the node node! Since the id attribute is in both the llnode node and the node node, either syntax will work.

Champion Toolkit Document

www.opentext.com

Best Practices

Advanced Workflow Techniques

Document Title

Sales www.opentext.com
info@opentext.com

Americas United States

100 Tri-State Intl Parkway Lincolnshire, IL USA 60069 Phone: 847-267-9330 Fax: 847-267-9332

Europe Germany
Technopark 2 Werner-von-Siemens-Ring 20 D-85630 Grasbrunn Germany Phone: +49 89 4629 0 Fax: +49 89 4629 1199

Asia/Pacific United Kingdom Australia

Level 23 100 Miller St. North Sydney NSW 2060 Australia Phone: +61-2-9026-3400 Fax: +61-2-9026-3455

North America Sales

1-800-499-6544

International Sales
+800-4996-5440

Grosvenor House Horseshoe Crescent Beaconsfield, Buckinghamshire United Kingdom HP9 1LJ Phone: +44 1494 679700 Fax: +44 1494 679707

If you are an Open Text partner or customer, visit online.opentext.com for more information about this and other Open Text solutions. Open Text is a publicly traded company on the NASDAQ (OTEX) and the TSX (OTC).
Copyright 2008 by Open Text Corporation. Open Text, Livelink, Livelink ECM, and Great Minds Working Together are trademarks or registered trademarks of Open Text Corporation. All other trademarks or registered trademarks are the property of their respective owners. All rights reserved.

www.opentext.com

10