Workflow Guide

CHAPTER 9

Workflow Tag Library

This chapter describes how to use the JSP tags contained in WorkflowTag.jar.

For more information    For background information, see the chapter on using the exteNd Director tag libraries in Developing exteNd Director Applications.

These are the JSP tags:

 
Top of page

addressee

Description

Specifies a workitem addressee that is passed to the tag within which it is nested. This tag is a nested tag. It can only be used as the child of another tag.

The parent tag must have a method of signature addAddressee(String x). The addressee tag calls that method on the parent tag and passes in the addressee.

See also

getWorklist

Syntax

  <prefix:addressee>addressee</>

Example

This example shows how to specify addressee nested tags in the getWorklist parent tag:

  <epwf:getWorkList id="example" iterate="true" >
  
  <epwf:addressee>user1</epwf:addressee>
  <epwf:addressee>user2</epwf:addressee>
  
   Activity = <%=activity%><br/>
   workitemid = <%=workitemid%><br/>
   name = <%=name%><br/>
   lockedby = <%=lockedby%><br/>
   message = <%=message%><br/>
  </epwf:getWorkList>

 
Top of page

createProperty

Description

Creates an EbiProperty object for a workitem or document using the specified values for property name, value, and type.

If docName is provided, the property object is created for the document. The EbiProperty object is returned in a default scripting variable called newProperty, or the name provided in the id attribute.

This tag wraps a version of createProperty() on the EbiWorkitemDelegate interface.

Syntax

  <prefix:createProperty workitemID="workitemID" docName="docName" propName="propName" value="value" type= "type" immutable="immutable" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

docName

No

Yes

Name of the document to which to add the property

propName

Yes

Yes

Name for the property

value

Yes

Yes

Property value

type

Yes

Yes

Data type for the property value; for valid entries, see EbiProperty in the API documentation

immutable

No

Yes

Boolean value (true or false) that specifies whether the property is immutable; default is false

id

No

No

Name of the variable in which to store the returned property object; default name is newProperty

Example

This example creates a workitem property and gets the property name from the returned object:

  <epwf:createProperty id="example" workitemID="<%=wid.getWorkitem().getId()%>" propName="wiproperty2" value="testvalue" type="string" / >
  
  <% com.sssw.wf.api.EbiProperty prop = (com.sssw.wf.api.EbiProperty)pageContext.getAttribute("example");%><br/>
  <%=prop.getPropertyName()%>

 
Top of page

forwardWorkitem

Description

Forwards a workitem to the next activity and returns a boolean representing whether the attempt to forward was successful.

The value is returned on a scripting variable called wi_forward or the name provided in the id attribute.

This tag wraps the forward() method on the EbiQueueDelegate interface.

Syntax

  <prefix:forwardWorkitem workitemID="workitemID" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Current workitem ID

id

No

No

Name of the variable in which to store the return value; default name is wi_forward

Example

  <epwf:forwardWorkitem id="forward" workitemID='<%=x%>' />
      <%=pageContext.getAttribute("forward") %> 

 
Top of page

getDocument

Description

Returns a document for a specified workitem ID. By default it returns the document as an object of type org.w3c.dom.Document. If returnDOM is set to false, the document is returned as a String. The value is returned on a scripting variable called wi_document or the name provided in the id attribute.

This tag wraps getDocument() on the EbiWorkitemDelegate interface.

Syntax

  <prefix:getDocument workitemID="workitemID" docName="docName" returnDOM="returnDOM" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

docName

Yes

Yes

Name of the document

returnDOM

No

Yes

Boolean that returns the document as an object of type org.w3c.dom.Document (true) or as a String (false); the default is false

id

No

No

Name of the variable in which to store the return value; default name is wi_document

Example

This example gets a workitem document as a String:

  <epwf:getDocument id="example" workitemID="<%=wid.getWorkitem().getId()%>" docName="mydoc1" returnDOM="false" />
  <%=pageContext.getAttribute("example")%>

 
Top of page

getProcessList

