Using the Data Integration Plug-In

 

Within most enterprise application integration (EAI) domains, data translation is an inherent part of an EAI solution. XML is quickly becoming the standard for exchanging information between applications, and is invaluable in integrating disparate applications. However, most data transformation engines do not support translations between binary data formats and XML. The data integration plug-in provides for an exchange of information between applications by supporting data translations between binary formats from legacy systems and XML.

In addition to this data translation capability, the data integration plug-in provides a binary data event handler, in-memory caching of MFL documents and translation object pooling to boost performance, a BinaryData variable type to edit and display binary data, and execution within the process engine clustered environment.

This section provides information about the following topics:

• Data Translation with the Data Integration Plug-In

• Processing Event Data

• Enhancing Data Translation Performance

• Custom Data Types and the Data Integration Plug-In

• WebLogic Server Clustering Support

 

---

Data Translation with the Data Integration Plug-In

The data integration plug-in provides XML and non-XML translation capabilities from within business process management (BPM). To perform one of these translation actions, follow the steps below. For more information on the actions specific to BPM, refer to the BPM documentation.

1. Start BPM.

2. Open the desired template definition and double-click a task. The Task Properties dialog box opens (Figure 2-1).

   Figure 2-1 Task Properties Dialog Box

   

   
    

3. If the task contains the data translation action, select it from the list and click Update; then, proceed to step 4. Otherwise, click Add to add a new action. The Add Action dialog opens (Figure 2-2).

   Figure 2-2 Add Action dialog

   

   
    

4. Select Integration Actions to expand its action list, then select Data Integration and choose the action you want to perform (Translate XML to Binary or Translate Binary to XML).

Translate XML to Binary

To perform an XML to binary translation:

1. From the Add Action dialog (Figure 2-2), select XML to Binary Translation. The Translate XML to Binary dialog box opens (Figure 2-3).

   Figure 2-3 Translate XML to Binary Dialog Box

   

   
    

2. Enter data in the fields as described in the following table.

   Field	Description
   Message Format Parameters
   Name	The name of the message format. You can type a name directly in the text box or click Browse to select the document from the repository.
   Description	Displays the description of the message format. Note: This field is display only. You cannot edit this field.
   Notes	Displays the notes attached to the message format. Note: This field is display only. You cannot edit this field.
   Debug	Enable or disable debug messaging. When you select this option, the translation actions are written to the WebLogic Server log file.
   Message Format Action Buttons
   Browse	Allows you to browse MFL documents in the repository.
   View	Displays the items contained in the message format so you can verify that you have selected the correct document type for translation.
   Variable Parameters
   Input XML Variable	Displays the XML workflow variables. Select the variable you want to use in the translation, or create a new variable as follows: Type the name you want to assign to the new variable and click OK. A confirmation message box displays. Click Yes to create the new variable.
   Assign Result To	Displays the Binary Data workflow variables. Select the variable you want to use to store the translated information or create a new variable as follows: Type the name you want to assign to the new variable and click OK. Click Yes to create the new variable.

   
    

3. Click OK to save the translation information to the workflow.

Translate Binary to XML

To perform a binary to XML translation:

1. From the Add Action dialog (Figure 2-2), choose Integration Actions—>Data Integration—>Translate Binary to XML. The Translate Binary to XML dialog opens (Figure 2-4).

   Figure 2-4 Translate Binary to XML Dialog Box

   

   
    

2. Enter data in the fields as described in the following table.

   Field	Description
   Message Format Parameters
   Name	The name of the message format. You can type a name directly in the text box, or click Browse to select the message format from the repository.
   Description	Displays the description of the message format. Note: This field is display only. You cannot edit this field.
   Notes	Displays the notes attached to the message format. Note: This field is display only. You cannot edit this field.
   Debug	Enable or disable debug messaging. When you select this option, the translation actions are written to the WebLogic Server log file.
   Message Format Action Buttons
   Browse	Allows you to browse MFL documents in the repository.
   View	Displays the items contained in the message format so you can verify that you have selected the correct document type for translation.
   Variable Parameters
   Input Binary Variable	Displays the binary workflow variables. Select the variable you want to use in the translation, or create a new variable as follows: Type the name you want to assign to the new variable and click OK. A confirmation message box displays. Click Yes to create the new variable.
   Assign Result To	Displays the XML Data workflow variables. Select the variable you want to use to store the translated information, or create a new variable as follows: Type the name you want to assign to the new variable and click OK. Click Yes to create the new variable.

   
    

