Configuring Event Keys

This section explains how to configure event keys, including the following topics:

• Overview of Event Keys

• Adding an Event Key

• Getting Event Key Information

• Updating an Event Key

• Deleting an Event Key

• Example of Configuring Event Keys

For additional information, see "Configuring Event Keys" in Configuring Workflow Resources in Using the WebLogic Integration Studio.

 

---

Overview of Event Keys

An event key enables the Event Processor to calculate a unique key value for an inbound event by evaluating a workflow expression against the event data. Typically, the workflow expression extracts information from a named field in the incoming event data using a field reference or function call.

Event keys are characterized by two attributes—Content Type and Event Descriptor—and contain the contents of the workflow expression that extracts the unique key value from the particular Content Type and Event Descriptor attributes, as well as the plug-in-supplied field that supports that data type.

The following table describes the event key attributes.

Table 11-1 Event Key Attributes  

Event Key Attribute	Description
Content Type	Multipurpose Internet Mail Extensions (MIME) type for the event data that identifies the underlying data type. The default content type supported by WebLogic Integration is text/xml (that is, XML documents). Plug-ins can be created to handle additional content types, for example, binary COBOL Copy Book records, comma-separated values (CSV), proprietary file formats (for example, Microsoft Word or Excel), serialized Java objects, HTML, SGML, and so on. For more information about programming BPM plug-ins, see Programming BPM Plug-Ins for WebLogic Integration.
Event Descriptor	Optionally, provides additional schema-level information to define the data format. Note: Some content types do not require additional information to define the data format. In the case of the default content type, text/xml, the event descriptor reflects the XML document type, and matches either the Public ID or System ID (if the Public ID is not defined) in the DOCTYPE DTD (Document Type Definition), if one is declared by the incoming document. If a DOCTYPE is not declared, the event descriptor matches the document root element name. Plug-in-supported content types should use the event descriptor, if necessary, to provide sufficient information to enable a field reference to extract the specified field from the event data. In cases where the data are not self-describing (for example, a raw binary record image), the event descriptor must provide sufficient information to enable the field reference(s) to access the relevant data dictionary service to retrieve, for example, the byte offset, length, and data type of the referenced field.

 

The Event Processor is able to calculate a unique key value for any incoming event. If the event is destined for a particular workflow instance, as in the case of an Event node, it is necessary to match the calculated key value to the ID of the target workflow instance. This match is achieved through the Event Watch table, which is used to associate the incoming content type, event descriptor, and key value with the waiting instance and Event node IDs. The Event Watch table is also used to handle triggered workflows that are instantiated in response to the receipt of a particular content type, event descriptor, and key value combination (and in this case, the instance ID is null).

 

---

Adding an Event Key

To add an event key, use the following com.bea.wlpi.server.admin.Admin method:

