bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming BPM Client Apps

Manually Starting Workflows

This section describes how to start workflows manually, including the following topics:

- Getting Startable Workflows

- Manually Starting a Workflow

- Examples of Manually Starting a Workflow

Note: You can also automate the launch of a workflow using one of the following mechanisms: an external or timed event, or the Start Workflow action, ActionStartWorkflow, which starts one workflow from another. The latter method offers greater control because it allows business rules to be considered in determining whether a called workflow is ever started. This mechanism also enables you to set variables using the XML content, and to start multiple workflows. For more information about the actions available for starting workflows, see Template Definition DTD, or Defining Actions in Using the WebLogic Integration Worklist.

For information about manually starting workflows using the WebLogic Integration Worklist, see Working with Workflows in Using the WebLogic Integration Worklist.

Note: The Worklist client application is being deprecated as of this release of WebLogic Integration. For information about the features that are replacing it, see the BEA WebLogic Integration Release Notes.

Getting Startable Workflows

To get a list of all the workflows that can be started manually from either the Worklist or a custom run-time management client, use the following com.bea.wlpi.server.worklist.Worklist method:

>     public java.util.List getStartableWorkflows(
>       java.lang.String orgId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getStartableWorkflows() method parameter.

Table 20-1 getStartableWorkflows() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization for which you want to get startable workflows. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Managing the Active Organization.

The method returns a list of com.bea.wlpi.common.TemplateInfo objects that:

- Correspond to the template definitions that can be started manually

- Are currently active

To access information about template definitions, use the TemplateInfo object methods described in TemplateInfo Object.

For example, the following code gets a list of all startable workflows for the organization specified by the organization ID ORG1. In this example, worklist represents the EJBObject reference to the Worklist EJB.

>     List template = worklist.getStartableWorkflows("ORG1");

For more information about the getStartableWorkflows() method, see the com.bea.wlpi.server.worklist.Worklist Javadoc.

Manually Starting a Workflow

To start (or instantiate) a workflow manually, use one of the following com.bea.wlpi.server.worklist.Worklist methods.

Method 1

>     public java.lang.String instantiateWorkflow(
>       java.lang.String orgId,
>       java.lang.String templateId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

Method 2

>     public java.lang.String instantiateWorkflow(
>       java.lang.String orgId,
>       java.lang.String templateId,
>       java.lang.String xml,
>       java.util.Map initialValues,
>       java.util.Map pluginData
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

Method 3

>     public java.lang.String instantiateWorkflow(
>       java.lang.String orgId,
>       java.lang.String templateId,
>       java.lang.Object transactionId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

Method 4

>     public java.lang.String instantiateWorkflow(
>       java.lang.String orgId,
>       java.lang.String templateId,
>       java.lang.String xml,
>       java.util.Map initialValues,
>       java.util.Map pluginData,
>       java.lang.Object transactionId
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The first method can be used in a nonclustered environment. The second method is recommended for use in a clustered environment. In this case, using the specified transaction ID, the system tracks the method execution status so that the method is not reissued after the transaction is committed, or in the event of a server crash or failover.

The following table describes the instantiateWorkflow() method parameters.

Table 20-2 instantiateWorkflow() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization associated with the workflow that you want to start. | String specifying a valid organization ID. For information about getting a list of all organization IDs, see Managing the Active Organization.
templateId | ID of the workflow template for which you want to start a workflow. | String specifying a valid template ID. To get the template ID, use the following com.bea.wlpi.common.TemplateInfo method: public final String getId() The getId() method returns a templateId. Each templateId may have multiple definitions. To determine which template definition to use, WebLogic Integration selects, from the set of active template definitions, the version with the most relevant effective date (current or past) and expiration date (current or future). For information about defining the effective and expiration dates for the template definitions and making the template definitions active, see Template Definition DTD, or Using the WebLogic Integration Studio. For information about getting the TemplateInfo object, see Getting the Templates for an Organization. For more information about the methods available to the TemplateInfo object, see TemplateInfo Object.
xml | Initialization values for the workflow instance. | XML document containing initialization values that are meaningful to the workflow instance, or null if no initialization values are required.
initialValues | Initial values for workflow variables. | Map object with key-value pairs, specifying variables to be initialized as a key, and the desired value as the value, or null, if no variables require initialization.
pluginData | Plug-in instance data. | Map object with key-value pairs, specifying the plug-in name as the key, and the instance data as the value, or null, if no plug-data needs to be defined. For more information about programming BPM plug-ins, see Programming BPM Plug-Ins for WebLogic Integration.
transactionId | ID of the transaction. Note: This parameter is required only in a clustered environment. | Object specifying a unique transaction ID. To generate a unique transaction ID, create a new com.bea.wlpi.client.common.GUID object using the following constructor: GUID transactionId = new GUID(); For more information about the GUID class, see the com.bea.wlpi.client.common.GUID Javadoc.

In addition to starting the workflow template, the instantiateWorkflow() method performs the following tasks, if specified in the template definition, for every manual Start node listed in the template definition:

- Initializes variable values to specified constant values

- Executes specified actions

- Activates successors

For information about creating a template definition and defining tasks to be performed upon instantiation, see Creating and Managing Workflow Template Definitions.

The instantiateWorkflow() methods return an XML document that is compliant with the Client Request DTD, and that contains information about the template definition instance, including the following:

- Template, template definition, and instance IDs

- Information about defined Send XML to Client actions

For more information about the Client Request DTD, see Client Request DTD.

For example, the following code instantiates the template definition for the organization specified by the activeOrgId and templateId variables. In this example, worklist represents the EJBObject reference to the Worklist EJB.

>     String clientReq = worklist.instantiateWorkflow(activeOrgId, templateId);

If multiple template definitions are represented by the same templateId, WebLogic Integration selects the version that is active and that has the most relevant effective and expiration dates.

For more information about the instantiateWorkflows() methods, see the com.bea.wlpi.server.worklist.Worklist Javadoc.

Examples of Manually Starting a Workflow

The following sections provide excerpts from the command-line and JSP worklist examples showing how to manually start a workflow.

Note: For more information about the command-line and JSP worklist examples, see BPM API Examples.

Command-Line Worklist Example

This section provides excerpts from the command-line worklist example showing how to start a workflow.

Note: For more information about the command-line worklist example, see Command-Line Worklist Example.

In this example, an input stream is defined to communicate with the user, and the user is prompted to specify one of the following actions to be performed:

- Getting Startable Workflows

- Manually Starting a Workflow

Important lines of code are highlighted in bold. In this example, worklist represents the EJBObject reference to the Worklist EJB.

>     /* Create an input stream to communicate with the user */
>     stdIn = new BufferedReader( new InputStreamReader( System.in ) )

>     /* Display Tool Title */
>     System.out.print( "\n---  Command Line Worklist v1.2  ---" );

>     /* Display the main menu and interact with user */
>     while( true ) {
>        /* Display the menu */
>        System.out.println( "\n---           Main Menu          ---" );
>        System.out.println( "\nEnter choice:" );
>        System.out.println( "1) Organizations" );
>        System.out.println( "2) Workflows" );
>        System.out.println( "3) Tasks" );
>        System.out.println( "Q) Quit" );
>        System.out.print( ">> " );
>           .
>           .
>           .
>     public static void mngWorkflows( ) {
>        String templateId;

>        /* Create an input stream to communicate with the user */
>        BufferedReader stdIn = new BufferedReader(
>           new InputStreamReader( System.in ) );

>        try {
>           /* Display the main menu and interact with user */
>           while( true ) {
>              /* Display the menu */
>              System.out.println( "\n\n---           Workflows          ---" );
>              System.out.println( "\nEnter choice:" );
>              System.out.println( "1) List Startable workflow templates" );
>              System.out.println( "2) Start a workflow" );
>              System.out.println( "B) Back to previous menu" );
>              System.out.println( "Q) Quit" );
>              System.out.print( ">> " );

>              /* Get the user's selection */
>              String line = stdIn.readLine( );

>              /* User pressed enter without making a selection ? */
>              if( line.equals( "" ) )
>                 continue;
>              /* User entered more than one char ? */
>              else if( line.length( ) > 1 ) {
>                 System.out.println( "*** Invalid choice" );
>                 continue;
>              }

>              /* Convert to uppercase and to char */
>              char choice = line.toUpperCase( ).charAt( 0 );

>              /* Process user's selection */
>              switch( choice ) { ...

Getting Startable Workflows

The following excerpt shows how to get a list of startable workflows:

>              /* List Startable workflow templates */
>              case '1' :
>                 /* WLPI Public API Method */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 String activeOrgId = worklist.getActiveOrganization( );
>                 List templateList;

>                 /* WLPI Public API Method */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 templateList = worklist.getStartableWorkflows( activeOrgId );

>                 /* Any startable workflows ? */
>                 if( templateList.size( ) == 0 )
>                    System.out.println( "\nNo Startable Workflows." );
>                 else
>                    System.out.println( "\nStartable Workflows:" );

>                 /* Process the list to display startable workflows */
>                 for( int i = 0; i < templateList.size( ); i++ ) {
>                    /* Retrieve an element from the list */
>                    TemplateInfo templateInfo = (
>                       TemplateInfo )templateList.get( i );

>                    /* Retrieve and display Template id and name */
>                    System.out.println( "- ID: " + templateInfo.getId( ) +
>                       " Name: " + templateInfo.getName( ) );
>                 }
>                 break; ...

Manually Starting a Workflow

The following excerpt shows how to manually start a workflow:

>              /* Instantiate a Workflow Template */
>              case '2' :
>                 /* Get Template ID for the workflow to instantiate */
>                 if( ( templateId = askQuestion(
>                    "\nEnter Workflow Template ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 try {
>                    /* WLPI Public API Method */
>                    /* Retrieve the Active Organization ID */
>                    activeOrgId = worklist.getActiveOrganization( );

>                    /* WLPI Public API Method */
>                    /* Instantiate the workflow */
>                    String clientReq = worklist.instantiateWorkflow(
>                       activeOrgId, templateId );

>                    /* Success (No exception thrown) */
>                    System.out.println( "- Success" );
>     //             System.out.println( "- Client Request:\n" + clientReq );

>                    /* Parse the reply from the server to process client
>                     * request (if any) */
>                    parser.handleRequest( clientReq );
>                 }
>                 catch( Exception e ) {
>                    System.out.println(
>                    "*** Failed to instantiate Workflow Template (ID: " +
>                       templateId + ")" );
>                    System.err.println( e );
>                 }
>                 break;

>              /* Return to previous menu */
>              case 'B' :
>                 return;

>              /* Exit tool */
>              case 'Q' :
>                 /* Disconnect from the server */
>                 disconnect( );
>                 System.exit( 1 );

>              default:
>                 System.out.println( "*** Invalid choice" );
>              }
>           }
>        }
>        /* "Unhandled" exceptions */
>        catch( Exception e ) {
>           System.err.println( e );
>        }
>        return;
>     }

JSP Worklist Example

This section provides excerpts from the JSP worklist example showing how to start a workflow manually.

Important lines of code are highlighted in bold. In this example, worklist represents the EJBObject reference to the Worklist EJB.

As shown in the figure Main Interface to the JSP Worklist, a workflow is started when a user clicks on the Start Workflow link in the JSP worklist, and selects a startable workflow. The Start Workflow link references the startworkflow.jsp file, as follows:

>     <a href="startworkflow.jsp"><font color= "white">Start Workflow</font></a>

The following excerpt from the startworkflow.jsp file in the JSP worklist example shows how to start a workflow:

>     <%@ page import="
>        javax.ejb.*,
>        java.rmi.RemoteException,
>        java.util.*,
>        com.bea.wlpi.common.*
>        com.bea.wlpi.server.worklist.*
>     " session="true"%>

>     <jsp:usebean id="responseParser" class="jsp_servlet._worklist.ResponseParser" scope="session"/>

>     <%
>        Worklist worklist = null;
>        String name;
>        String error = null;
>        String currentOrg = (String)session.getValue("currentOrg");
>        worklist = (Worklist)session.getValue("worklist");
>        name = (String)session.getValue("name");

>        if (worklist != null) {
>           Hashtable h = new Hashtable();
>           h.put(javax.naming.Context.SECURITY_PRINCIPAL, name);
>           h.put(javax.naming.Context.SECURITY_CREDENTIALS,
>           (String)session.getValue("password"));
>           new javax.naming.InitialContext(h);

The start variable is used to store the template ID of the workflow template definition that the user wants to start. When the JSP is initially loaded, the start variable is set to null, and the start workflow try loop is skipped. Next, the startable workflows are listed. When the user selects a startable workflow, the startworkflow.jsp file is invoked with the start variable set to the value of the template ID, which is obtained from the TemplateInfo object. The resulting XML file (which is compliant with the Client Request DTD) is returned from the instantiateWorkflow() method call and passed to the response parser, ResponseParser, for parsing. For more information about the response parser, see Assigning a Task.

>           /* Start Workflow if start parameter set */
>           String start = request.getParameter("start");
>           if (start != null)
>              try {
>                 responseParser.parse(worklist.instantiateWorkflow(
>                    currentOrg, start));
>                 session.removeValue("error");
>                 if (responseParser.isQuery())
>                    pageContext.forward("query.jsp");
>                 else
>                    pageContext.forward("worklist.jsp");
>                 return;
>              } catch (Exception e) {
>              error = e.getMessage();
>           } out.println(error);
>     %>
>     <html>
>     <title>eProcess Integrator</title>
>     <head>
>     </head>

>     <body bgcolor=#ffffff>
>     <font face="Arial" size="4">

>     <table dir="ltr" border="0" cellpadding="1" cellspacing="1">
>        <tr>
>           <td><img src="logo.gif"></td>
>           <td>
>              <font color="red" size="7"><strong><em>Weblogic</em></strong></font>
>              <font color="black" size="7"><strong><em>Process Integrator
>              </em></strong></font></td>
>        </tr>
>        <tr>
>           <td bgcolor="navy" valign="top">
>           <table dir="ltr" border="0" cellpadding="2" cellspacing="2" >
>              <tr>
>                 <td><font color="yellow"><strong>Go ...</strong></font></td>
>              </tr>
>              <tr>
>                 <td><a href="worklist.jsp?worklist">
>                 <font color="white">Worklist</font></a></td>
>              </tr>
>              <tr>
>                 <td><a href="logoff.jsp"><font color="white">Logoff</font></a></td>
>              </tr>
>           </table>
>           </td>

>           <td valign="top">
>           <table dir="ltr" border="0" cellpadding="2" cellspacing="2" valign="top">
>              <tr>
>                 <td><font color="navy" size="5" face="Arial">
>                 Start Workflow</font></td>
>              </tr>

The startable workflows are listed. When the user selects one, the startworkflow.jsp file is invoked with the start variable set to the value of the template ID obtained from the TemplateInfo object.

>     /* Get startable workflows and list them./*
>     <%
>        try {
>           List templates = worklist.getStartableWorkflows(currentOrg);
>           for (int i = 0; i < templates.size(); i++) {
>     	    TemplateInfo info = (TemplateInfo)templates.get(i);

>     %>
>              <tr>
>                 <td><a href="startworkflow.jsp?start=<%=info.getId()%>">
>                 <%=info.getName()%></a></td>
>              </tr>
>     <%
>        }
>        } catch (Exception e) {
>        out.print("Error 3: " + e);
>        }
>        }
>     %>
>           </table>
>           </td>
>        </tr>
>     </table>
>     </font>
>     </body>
>     </html>