Description

Retrieves a list of available workflow processes. Returns the list as a DOM or as variables that can be set within the tag. The result is returned using a scripting variable called processList or by a value set in the id attribute.

Tag options

Do one of the following:

This tag wraps the getProcessDefinitions() method on the EbiWorkflowEngineDelegate interface.

Syntax

  <prefix:getProcessList returnDOM="returnDOM" iterate="iterate" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

returnDOM

No

Yes

Boolean value (true or false) that indicates whether to return the list as a DOM (true) or as an XML String (false)

The DOM adheres to workflow-process_4_0.dtd

NOTE:   If returnDOM is set to true, the iterate attribute must be set to false

iterate

No

Yes

Boolean value (true or false) that indicates whether this tag will operate as a body tag so that each row can be processed separately; default value is false

If the iterate attribute is set to true, the following values can be accessed from within the getProcessList tag:

  • processid

  • name

Each of these variables has a scope of NESTED

NOTE:   When the iterate attribute is set to true, returnDOM is not used

id

No

No

Name of the variable in which to store the returned boolean value; the default name is processList

Example

This example gets a process list using iterated nested variables:

      <epwf:getProcessList iterate="true" >
          ProcessID = <%=processid%><br/>
          Name = <%=name%><br/>
      </epwf:getProcessList>

 
Top of page

getProperty

Description

Gets a property object of type EbiProperty for a workitem or (if docName is provided) for a document. The value is returned on a scripting variable called property or the name provided in the id attribute.

This tag wraps the getProperty() method on the EbiWorkitemDelegate interface.

Syntax

  <prefix:getProperty workitemID="workitemID" propName="propName" docName="docName" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

propName

Yes

Yes

Name of the property

docName

No

Yes

If this is a document property, the name of the document associated with the property

id

No

No

Name of the variable in which to store the returned property object; the default name is property

Example

This example gets a workitem property name and value from the returned property object:

  <epwf:getProperty id="example" workitemID="<%=wid.getWorkitem().getId()%>" propName="wiproperty" />
  
  <%=((com.sssw.wf.api.EbiProperty)pageContext.getAttribute("example")).getPropertyName()%> = name
  <%=((com.sssw.wf.api.EbiProperty)pageContext.getAttribute("example")).getPropertyValue()%> = value

 
Top of page

getPropertyList

Description

Returns a List (java.util.List) of EbiProperty objects for a given workitem and/or related document. Either the forWorkitem or forDocuments attribute must be set to true. If both are set to true, all properties will be returned for the workitem and all related documents. List is returned on a scripting variable called propertyList or the name provided in the id attribute.

This tag wraps the getAllProperties(), getWorkitemProperties, and getDocumentProperties on the EbiWorkitemDelegate interface, depending on the attributes provided.

Syntax

  <prefix:getPropertyList workitemID="workitemID" forWorkitem="forWorkitem" forDocuments="forDocuments" docName="docName" iterate="iterate" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

forWorkitem

No

Yes

Boolean value that specifies workitem properties; if this attribute and the forDocuments attribute are true and no docName is provided, all workitem properties are returned

forDocuments

No

Yes

Boolean value that specifies document properties; if this attribute is true, you can also set the docName attribute

docName

No

Yes

Name of the document whose properties you want returned (only the properties for the specified document are returned); if you do not specify a docName, all properties are returned

iterate

No

Yes

Boolean value (true or false) that indicates whether this tag will operate as a body tag so that each row can be processed separately

The default is false, which returns a List object on the scripting variable named propertyList or the name provided in the id attribute; List contains objects of type EbiProperty

If iterate is set to true, the following values will be available in the body tag:

  • name: the property name

  • type: the property type

  • value: the property value

  • docName: the name of the document to which the property is related

Each of these variables has a scope of NESTED

id

No

No

Name of the variable in which to store the List; the default name is propertyList

Examples

