Workflow Guide

Chapter 4 Customizing Activities and Links

This chapter describes how to write Java classes for automatic activities and how to customize runtime behavior for activities and links. It has these sections:

Writing an automatic activity

An automatic activity represents an unattended task or step in your process. In Workflow Designer, you create an automatic activity node and specify properties that configure the engine and queue for this task. For more information, see Automatic activity.

You use the Activity Wizard to generate a Java class that executes the logic for the activity. The generated automatic activity class is used only at runtime. No design-time classes are generated.

Procedure To generate a Java class for a custom activity:

With your EAR project open in Workbench, select File>New from the menu.
Click the Workflow tab.
Select Workflow Activity and click OK.

Complete the wizard panel:

Panel item	Description
Class name	Name for the Java class file. This is the name referenced in the Automatic Activity property sheet in Workflow Designer.
Package	(Optional) Package name for the class.
Resource Set	Resource set for storing the runtime deployment class.
Include logging code	Include logging code in the generated template.
Automatic Activity	Select to generate code for an automatic activity. Deselect to generate code for a custom activity.

Click Finish.

The wizard generates an automatic activity stub class.

Coding the automatic activity

The generated class implements the EbiActivity interface. This interface is how Workflow Designer discovers automatic activity classes to select from when you edit activity properties in Workflow Designer.

The wizard generates four method stubs:

  public void invoke()
  public void timeout(int retries)
  public void restart()
  public void terminate()

invoke()

This method is called when work shows up in the workflow queue for the automatic activity. It is the responsibility of the automatic activity to request the work from the queue. This is done through the queue delegate interface. Before a workitem can be changed, it must be locked. After all changes have been made, you forward work to the next activity.

For more information, see EbiQueueDelegate and EbiWorkitemDelegate in the API Reference.

Here is what an invoke() method looks like:

  public void invoke(){   
   try
     {
     //Get the queue delegate for requesting work
     EbiQueueDelegate queueDelegate = EboFactory.getQueueDelegate();
     
     //Get the next workitem 
     EbiWorkitemDelegate workitemDelegate =
        queueDelegate.getNextWorkitem(this.getClass().getName());
     
     //lock workitem
     workitemDelegate.lockDocument("Document1",
        this.getClass().getName());
    
     //Do the logic for the activity, for example..
     EbiProperty prop = (EbiProperty) new EboProperty("Document1",
        "DocProp1", "Hello world!", EbiProperty.TYPE_STRING, false);
     workitemDelegate.setDocumentProperty(prop, this.getClass().getName());
     
     //Forward to next workitem -- this automatically unlocks it
     queueDelegate.forward(workitemDelegate2);
    }
   catch (Exception e)
    {
     e.printStackTrace();
    }
  }

restart()

This method informs the automatic activity to restart its actions for performing work. Normally, this would be the same actions taken in the invoke method; but it may include additional actions.

timeout()

This method informs the automatic activity that a timeout has occurred and the int argument represents the number of retries (the number of times the activity can stay active after a timeout). Presumably when the count is zero, the automatic activity should take the course of actions the developer has instructed for this contingency. No particular action is enforced by the workflow system at this time.

terminate()

This method informs the automatic activity it should follow the appropriate course of actions the developer has instructed for this contingency. Like the retries method, the Workflow subsystem enforces no particular action.

Customizing runtime behavior for an activity

Custom activities can add customized runtime behavior before the workitem is sent to the workflow queue to have work performed, and can add customized behavior after the work has been performed. Respectively, two methods represent any pre and post workitem processing: onPreprocess() and onPostprocess().

To create a class template for a custom Activity, use the Custom Activity Wizard as described in To generate a Java class for a custom activity:. The generated class extends EboProcessNode:

  import com.sssw.wf.activity.*;
  import com.sssw.wf.api.*;
  import com.sssw.wf.message.EbiDispatch;
  import com.sssw.wf.exception.*;
  import com.sssw.wf.core.*;
  import com.sssw.wf.client.EboFactory;
  import com.sssw.wf.client.EbiQueueDelegate;
  import com.sssw.wf.client.EbiWorkitemDelegate;
  import org.w3c.dom.*;
  
  /**
      This class is a sample runtime activity.
  */
  public class UntitledActivity1 extends EboProcessNode {
  
      public UntitledActivity1() {
      }
  }

Coding the activity

Here is an example showing the format for custom post process actions:

  /**
  This class is a sample runtime activity.
  */
  public class UntitledActivity1 extends EboProcessNode {
  
    public UntitledActivity1() {
    }
    public void onPostprocess (EbiDispatch dispatch) throws  
         EboActivityException
    {
      EbiWorkitem wi = dispatch.getMessage().getWorkitem();
      //Logic goes here
       }
  }

The dispatch argument can be queried for the workitem through a getMessage() call. The workitem can then be queried for its properties and/or documents via an EbiWorkitemDelegate.

Similarly, the method available to custom activities for custom actions before a workitem is sent to the workflow queue is:

  public void OnPreprocess (EbiDispatch dispatch) throws EboActivityException

Usage is the same as for the OnPostprocess() method.

Customizing runtime behavior for a link

Custom links give you complete control over how the set of link paths is chosen. To create a class template for a custom Link, use the Link Wizard as described below. The generated class implements EbiLink. In the custom link code you can access workitem link properties by implementing EbiLink.getDestinations().

Procedure To generate a java class for a custom link:

With your EAR project open in Workbench, select File>New from the menu.
Click the Workflow tab.
Select Workflow Link and click OK.

Panel item	Description
Class name	Name for the Java class file.
Package	(Optional) Package name for the class.
Resource Set	Resource set for storing the runtime deployment class.
Include logging code	Include logging code in the generated template.

Complete the wizard panel:

The resulting code template looks like this:

  import java.util.List;
  import com.sssw.wf.core.EbiWorkitem;
  import com.sssw.wf.api.EbiLink;
  import com.sssw.wf.exception.EboLinkException;
  
  /**
   *   UntitledLink1
  */
  public class UntitledLink1 implements EbiLink {
  
      public UntitledLink1() {
      }
  
      public List getDestinations(EbiWorkitem workitem) throws
          EboLinkException {
      // This method should return a List of objects of type EbiDestination
          return null;
      }
  }

Coding the link

getDestinations() returns a list of all available workitems for the link. After you get a workitem, you can query it for property values:

  public List getDestinations(EbiWorkitem workitem) throws EboLinkException
    {
        List dests = (List) new Vector();
        // call Ebolink.getDestinations()to get ALL available destinations
        List availDests = getDestinations();
        Iterator destIt = dests.iterator();
        while(destIt.hasNext())
        {
            EbiDestination d = destIt.next();
  	 	 	 /*
            Get link properties and do logic ...
          */
        }
        return dests;
    }

Accessing link properties

In most cases the properties provide the context in which the link paths are chosen. The pattern for the Workflow subsystem is activities set properties and links read properties. If a custom link property was defined in Workflow Designer, you can call this method:

  protected NodeList getProperties ()

Then parse the list to access specific items. The element schema for the returned properties is:

  <!ELEMENT property EMPTY>
  <!ATTLIST property
  name CDATA #REQUIRED
  type (int | double | long | boolean | timestamp | string) #REQUIRED
  value CDATA #IMPLIED
  immutable (true | false) #IMPLIED
  >

Workflow Guide