public void addEventKey(
  com.bea.wlpi.common.EventKeyInfo eventKeyInfo
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

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

Table 11-2 addEventKey() Method Parameter  

Parameter	Description	Valid Values
eventKeyInfo	New event key information.	An EventKeyInfo object. For information about defining the EventKeyInfo object, see EventKeyInfo Object.

 

For example, the following code adds an event key based on the contents of the specified eventKeyInfo object. In this example, admin represents the EJBObject reference to the Admin EJB.

admin.addEventKey(eventKeyInfo);

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

 

---

Getting Event Key Information

To get information about an event key, use the following com.bea.wlpi.server.admin.Admin method:

public java.util.List getEventKeyInfo(
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

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

For example, the following code gets event key information and saves it to the eventKeys list object. In this example, admin represents the EJBObject reference to the Admin EJB.

List eventKeys = admin.getEventKeyInfo();

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

 

---

Updating an Event Key

To update an event key, use the following com.bea.wlpi.server.admin.Admin method:

public void updateEventKey(
  com.bea.wlpi.common.EventKeyInfo eventKeyInfo
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

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

Table 11-3 updateEventKey() Method Parameter  

Parameter	Description	Valid Values
eventKeyInfo	Event key information that you want to update.	An EventKeyInfo object. For information about defining the EventKeyInfo object, see EventKeyInfo Object.

 

For example, the following code updates an event key based on the contents of the specified eventKeyInfo object. In this example, admin represents the EJBObject reference to the Admin EJB.

admin.updateEventKey(eventKeyInfo);

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

 

---

Deleting an Event Key

To delete an event key, use the following com.bea.wlpi.server.admin.Admin method:

public void deleteEventKey(
  com.bea.wlpi.common.EventKeyInfo eventKeyInfo
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

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

Table 11-4 deleteEventKey() Method Parameter  

Parameter	Description	Valid Values
eventKeyInfo	Event key that you want to delete.	An existing EventKeyInfo object. For information about defining the EventKeyInfo object, see EventKeyInfo Object.

 

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

admin.deleteEventKey(eventKeyInfo);

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

 

---

Example of Configuring Event Keys

This section provides excerpts from the command-line administration example showing how to configure event keys.

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

• Adding an Event Key

• Deleting an Event Key

• Getting Event Keys

• Updating Event Keys

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 Administration v1.1  ---" );

/* 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) Roles" );
   System.out.println( "3) Users" );
   System.out.println( "4) Security Realm" );
   System.out.println( "5) Business Operations" );
   System.out.println( "6) Event Keys" );
   System.out.println( "7) Business Calendars" );
   System.out.println( "8) EJB Catalog" );
   System.out.println( "9) Server Properties" );
   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 Event Keys. 
 * An event key is used to identify the 
 * workflow definitions or instance(s) that are associated with an incoming
 * XML document. Usage of an event key avoids a sequential search of all XML 
 * based workflow triggers in order to find the right one.
 */
public static void mngEventKeys() {
   EventKeyInfo eventKeyInfo;
   List eventKeyList;
   String eventKeyRoot;
   String eventKeyExpr;
   //		boolean isGetDefinition;
   //		BusinessCalendarInfo calendarInfo;
   //		String answer;
   //		String calendarDefinition;
   //		String calendarId;
   //		String calendarName;
   //		String calendarTimezone;	// XML Document

   /* 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---            Event Keys            ---" );
         System.out.println( "\nEnter choice:" ); 
         System.out.println( "1) Add an Event Key" );
         System.out.println( "2) Delete an Event Key" );
         System.out.println( "3) List all Event Keys" );
         System.out.println( "4) Update an Event Key" );
         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 ) {
         .
         .
         .

Adding an Event Key

The following excerpt shows how to add an event key:

         /* Add an Event Key */
         case '1' :
            /* Get Event Key XML Document root for the new Event Key */
            if( ( eventKeyRoot = askQuestion( "\nEnter the Event Key XML 
               Document Root" ) ) == null ) {
               /* User cancelled the operation */
               System.out.println( "*** Cancelled" );
               break;
            }

            /* Get Expression for the new Event Key */
            if( ( eventKeyExpr = askQuestion( "Enter the Event Key Expression" ) )
               == null ) {
               /* User cancelled the operation */
               System.out.println( "*** Cancelled" );
               break;
            }

            try {
               /* Create an EventKeyInfo object; required to invoke 
                * the add method */
               eventKeyInfo = new EventKeyInfo( 
                  "text/xml", eventKeyRoot, eventKeyExpr, null, 0 );

               /* WLPI Public API Method */
               /* Add the Event Key */
               admin.addEventKey( eventKeyInfo );

               /* Success (No exception trown) */
               System.out.println( "- Added" );
            }
            catch( Exception e ) {
               System.out.println( "*** Unable to add the Event Key" );
               System.err.println( e );
            }
            break;
            .
            .
            .

Deleting an Event Key

The following excerpt shows how to delete event keys:

         /* Delete an Event Key */
         case '2' :
            /* Get Event Key XML Document root for the Event Key to delete */
            if( ( eventKeyRoot = askQuestion( "\nEnter the root for 
               the Event Key to delete" ) ) == null ) {
            /* User cancelled the operation */
               System.out.println( "*** Cancelled" );
               break;
            }

            try {
               /* To invoke the delete method, we need to create an 
                * EventKeyInfo object which basically consist of an 
                * XML Document root and an expression. Since we are 
                * deleting the expression is not required. */
               eventKeyExpr = "";

               /* Create an EventKeyInfo object; required to 
                * invoke the delete method */
               eventKeyInfo = new EventKeyInfo( 
                  "text/xml", eventKeyRoot, eventKeyExpr, null, 0 );
   
               /* WLPI Public API Method */
               /* Delete the Event Key */
               admin.deleteEventKey( eventKeyInfo );

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

Getting Event Keys

The following excerpt shows how to get event keys:

         /* List all Event Keys */
         case '3' :
            try {
               /* WLPI Public API Method */
               /* Retrieve all Event Keys */
              eventKeyList = admin.getEventKeyInfo();

               /* Any Event Keys defined ? */
               if( eventKeyList.size() == 0 )
                  System.out.println( "\nNo Event Keys defined" );
               else	
                  System.out.println( "\nDefined Event Keys:" );
          
               /* Process the list to display event keys and attributes */
               for( int i = 0; i < eventKeyList.size(); i++ ) {
                  /* Retrieve an element from the list */
                  eventKeyInfo = ( EventKeyInfo )eventKeyList.get( i );

                  /* WLPI Public API Method */
                  /* Retrieve and display the XML Document root */
                  System.out.println( "- Content Type:       " + 
                    eventKeyInfo.getContentType() );

                  /* WLPI Public API Method */
                  /* Retrieve and display the XML Document root */
                  System.out.println( "- Event Descriptor:       " + 
                    eventKeyInfo.getEventDescriptor() );

                  /* WLPI Public API Method */
                  /* Retrieve and display calendar name */
                  System.out.println( "  Expression: " + 
                     eventKeyInfo.getExpr() );
               }
            }
            catch( Exception e ) {
               System.out.println( "*** Unable to retrieve Event Keys" );
               System.err.println( e );
            }
            break;
            .
            .
            .

Updating Event Keys

The following excerpt shows how to update an event key:

         /* Update an Event Key */
         case '4' :
            /* Get Event Key XML Document root for the Event Key to update */
            if( ( eventKeyRoot = askQuestion( "\nEnter the root for the 
               Event Key to update" ) ) == null ) {
               /* User cancelled the operation */
               System.out.println( "*** Cancelled" );
               break;
            }

            /* Get the new Expression for the Event Key */
            if( ( eventKeyExpr = askQuestion( "Enter the new Event Key 
               Expression" ) ) == null ) {
               /* User cancelled the operation */
               System.out.println( "*** Cancelled" );
               break;
            }

            try {
               /* Create an EventKeyInfo object; required to invoke 
                * the update method */
               eventKeyInfo = new EventKeyInfo( 
                  "text/xml", eventKeyRoot, eventKeyExpr, null, 0 );

               /* WLPI Public API Method */
               /* Update the Event Key */
               admin.updateEventKey( eventKeyInfo );

               /* Success (No exception trown) */
               System.out.println( "- Updated" );
            }
            catch( Exception e ) {
               System.out.println( "*** Unable to update the Event Key" );
               System.err.println( e );
            }
            break;
            .
            .
            .