3. Click OK to save the translation information to the workflow.

 

---

Processing Event Data

The data integration plug-in provides functionality that allows binary data to trigger workflows by converting the binary data to XML or pre-processing it at the front end of event processing. This functionality is referred to as the "event handler." Publishing JMS messages to a topic causes the event handler to run.

There are three JMS properties required for the message to be pre-processed by the data integration plug-in:

• WLPIContentType: "binary/x-application/wlxt"

• WLPIPlugin: "com.bea.wlxt.WLXTPlugin"

• WLPIEventDescriptor: MFL document name

The first two JMS message properties are constant for all messages addressed to the event handler. The third property contains the name of the MFL document that describes the binary data in the message.

Note: The MFL document referenced in the WLPI EventDescriptor must be stored in the repository.

Listing 2-1 is a sample of the code used to build a message that is to be processed by the event handler.

Listing 2-1 Sample Event Handler Code

byte[] bindata = ... the binary data ...
pub = sess.createPublisher(topic);
BytesMessage msg = sess.createBytesMessage();
msg.writeBytes(bindata);
msg.setStringProperty("WLPIPlugin", "com.bea.wlxt.WLXTPlugin");
msg.setStringProperty("WLPIContentType",
 "binary/x-application/wlxt");
msg.setStringProperty("WLPIEventDescriptor", "mymfldoc");
pub.publish(msg);

This process is illustrated in the servlet sample application.

 

---

Enhancing Data Translation Performance

The data integration plug-in provides a configuration panel to administer and monitor the MFL document in-memory cache and enable or disable event handler debugging. Using this panel, you can adjust the in-memory cache and translation object pool to enhance the performance of your data translations.

Note: You must clear the MFL document in-memory cache in order for any updates you make to an MFL document to take effect.

To access the configuration panel, follow the steps below. For more information on the actions specific to business process management, refer to the business process management documentation.

1. Start BPM.

2. Choose Configuration—>Plugins. The Plugin Configuration dialog opens (Figure 2-5).

   Figure 2-5 Plugin Configuration Dialog Box

   

   
    

3. Choose Data Integration Plug-In and click Update. The Configuration dialog box for the data integration plug-in opens (Figure 2-6).

   Figure 2-6 Configuration Dialog Box for the Data Integration Plug-In

   

   
    

4. Use the fields as described in the table below to monitor and enhance translation performance.

   Field	Description
   Start mode
   Automatic	Select this option to have the data integration plug-in open automatically when BPM opens.
   Manual	Select this option to have the data integration plug-in available from BPM.
   Disabled	Select this option to disable the use of the data integration plug-in from BPM.
   Data Integration Object Pool
   Preferred Pool Size	Defines the maximum number of permanent objects in the pool. Use the slider to set the pool size to the desired number. Note: The translation engine creates temporary pool objects if the demand exceeds the preferred pool size you have set. These objects are deleted when they are returned to the pool.
   Current Size	Displays the number of objects currently in the pool.
   High Water Mark	Displays the largest number of objects in the pool since the server was started.
   MFL Cache
   MFL Requests	Displays the total number of requests for translation of MFL documents.
   Cache Hits	Displays the number of requests where the MFL document needed was already in the cache.
   Hit Ratio	Displays the percentage of requests satisfied by retrieving MFL documents from the cache, rather than from the database.
   MFL Cache Action Buttons
   Refresh	Sends a request to the server to update the MFL cache statistics.
   Clear	Clears the MFL document cache. This requires all future translation requests to load MFL documents from the repository.
   Event Handler Options
   Enable Debug Messaging	Enables or disables debug messaging for the Event Handler. If enabled, debug messages are written to the WebLogic Server log file during translation.

The data integration plug-in provides additional display and edit capabilities over the standard BPM functionality. These capabilities are provided by the Hex Editor component of Format Tester for displaying and editing binary data.

 

---

Variable Types and the Data Integration Plug-In

The data integration plug-in provides a BinaryData variable type, that you can use to edit and display binary data. The BinaryData variable acts as a container for a logical group of binary data with additional display capabilities. The BinaryData variable is used by programs that call the actions provided by the data integration plug-in to pass and receive binary data. It is also used by the Workflow Instance Monitor to display and edit the contents of a binary variable.

 

---

Custom Data Types and the Data Integration Plug-In

