bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming BPM Client Apps

Creating and Managing Workflow Templates

Workflow templates provide containers that hold one or more workflow template definitions.

This section explains how to create and manage workflow templates, including the following topics:

- Creating a Template

- Getting a Template

- Getting the Templates for an Organization

- Getting the Template Organizations

- Setting the Template Organizations

- Deleting a Template

- Example of Managing Templates

For more information about the methods described in this section, see the com.bea.wlpi.server.admin.Admin Javadoc. For information about managing workflow templates using the WebLogic Integration Studio, see Defining Workflow Templates in Using the WebLogic Integration Studio.

Creating a Template

To create a workflow template, use one of the following com.bea.wlpi.server.admin.Admin methods.

Method 1

>     public java.lang.String createTemplate(
>       java.lang.String name,
>       java.lang.String xml,
>       java.util.Collection orgs
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

Method 2

>     public java.lang.String createTemplate(
>       java.lang.String name,
>       java.lang.String xml,
>       java.util.Collection orgs,
>       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 createTemplate() method parameters for which you must specify values.

Table 13-1 createTemplate() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
name | Template name. | Non-null string.
xml | Name of the XML document that defines the plug-in data and that is compliant with the Template Definition DTD, as described in Template Definition DTD. For more information about programming BPM plug-ins, see Programming BPM Plug-Ins for WebLogic Integration. | Non-null string.
orgs | Collection of organization IDs that can access the template. | Collection of strings consisting of valid organization IDs. For information about getting a list of organization IDs, see Getting All Organizations.
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.

Each method returns the ID of the new template.

For example, the following code creates a new template named Order Processing that is accessible from the specified collection of organizations, orgIds. In this example, admin represents the EJBObject reference to the Admin EJB.

>     String id = admin.createTemplate("Order Processing", null, orgIds);

For more information about the createTemplate() methods, see the com.bea.wlpi.server.admin.Admin Javadoc.

Getting a Template

To get a workflow template, use the following com.bea.wlpi.server.admin.Admin method:

>     public com.bea.wlpi.common.TemplateInfo getTemplate(
>       java.lang.String templateId,
>       boolean byName
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the getTemplate() method parameters for which you must specify values.

Table 13-2 getTemplate() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
templateId | ID or name of the template that you want to retrieve. | String specifying a valid template ID or name.
byName | Boolean flag specifying whether or not the value specified for the templateId parameter is the template name (true) or ID (false). | true (name) or false (name).

Each method returns the com.bea.wlpi.common.TemplateInfo object corresponding to the template. To access information about the template, use the TemplateInfo object methods described in TemplateInfo Object.

For example, the following code gets the template with the name Order Processing (note, the byName parameter is set to true). In this example, admin represents the EJBObject reference to the Admin EJB.

>     TemplateInfo template = admin.getTemplate(
>       "Order Processing", true);

For more information about the getTemplate() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

Getting the Templates for an Organization

To get a list of workflow templates for an organization, use the following com.bea.wlpi.server.admin.Admin method:

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

The following table describes the getTemplates() method parameter for which you must specify a value.

Table 13-3 getTemplates() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
orgId | ID of the organization for which you want to get templates. | String specifying a valid organization ID. For information about getting a list of organization IDs, see Getting All Organizations.

This method returns a list of com.bea.wlpi.common.TemplateInfo objects. To access information about each template, use the TemplateInfo object methods described in TemplateInfo Object.

For example, the following code gets all templates associated with the ORG1 organization. In this example, admin represents the EJBObject reference to the Admin EJB.

>     List templates = admin.getTemplates("ORG1");

For more information about the getTemplates() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

Getting the Template Organizations

To get the organizations that have access to a template, use the following com.bea.wlpi.server.admin.Admin method:

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

The following table describes the getTemplateOrgs() method parameter for which you must specify a value.

Table 13-4 getTemplateOrgs() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
templateId | ID of the template for which you want to retrieve the organizations. | String specifying a valid template ID. To get the template ID, use the following com.bea.wlpi.common.TemplateInfo method: public final java.lang.String getId() 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.

Each method returns a list of organization IDs.

For example, the following code gets a list of organizations that have access to a template and assigns the result to orgs. In this example, admin represents the EJBObject reference to the Admin EJB.

>     List orgs = admin.getTemplateOrgs(template.getId());

The template ID is obtained using the methods associated with the com.bea.wlpi.common.TemplateInfo object, template. The template object can be obtained using the methods described in Getting the Templates for an Organization.

For more information about the getTemplateOrgs() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

Setting the Template Organizations

To set the organizations that have access to a template, use the following com.bea.wlpi.server.admin.Admin method:

>     public void setTemplateOrgs(
>       java.lang.String templateId,
>       java.util.Collection orgs
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the setTemplateOrgs() method parameters for which you must specify values.

Table 13-5 setTemplateOrganizations() Method Parameters

Parameter | Description | Valid Values
--- | --- | ---
templateId | ID of the template for which you want to set organizations. | String specifying a valid template ID. To get the template ID, use the following com.bea.wlpi.common.TemplateInfo method: public final java.lang.String getId() 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.
orgs | Collection of organization IDs that can access the template. | Collection of strings consisting of valid organization IDs. For information about getting a list of organization IDs, see Getting All Organizations.

For example, the following code sets the organizations that have access to a template using the collection, organizations. In this example, admin represents the EJBObject reference to the Admin EJB.

>     List orgs = admin.setTemplateOrgs(
>       template.getId(), template.getName(), organizations);

The template ID and name are obtained using the methods associated with the com.bea.wlpi.common.TemplateInfo object, template. The template object can be obtained using the methods described in Getting the Templates for an Organization.

For more information about the setTemplateOrgs() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

Updating a Template

To update a workflow template, use the following com.bea.wlpi.server.admin.Admin method:

>     public void updateTemplate(
>       com.bea.wlpi.common.TemplateInfo info
>     ) throws java.rmi.RemoteException,
>       com.bea.wlpi.common.WorkflowException

The following table describes the updateTemplate() method parameter for which you must specify a value.

Table 13-6 updateTemplate() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
info | Template name, ID, and new information. | A TemplateInfo object with the name and ID fields set to identify the existing template that you want to update, and the remaining fields set to the new information.

For example, the following code updates an existing template, as defined by the TemplateInfo object, info. In this example, admin represents the EJBObject reference to the Admin EJB.

>     admin.updateTemplate(info);

For more information about the updateTemplate() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

Deleting a Template

To delete a template, use the following com.bea.wlpi.server.admin.Admin method:

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

The following table describes the deleteTemplate() method parameter for which you must specify a value.

Table 13-7 deleteTemplate() Method Parameter

Parameter | Description | Valid Values
--- | --- | ---
templateId | ID of the template that you want to delete. | String specifying a valid template ID. To get the template ID, use the following com.bea.wlpi.common.TemplateInfo method: public final java.lang.String getId() 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.

For example, the following code deletes the specified template. In this example, admin represents the EJBObject reference to the Admin EJB.

>     admin.deleteTemplate(template.getId());

The template ID is obtained using the methods associated with the com.bea.wlpi.common.TemplateInfo object, template. The template object can be obtained using the methods described in Getting the Templates for an Organization.

For more information about the deleteTemplate() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

Example of Managing Templates

This section provides excerpts from the command-line Studio example showing how to manage templates.

Note: For more information about the command-line Studio example, see Command-Line Studio 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:

- Creating a Template

- Deleting a Template

- Getting Templates for an Organization

Important lines of code are highlighted in bold. In this example, admin represents the EJBObject reference to the Admin 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 Studio v1.0      ---" );

>     /* 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) Templates" );
>        System.out.println( "2) Task Reroutes" );
>        System.out.println( "Q) Quit" );
>        System.out.print( ">> " );
>           .
>           .
>           .
>     /**
>      * Method that interacts with the user to get all the required information
>      * to illustrate the Public API Methods available in the Admin interface
>      * that are related to WLPI Workflow Templates.
>      */
>     public static void mngTemplates() {
>        ArrayList orgsList = new ArrayList();
>        String answer;
>        String orgId;
>        String templateId;
>        String templateName;

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

>        try {
>           /* Display the menu and interact with user */
>           while( true ) {
>              /* Display the menu */
>              System.out.println( "\n\n---       Workflow Templates         ---" );
>              System.out.println( "\nEnter choice:" );
>              System.out.println( "1) Create a Template" );
>              System.out.println( "2) Delete a Template" );
>              System.out.println( "3) List Templates for an Organization" );
>              System.out.println( "B) Back to previous menu" );
>              System.out.println( "Q) Quit" );
>              System.out.print( ">> " );

>              /* Get 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 selection" );
>                 continue;
>              }

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

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

Creating a Template

The following excerpt shows how to create a template:

>              /* Create a Template */
>              case '1' :
>                 /* Get Template name */
>                 if( ( templateName = askQuestion( "\nEnter Template Name" ) )
>                    == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 System.out.println( "\nDefining organizations where
>                    the template is accessible" );
>                 boolean isEnterMore = true;
>                 boolean isCancelled = false;

>                 /* Loop to get the list of Organizations ID */
>                 while( isEnterMore ) {
>                    /* Get Organization ID for the organization to set as active */
>                    if( ( orgId = askQuestion( "Enter an Organization ID" ) )
>                       == null ) {
>                       /* User cancelled the operation */
>                       System.out.println( "*** Cancelled" );
>                       isCancelled = true;
>                       break;
>                    }

>                    orgsList.add( orgId );

>                    /* Should we keep looping to enter more org ID ? */
>                    if( ( answer = askQuestion( "Enter more (y/n)?" ) ) == null ) {
>                       /* User cancelled the operation */
>                       System.out.println( "*** Cancelled" );
>                       isCancelled = true;
>                       break;
>                    }

>                    /* Evaluate the answer */
>                    isEnterMore = ( answer.equals( "y" ) || answer.equals( "Y" ) );
>                 }

>                 /* Has the user cancelled the operation ? */
>                 if( isCancelled )
>                    break;

>                 try {
>                    /* WLPI Public API Method */
>                    /* Create the new Template */
>                    templateId = admin.createTemplate( templateName, null, orgsList );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Created (template Id = " +
>                       templateId + ")" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to create Template" );
>                    System.err.println( e );
>                 }
>                 break;
>                    .
>                    .
>                    .

Deleting a Template

The following excerpt shows how to delete a template:

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

>                 try {
>                    /* WLPI Public API Method */
>                    /* Delete the Template */
>                    admin.deleteTemplate( templateId );

>                    /* Success (No exception trown) */
>                    System.out.println( "- Deleted" );
>                 }
>                 catch( Exception e ) {
>                    System.out.println( "*** Unable to delete Template" );
>                    System.err.println( e );
>                 }
>                 break;

>                    .
>                    .
>                    .

Getting Templates for an Organization

The following excerpt shows how to get templates for an organization:

>              /* List Templates for an Organization */
>              case '3' :
>                 /* Get Organization ID to query for */
>                 if( ( orgId = askQuestion( "\nEnter Organization ID" ) ) == null ) {
>                    /* User cancelled the operation */
>                    System.out.println( "*** Cancelled" );
>                    break;
>                 }

>                 /* WLPI Public API Method */
>                 /* Retrieve all templates defined in this organization */
>                 /* NOTE: Would be nice to add code to capture any
>                  * thrown exceptions */
>                 List templateList = admin.getTemplates( orgId );

>                 /* Any templates defined ? */
>                 if( templateList.size() == 0 )
>                    System.out.println( "\nNo template defined" );
>                 else
>                    System.out.println( "\nDefined Templates:" );

>                 /* Process the list to display Templates */
>                 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 */
>                    System.out.println( "- Template ID: " + templateInfo.getId() );

>                    /* Retrieve and display template name */
>                    System.out.println( "  Name:        " +
>                       templateInfo.getName() + "\n" );
>                 }
>                 break;
>                    .
>                    .
>                    .