Property list using iterated nested variables:

  <epwf:getPropertyList id="example1" iterate="true" workitemID="<%=wid.getWorkitem().getId()%>" forWorkitem="true" forDocuments="true" >
   name = <%=name%><br/>
   value = <%=value%><br/>
   docName = <%=docName%><br/>
  </epwf:getPropertyList>

Property list as a Java List:

  <epwf:getPropertyList id="example2" iterate="false" workitemID="<%=wid.getWorkitem().getId()%>" forWorkitem="true" forDocuments="true" />
  <%=example2.size()%> = size

 
Top of page

getQueueStatus

Description

Checks the status of the workflow engine. Returns the word running, shutdown, or suspended. The value is returned on a scripting variable called queueStatus or the name provided in the id attribute.

This tag wraps getQueueStatus on the EbiQueueDelgate interface.

Syntax

  <prefix:getQueueStatus id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

id

No

No

Name of the variable in which to store the return value; the default name is queueStatus

Example

  <epwf:getQueueStatus id="queue" />
      <%=pageContext.getAttribute("queue") %>

 
Top of page

getWorkitem

Description

Returns an object of type EbiWorkitemDelegate for the specified workitemID. The value is returned on a scripting variable called workitem or the name provided in the id attribute.

This tag wraps getWorkitem() on the EbiQueueDelgate interface.

Syntax

  <prefix:getWorkitem workitemID="workitemID" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

id

No

No

Name of the variable in which to store the return value; the default name is workitem

Example

  <epwf:getWorkitem id="get" workitemID='<%=x%>' />
      <%=pageContext.getAttribute("get") %>

 
Top of page

getWorklist

Description

Retrieves a list of workitems from a specified queue. The result is returned using a default scripting variable called workList or by a value set in the id attribute.

You can embed the workitem addressee in this tag using the addressee tag.

This tag wraps a version of getWorklist() on the EbiQueueDelegate interface. The method version used depends on which tag attributes are provided.

Tag options

Two steps are required:

Step

What to do

1

First make sure one of the following is true:

  • The user is logged in so that the workitem list can be retrieved from the workflow context.

    OR

  • The activity attribute is set.

    OR

  • The addressee or name attribute is set. The ignoreSuspended attribute is used in this instance, with default value true. To pass the addressee you can nest the addressee tag inside the getWorklist tag.

2

Then do one of the following:

  • Set the returnDOM attribute to true (return as XML DOM) or false (return as XML string). When this attribute is set, the iterate attribute must be set to false.

    OR

  • Set iterate to true. The results are returned via variables in the body tag. In this case, returnDOM is not used.

    OR

  • Set returnList to true. In this case a list of EbiWorkitemDelegate objects is returned in an object of type java.util.List.

The getWorklist tag wraps a version of getWorklist() on the EbiQueueDelegate interface. The method version used depends on which tag attributes are provided.

Syntax

  <prefix:getWorklist activity="activity" name="name" returnDOM="returnDOM" returnList="returnList" iterate= "iterate" priority="priority" ignoreSuspended="ignoreSuspended" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

activity

No

Yes

Name of the activity; this corresponds to the Name property for the activity defined in the Workflow Modeler

name

No

Yes

Name of the workitem; this corresponds to the WorkName property defined for the process in the Workflow Modeler

returnDOM

No

Yes

Boolean value (true or false) that indicates whether or not to return the list as a DOM (true) or as an XML String (false)

The DOM adheres to workflow-worklist_4_0.dtd

If returnDOM is set to true, the iterate attribute must be set to false

returnList

No

Yes

A boolean value (true or false) that when set to true returns a list of EbiWorkitemDelegate objects as an object of type java.util.List

iterate

No

Yes

A boolean value (true or false) that indicates whether this tag will operate as a body tag so that each row can be processed separately; the default value is false

If the iterate attribute is set to true, the following values can be accessed from within the getWorkList tag:

  • activity

  • name

  • workitemid

  • message

  • lockedby

Each of these variables has a scope of NESTED

NOTE:   When the iterate attribute is set to true, returnDOM is not used

priority

No

Yes