Data integration includes a user defined type feature that allows you to create custom data types specific to your unique data type requirements. The user defined type feature allows these custom data types to be plugged in to the data integration run-time engine. Once a user defined data type is plugged-in, it is indistinguishable from a built-in data type in both features and function.

 

---

Configuring User Defined Data Types

User Defined Types used by the data integration plug-in are stored in the WebLogic Integration repository as CLASS documents. At runtime, the data integration plug-in loads user defined type classes from the repository as required. In addition, the data integration plug-in will export the MFL and class files required to support the active template allowing a template to be imported on another business process management instance intact. Class documents may be placed in the repository using one of the following methods:

• Using Format Builder

• Using the Repository Import Utility

Using Format Builder

Perform the following steps to publish a user defined type to the repository using Format Builder.

1. Start Format Builder by choosing Start—>Programs—>BEA WebLogic E-Business Platform—>WebLogic Integration 2.1—>Format Builder. The Format Builder main window displays.

2. Choose Repository—>Log In. The WebLogic Integration Repository Login window opens.

   

   
    

3. Enter the user ID specified for the server in the User Name field. (The default is: wlipisystem.)

4. Enter the password specified for the server in the Password field. (The default is: wlpisystem.)

5. Enter the server name and Port number in the Server[:port] field.

   Note: The WebLogic Integration Repository Login window allows up to three unsuccessful login attempts, after which, a login failure message is displayed. If you experience three login failures, choose Repository—>Log In to repeat the login procedure.

6. Click Connect. If your login is successful, the Login window disappears and the Format Builder Title bar displays the server name and port number entered on the WebLogic Integration Repository Login window. You may now choose any of the active repository menu items to access.

7. Choose Tools—>User Defined Types. The Add/Remove User Defined Types dialog box opens.

   With a repository connection established, the Add/Remove User Defined Types dialog box displays the status of each registered user defined type and allows for its publication to the repository. The user defined type repository status is reflected by an icon of a ball preceding the type name of each installed user defined type.

   

   
    

   The color of the icon associated with each user defined type indicates its status:

   • Green - The user defined type has been published to the repository.

   • Yellow - The user defined type has been published to the repository, however, the local version of the class differs from the repository version.

   • Red - The user defined type does not exist in the repository.

8. Select the class you want to publish from the list of Installed Types and click Publish. The icon for the selected entry should become green indicating the class was successfully placed in the repository.

Using the Repository Import Utility

Perform the following steps to use the repository import utility to import Java class files, including User Defined Types.

1. Create a wlxt-repository.properties file in the CLASSPATH. The content of this file should be as follows:

   wlxt.repository.url=<server url>

   For example:

   wlxt.repository.url=t3://localhost:7001

2. Type the following command to pass the class file name on the Import command line.

   java com.bea.wlxt.repository.Import <file name>

   For example, the following command imports all the class files in the current directory:

   java com.bea.wlxt.repository.Import *.class

Note: Any Java class file may be imported to the repository using the Repository Import utility, not just User Defined Types. This is useful if a user defined type relies on additional class files that do not extend the com.bea.wlxt.bintype.Bintype class.

 

---

WebLogic Server Clustering Support

The data integration plug-in can operate successfully in a WebLogic Server clustered environment. In a clustered environment, the plug-in administrator is connected to only one node of the cluster at any given time. Any commands issued by the administrator must be propagated to the other nodes in the cluster.

Communication among the various servers in a cluster is handled through the use of a JMS topic. The topic is used for communication on different nodes in a cluster in WebLogic Integration.

Configuring the Data Integration Plug-In for Clustering

If you want to take advantage of the clustering capability, you must configure the data integration plug-in as follows:

1. Create a JMS topic on one of the servers within the cluster. The JNDI name of this topic must be as follows:

   com.bea.wlxt.cluster.BroadcastTopic

   Note: Refer to the WebLogic Server documentation for more information on creating JMS topics.

2. Open the config.xml file in a text editor. This file can be found in the config\samples\ directory where you have WebLogic Integration installed.

   Note: The config directory contains separate subdirectories for each domain you have created. Each of these subdirectories contains its own config.xml file. Make sure you open the file under the correct domain.

3. Locate the <Application> section for business process management and add the following anywhere within this section:

   <EJBComponent Name="wlxt-cluster"
    DeploymentOrder="99"
    Targets="[server_name]"
    URI="wlxtmb.jar"
   />

4. Save the config.xml file.

Note: You must restart the server in order for the change to the config.xml file to be recognized.