Chapter 17 Writing Custom Activities

This chapter describes how to write and use custom activities. The sections in this document are:

• Introduction
• Implementing ISimpleWorkPerformer
• Writing the XML Description File
• Packaging a Custom Activity
• Adding a Custom Activity to the Process Map
• Working with a Custom Activity
• Implementation Tips

• You place them on the process map by dragging and dropping them from the Palette.
• They can have completion scripts.
• They are triggered as soon as the process instance reaches the activity, unless the activity is deferred. A deferred activity is triggered at its specified date and time.

1. Write and compile a Java class that implements the ISimpleWorkPerformer interface.
2. Define an XML description file for the activity.
3. Package the Java class and the XML description file as a zip or jar file.
4. Bring the custom activity into an application.

1. gets data field values as input
2. performs some task
3. sets data field values as output

• Methods of ISimpleWorkPerformer
• Sample Java Class

• The init( ) method is called when the application starts.

• The perform( ) method is called each time the custom activity is executed. This method must be thread-safe.


• The destroy( ) method is called when the application is unloaded or removed.

public void init (Hashtable environment) throws Exception

The init() method performs initialization tasks that the custom activity requires when the application starts. For example, use init() to set up database connections that are shared by all instances of the activity, or use init() to define variables that are constant across all instances of the activity.

public void perform (Hashtable in, Hashtable out) throws Exception

The perform() method does whatever tasks must be done for the activity. This method takes two java.util.Hashtable arguments. The input hashtable contains values taken from data fields, and the output hashtable contains values to put into data fields.

To obtain the value of a parameter in the input hashtable, call the get() method on the input hashtable. The get() method returns either the value of the parameter, or null if the parameter doesn't exist. Note that the get() method returns a Java object, so you must cast this object to the object class type that your custom activity is expecting. For example:

String sizeOrder = (String) input.get("order");

The Output Hashtable

To set data field values, the perform() method must put values into the output hashtable by calling put() on the output hashtable. When the perform() method finishes executing, you then assign the values to the corresponding data fields.

public void destroy()

The destroy() method is called when the application that uses the custom activity is unloaded or removed. Typically, you use the destroy() method to clean up resources that were used by the init() method.

1. Define a package for your class:

   package com.netscape.pm.sample;

2. Import the required standard Java packages:

   import java.lang.*;
   import java.util.*;