Provided to support user-implemented priority schemes; not supported in the current version

ignoreSuspended

No

Yes

Boolean value (true or false) that indicates whether to ignore suspended activities in the returned list

id

No

No

Name of the variable in which to store the result; the default name is workList

Examples

Worklist using iterated nested variables:

  <epwf:getWorkList iterate="true" >
          Activity = <%=activity%><br/>
          Name = <%=name%><br/>
          Workitemid = <%=workitemid%><br/>
          <%! String x;%> 
          <% x = (String) pageContext.getAttribute("workitemid"); %>
          Message = <%=message%><br/>
          Lockedby = <%=lockedby%><br/>
      </epwf:getWorkList>

Worklist as a DOM:

  <epwf:getWorkList id="list" iterate="false" returnDOM="true" />
  // access the DOM
  xml string = <%org.w3c.dom.Document doc = (org.w3c.dom.Document) pageContext.getAttribute("list");%>
  	 	 <%=doc.getFirstChild().getNodeName()%>

Worklist as a Java List object:

  <epwf:getWorkList id="list2" returnList="true" />
  <% for (int x=0;x<list2.size();x++){
  	 // parse the List
  	 com.sssw.wf.client.EbiWorkitemDelegate wid = (com.sssw.wf.client.EbiWorkitemDelegate) list2.get(x); %>
  	 Wid <%=x%> activity name = <%=wid.getActivityName()%>
  <% } %>

Worklist as an XML string:

  <epwf:getWorkList id="list3" iterate="false" returnDOM="false" />
  xml string = <%=(String) pageContext.getAttribute("list3")%>

Worklist using an embedded addressee tag:

  <epwf:getWorkList iterate="true" >
  <epwf:addressee>sample</epwf:addressee>
   Activity = <%=activity%><br/>
   workitemid = <%=workitemid%><br/>
   name = <%=name%><br/>
   lockedby = <%=lockedby%><br/>
   message = <%=message%><br/>
  </epwf:getWorkList>

 
Top of page

hasDocument

Description

Checks whether a document exists for workitem and returns a boolean. The value is returned on a scripting variable called hasDocument or the name provided in the id attribute.

This tag wraps hasDocument() on the EbiWorkitemDelegate interface.

Syntax

  <prefix:hasDocument workitemID="workitemID" docName="docName" returnDOM="returnDOM" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

docName

Yes

Yes

Name of the document

returnDOM

No

Yes

Boolean that returns the document as an object of type org.w3c.dom.Document (true) or as a String (false); default is false

id

No

No

Name of the variable in which to store the return value; the default name is hasDocument

Example

  <epwf:hasDocument workitemID="<%=wid.getWorkitem().getId()%>" docName="mydocument" />
  <%=pageContext.getAttribute("hasDocument")%>

 
Top of page

hasProperty

Description

Checks whether a property exists for a workitem or (if docName is provided) for a document. Returns a boolean. The value is returned on a scripting variable called hasProperty or the name provided in the id attribute.

This tag wraps hasProperty() and hasDocument Property on the EbiWorkitemDelegate interface.

Syntax

  <prefix:hasProperty workitemID="workitemID" docName="docName" propName="propName" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

docName

No

Yes

Name of the document whose property you want to check; use only for document properties

propName

Yes

Yes

Name of the property

id

No

No

Name of the variable in which to store the return value; the default name is hasProperty

Example

  <epwf:hasProperty id="status" workitemID="<%=wid.getWorkitem().getId()%>" propName="wiproperty2" />
  <%=pageContext.getAttribute("status")%>

 
Top of page

isDocumentLocked

Description

Checks whether a workitem document is locked—and if the userID attribute is set, also checks whether the document is locked by a particular user. Returns a boolean. The value is returned on a scripting variable called doc_islocked or the name provided in the id attribute.

This tag wraps isDocumentLocked() or isDocumentLockedBy() on the EbiWorkitemDelegate interface.

Syntax

  <prefix:isDocumentLocked workitemID="workitemID" docName="docName" userID ="userID" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

docName

Yes

Yes

Name of the document

userID

No

Yes

UserID; if not set, the tag checks the document status only

id

No

No

Name of the variable in which to store the return value; the default name is doc_isLocked

Example

  <epwf:isDocumentLocked id="doclocked" workitemID='<%=x%>' docName="doc1" />
      <%=pageContext.getAttribute("doclocked") %> <br/>

 
Top of page

isWorkitemLocked

Description

Checks whether a workitem is locked—and if the userID attribute is set, also checks whether the workitem is locked by a particular user. Returns a boolean. The value is returned on a scripting variable called wi_islocked or the name provided in the id attribute.

This tag wraps isLocked() or isLockedBy() on the EbiWorkitemDelegate interface.

Syntax

  <prefix:isWorkitemLocked workitemID="workitemID" userID ="userID" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

userID

No

Yes

UserID to check; if not set, the tag checks the workitem status only

id

No

No

Name of the variable in which to store the return value; the default name is wi_isLocked

Example

  <epwf:isWorkitemLocked id="worklock" workitemID='<%=x%>' />
      <%=pageContext.getAttribute("worklock") %> <br/>

 
Top of page

setProperty

Description

Stores an existing EbiProperty object for a workitem (or for a document if docName is provided) using the specified EbiProperty object. Returns a boolean representing success or failure. Return value is stored in a scripting variable called setProperty or the name provided in the id attribute.

If the userID attribute is not specified, the current user is used.

This tag wraps setProperty() and setDocumentProperty() on the EbiWorkitemDelegate interface.

Syntax

  <prefix:setProperty workitemID="workitemID" property="property" forDocument="forDocument" userID ="userID" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

property

Yes

Yes

Name of the property to add

forDocument

No

Yes

Boolean value that specifies whether the property is a document property; the default is false

NOTE:   The property must have been previously associated with the specified document; see createProperty

userID

No

Yes

UserID

If set, the tag sets the document or workitem property for the user; otherwise, it uses the current context

id

No

No

Name of the variable in which to store the return value; the default name is setProperty

Example

This example sets a property from an attribute provided on the page:

  <epwf:setProperty id="set" workitemID="<%=wid.getWorkitem().getId()%>" property="<%=(com.sssw.wf.api.EbiProperty)pageContext.getAttribute("myatt")%>" / >
  <%=pageContext.getAttribute("set")%>

 
Top of page

startProcess

Description

Starts a workflow process with a specified processID. Starts the process with a document if the docName attribute is specified, as well as one of the following attributes representing the document:

Returns an int representing success or failure:

Value

Meaning

0

Success

-1

Engine not running; unable to start process

-2

Process definition not found

-3

Process suspended

The value is returned on a scripting variable called processStarted or the name provided in the id attribute.

This tag wraps startProcess() on the EbiWorkflowEngineDelegate interface.

Syntax

  <prefix:startProcess processID="processID" docName="docName" document="document" docstring="docstring" url ="url" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

processID

Yes

Yes

Workitem ID

docName

No

Yes

Name of the starting document

document

No

Yes

Starting document, as a DOM

docstring

No

Yes

Starting document, as a String

url

No

Yes

URL to the starting document (DOM)

id

No

No

Name of the variable in which to store the return int value; the default name is processStarted

Example

  <epwf:startProcess id ="start" processID="c373e9ea737c902a8f7af0aa8c836fd6" />
      <%=pageContext.getAttribute("start") %>

 
Top of page

updateDocument

Description

Updates or adds a document for the specified workitem ID and document name and returns a boolean representing success. The return value is stored in a scripting variable called wi_document or the id you specify.

To add a new document, set the addMode attribute to true. To update an existing document, set it to false (default).

The document may be specified using one of these attributes:

If the userID attribute is not specified, the current user is used.

This tag wraps addDocument() and updateDocument() on the EbiWorkitemDelegate interface.