3. Define the class HelloWorldPerformer to implement com.netscape.pm.model.ISimpleWorkPerformer, as follows:

   public class HelloWorldPerformer
      implements com.netscape.pm.model.ISimpleWorkPerformer
{

4. Define two variables to hold the English and French parts of the greeting. Define another variable to hold the complete greeting when it has been derived (such as "Bonjour Nikki.")

   // Greeting Messages
   public static final String GREETING_FRENCH = "Bonjour";
   public static final String GREETING_ENGLISH = "Hello";

   // Holds the greeting message once the language has been specified
   String mGreeting;

5. Define the init() method to get the value of the Language environment variable and to set the language-specific part of the greeting. In addition, throw an exception if the language is not provided, or if the language is neither English nor French. For example:

   /**

    * The HelloWorld custom activity knows to generate both French

    * and English greetings. The Language argument defines which

    * language should be used.

    */

   public void init( Hashtable env ) throws Exception

   {

      String lang = (String) env.get( "language" );

      if( lang == null )

      {

            throw new Exception( "-- language not defined.") ;

      }

      else if( lang.equalsIgnoreCase("French") )

      {

            mGreeting = GREETING_FRENCH;

      }

      else if( lang.equalsIgnoreCase("English") )

      {

            mGreeting = GREETING_ENGLISH;

      }

      else

      {

         throw new Exception( "-- Unknown language:"+ lang +

         ". We currently support English or French--" ) ;

      }

   }

Later, you will set the exact value of the Language environment. You'll do this in Process Builder, when you set up the custom activity in a process definition.

6. Define the perform() method to construct a welcome message consisting of the language-specific part of the greeting and the user's name, for example "Hello Billy." The value of the userName parameter is derived later—from a data field in a process instance that uses the custom activity.

• Use the get() method on the input parameter to get the value of an input parameter.

   /**

   * Reads the userName element of the input hashtable,

   * generates greetings, and sets the Greeting element of out.

   */

   public void perform( Hashtable input, Hashtable output )

      throws Exception

   {

      // Read the userName attribute from the input hashtable

      String userName = (String) input.get( "userName" );

      

      if( userName == null )

      {

            throw new Exception( "userName has not been initialized!" ) ;

      }

      // Generate greetings

      String msg = mGreeting + " " +userName;

• Use the put() method on the output parameter to set the value of an output parameter.

      // Put the greeting into the welcomeMsg parameter of

      // the output hashtable.

      output.put( "welcomeMessage" , msg );

7. Finally, define the destroy() method, which is invoked when the application is unloaded from the application server. In this case, the method does nothing because no resource cleanup is needed.

      public void destroy( )

      {

      }

   // End of class
   }

8. Compile HelloWorldPerformer.java to get a class file, HelloWorldPerformer.class.

• File Format
• Sample XML Description File

   <?XML version = "1.0" ?>

The body of the description is contained between an opening <WORKPERFORMER> tag and a closing </WORKPERFORMER> tag. Within the WORKPERFORMER section you define four sections, as summarized in Table 17.1.

<?XML version = "1.0" ?>

<WORKPERFORMER >

<ENVIRONMENT>
   <PARAMETER> ... </PARAMETER> ...
</ENVIRONMENT>

<INPUT>
   <PARAMETER> ... </PARAMETER> ...
</INPUT>

<OUTPUT>
   <PARAMETER> ... </PARAMETER> ...
</OUTPUT>

<DESIGN>
   <PARAMETER> ... </PARAMETER> ...
</DESIGN>

</WORKPERFORMER>

WORKPERFORMER Tag
The <WORKPERFORMER> tag has four attributes: TYPE, NAME, CLASS_ID, and VERSION.

• TYPE is the full package name for the Java class for this type of activity. For a simple custom activity, TYPE is always this:

com.netscape.pm.model.ISimpleWorkPerformer

• NAME is the name of the custom activity (which is the same as the name of the XML description file and the jar file that contains the custom activity). This name is not currently used anywhere.
• CLASS_ID is the full package name for the Java class that implements the custom activity.
• VERSION is the version of the custom activity. VERSION is currently unused, but you could use it to keep version information about the description file.

<WORKPERFORMER
   TYPE="com.netscape.pm.model.ISimpleWorkPerformer"
   NAME="HelloWorld"
   CLASS_ID="com.netscape.pm.sample.HelloWorldPerformer"
   VERSION="1.1">

ENVIRONMENT Section
The <ENVIRONMENT> tag defines environment parameters that are constant within all instances of the custom activity. For example, suppose that in an application named HelloWorld, you set the value of the Language environment parameter to French. Then, the value is always French in every process instance of that application.

<ENVIRONMENT>
   <PARAMETER NAME="Language">"French"</PARAMETER>
</ENVIRONMENT>

Warning. Parameter values (such as "French" in the example above) are actually JavaScript expressions, so you can supply the value as a string, integer, or function. However, be sure to quote any string expression. Note that French (without quotes) and "French" (with quotes) mean different things.

<INPUT>

   <PARAMETER

         NAME="userName"

         DISPLAYNAME="User Name"

         TYPE="java.lang.String"

         DESCRIPTION="Last Name">

   getData("customerName")

   </PARAMETER>

</INPUT>

For details on the syntax of the <PARAMETER> tag, see the section "PARAMETER Tag".

public void perform( Hashtable input, Hashtable output )

         throws Exception

{

   // Read the userName attribute from the input hashtable

   String userName = (String) input.get( "userName" );

   if( userName == null )

   {

         throw new Exception( "userName has not been initialized!" ) ;

   }

   // Generate greetings

   String msg = mGreeting + " " +userName;

OUTPUT Section
The <OUTPUT> tag contains embedded <PARAMETER> tags. Each <PARAMETER> tag describes a parameter in the output hashtable, the output argument of the perform() method. The <OUTPUT> tag has a corresponding closing </OUTPUT> tag , and each <PARAMETER> tag has a closing </PARAMETER> tag.

<OUTPUT>

   <PARAMETER

            NAME="welcomeMsg"

            DISPLAYNAME="Welcome Message"

            TYPE="java.lang.String"

            DESCRIPTION="Greeting for the user">

   mapTo("greeting")

   </PARAMETER>

</OUTPUT>

For details on the syntax of the <PARAMETER> tag, see the section "PARAMETER Tag".

   output.put( "welcomeMessage" , msg );

PARAMETER Tag
The <PARAMETER> tag has the attributes as summarized in Table 17.2. When you define parameters within the DESIGN section of the XML description file, only the NAME and DESCRIPTION attributes apply. However, within the ENVIRONMENT, INPUT, or OUTPUT sections, all of the attributes apply.

• This file specifies userName as a parameter in the input hash table. However, the value of this parameter is obtained from the customerName data field in the process instance.
• Similarly, the file specifies welcomeMsg as a parameter in the output hashtable, and maps its value back into the greeting data field in the process instance.

<?XML version = "1.0" ?>

<WORKPERFORMER

   TYPE="com.netscape.pm.model.ISimpleWorkPerformer"

   NAME="HelloWorld"

   CLASS_ID="com.netscape.pm.sample.HelloWorldPerformer"

   VERSION="1.1">

<ENVIRONMENT>

   <PARAMETER

            NAME="Language"

            VALUESET="'English','French'"

            TYPE="java.lang.String">

   'English'

   </PARAMETER>

</ENVIRONMENT>

<INPUT>

   <PARAMETER

            NAME="userName"

            DISPLAYNAME="User Name"

            TYPE="java.lang.String"

            DESCRIPTION="Last Name">

   getData("customerName")

   </PARAMETER>

</INPUT>

<OUTPUT>

   <PARAMETER

            NAME="welcomeMsg"

            DISPLAYNAME="Welcome Message"

            TYPE="java.lang.String"

            DESCRIPTION="Greeting for the user">

   mapTo("greeting")

   </PARAMETER>

</OUTPUT>

<DESIGN>

   <PARAMETER

            NAME="Icon"

            DESCRIPTION="A 32x32 icon that is placed on the palette">

   drap_uk2.gif

   </PARAMETER>

   <PARAMETER

            NAME="Label"

            DESCRIPTION="The DISPLAYNAME used for this palette element.">

   Hello World

   </PARAMETER>

   <PARAMETER

            NAME="BubbleHelp"

            DESCRIPTION="Bubble help for the palette element">

   HelloWorld - A simple work performer Custom Activity.

   </PARAMETER>

   <PARAMETER

            NAME="HelpURL"

            DESCRIPTION="URL explaing this palette element">

   http://people.netscape.com/michal/

   </PARAMETER>

   <PARAMETER

            NAME="MapIcon"

            DESCRIPTION="Icon for the process map (48x48)">

   drap_uk2.gif

   </PARAMETER>

   <PARAMETER

            NAME="SelectedMapIcon"

            DESCRIPTION="Icon for the process map (48x48)">

   drap_fr2.gif

   </PARAMETER>

   <PARAMETER

            NAME="TreeViewIcon"

            DESCRIPTION="Icon for the tree view (48x48)">

   mailer_tree_view.gif

   </PARAMETER>

</DESIGN>

</WORKPERFORMER>

• One or more Java classes. At least one of these classes must implement ISimpleWorkPerformer.
• An XML description file.
• Optional image files to use as icons in Process Builder.

• In one case you create a custom palette. This approach is useful if you intend to use a custom activity often, either within a single application or across several applications.
• In the other case, you don't create a custom palette, and you simply use the Custom Activity icon provided with Process Builder. This approach might be better if you rarely use custom activities, and you don't want to create a custom palette for them.

1. In the palette, right-click the area below the title bar, and choose "Add custom palette," as shown in Figure 17.3. This adds a new tab to the palette.

Figure 17.3    Adding a custom palette



2. In the "New palette name" dialog box (shown in Figure 17.4), type the label for the new tab. For example, enter "HelloWorld".

Figure 17.4    Enter a name for the new palette



A new tab is added to the palette.

3. Click your new custom tab to make it active. Note that the area contains no icons.
4. Right-click in the empty area under the tabs, and select "Add Custom Activity ...". See Figure 17.5.

Figure 17.5    Add a custom activity to the palette



A file selection window appears.

5. Using the file selection window, locate the archive file that represents the custom activity, and select the file. For example, Figure 17.6 show the selection of HelloWorld.zip:

Figure 17.6    Select the file that represents a custom activity



The custom activity is added to your new palette. For example, as shown in Figure 17.7, the HelloWorld activity appears on the palette like this:

Figure 17.7    A custom activity icon appearing on the HelloWorld custom palette



Note that the custom activity's appearance in Process Builder is controlled by the DESIGN section of the XML file. In the HelloWorld tab pictured above, you see the effects of setting the Icon, Label, and BubbleHelp parameters in the DESIGN section.

6. To add the activity to your application, drag the icon from the custom palette to the process map.

1. In the palette, drag the Custom Activity icon to the process map.
2. Select the custom activity and open the Inspector window.
3. On the Properties tab of the Inspector, locate the property named Custom Activity.
4. Click the Browse button to bring up a file selection window, and locate the zip or jar file that represents the custom activity. An example is shown in Figure 17.8.

Figure 17.8    Setting the Custom Activity property



5. Click Open to associate the selected file with the Custom Activity icon. The Custom Activity icon now has the characteristics defined by the file.