Syntax

  <prefix:updateDocument workitemID="workitemID" docName="docName" document="document" identifier="identifier" url="url" userID="userID" addMode="addMode" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

docName

Yes

Yes

Name of the document

document

No

Yes

The actual document; the document can be specified as an XML String or an object of type org.w3c.dom

identifier

No

Yes

The string identifier for information in the document

url

No

Yes

The URL for the document, specified as an object of type java.net.URL

userID

No

Yes

The user with whom to associate the document; if not specified, gets the user ID from the context

addMode

No

Yes

Boolean indicating whether to add a new document (true) or update an existing document (false); the default is false.

id

No

No

Name of the variable in which to store the return value; default name is wi_document

Examples

Adding a document with identifier:

  <epwf:updateDocument id="doc1" workitemID="<%=wid.getWorkitem().getId()%>" docName="identifier" addMode="true" identifier="myidentifier" / >
  <%= pageContext.getAttribute("doc1")%>

Updating a document with identifier:

  // lock the document first
  <epwf:workitemLock workitemID="<%=wid.getWorkitem().getId()%>" docName="identifier" documentLock="true" action="lock"/>
  // update the document
  <epwf:updateDocument id="doc2" workitemID="<%=wid.getWorkitem().getId()%>" docName="identifiertest3" identifier="newidentifier" / >
  <%=pageContext.getAttribute("doc2")%>

Adding document with string XML:

  <epwf:updateDocument id="doc3" workitemID="<%=wid.getWorkitem().getId()%>" docName="string1" addMode="true" document="<main><node1>this is my document</node1></main>" / >
  <%= pageContext.getAttribute("doc3")%>

 
Top of page

workitemLock

Description

Locks or unlocks a workitem or the documents associated with a workitem. The action attribute must be set to either lock or unlock. Returns a boolean value representing success. The value is returned on a scripting variable called wilocked or the name provided in the id attribute.

If documentLock is set to true, a docName must be specified.

If the userID attribute is not specified, the object is locked or unlocked using the current user.

This tag wraps lock(), unlock(), lockDocument(), and unlockDocument() on the EbiWorkitemDelegate interface.

Syntax

  <prefix:workitemLock workitemID="workitemID" action="action" workitemLock="workitemLock" documentLock="documentLock" docName="docName" userID="userID" id="id"/>

Attribute

Required?

Request-time expression values supported?

Description

workitemID

Yes

Yes

Workitem ID

action

Yes

Yes

Specify lock or unlock

workitemLock

No

Yes

Boolean indicating whether the action is for the workitem (true); the default is false

Either this attribute or documentLock (or both) must be set to true

documentLock

No

Yes

Boolean value indicating whether the lock is for a document associated with the workitem (true); the default is false

Either this attribute or workitemLock (or both) must be set to true; if documentLock is true, docName must be specified

docName

No

Yes

Name of the document; use if documentLock is true

userID

No

Yes

User to execute the action on (if not specified, the user ID from the context)

id

No

No

Name of the variable in which to store the return value; the default name is wilocked

Examples

workitemLock:

  <epwf:workitemLock id="wilock" workitemID='<%=x%>' action="lock" workitemLock="true" />
      <%=pageContext.getAttribute("wilock") %> <br/>    
      <% get.addDocument("test", "ID" , "sample"); %>

documentLock:

  <epwf:workitemLock id="doclock" workitemID='<%=x%>' action="lock" workitemLock="false" documentLock="true" docName="test" />
      <%=pageContext.getAttribute("doclock") %>

workitemUnlock:

  <epwf:workitemLock id="wiunlock" workitemID='<%=x%>' action="unlock" workitemLock="true" />
      <%=pageContext.getAttribute("wiunlock") %> <br/>    
      <%-- get.addDocument("test1456", "ID" , "sample"); --%>

documentUnlock:

  <epwf:workitemLock id="docunlock" workitemID='<%=x%>' action="unlock" workitemLock="false" documentLock="true" docName="test" />
      <%=pageContext.getAttribute("docunlock") %>


Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...