Monitoring the BPEL Service Engine

You can monitor BPEL Service Engine instances using the Command Line tool or from your own monitoring application using the BPEL Monitor API library. These monitoring tools enable you to view and change BPEL variable values, and suspend, resume, or terminate BPEL instances.

Installing the BPEL Monitor API and Command Line Monitoring Tool

The bpelMonitorTool.zip file contains the BPEL Monitor API, the Command Line Monitoring tool, the BPELManagement API Javadoc and the BPEL Monitor User Manual.

To install the monitoring tool:

1. Create a new directory named bpelsemonitor in your file-system, for example, C:\GlassFishESB\glassfish\addons\bpelsemonitor.

2. Download the bpelMonitorTool.zip and extract the file to your new bpelsemonitor directory.

3. Edit the monitorcommand.properties file, included in the bpelMonitorTool.zip file, with appropriate values for your environment.

4. Make script executable, as follows:

   • For Unix:

     1. cd to scripts.

     2. chmod a+x runbpelmonitor.sh.

     3. Execute runbpelmonitor.sh in the scripts directory.

   • For Windows:

     Execute runbpelmonitor.bat in the scripts directory.

   ---

   Note –

   If you are using the BPEL Monitor API alone in your own monitoring application, you need the bpelmonitor-api.jar and the other JAR files downloaded in the lib directory.

   ---

Using the BPEL Monitor Command Line Tool

The lightweight command line monitoring tool uses the BPEL Monitoring API library to manage tasks interactively.

To use the BPEL Monitor command line tool

Before You Begin

Enable monitoring in the BPEL Service Engine properties.

1. From the NetBeans IDE Services window, Start the GlassFish Application Server.

2. Start the sun-bpel-engine, under JBI -> Service Engines.

3. Once the Service Engine has started, open the properties.

   There are two properties related to BPEL monitoring:

   • Monitoring Enabled - required for using the BPEL Monitor API as well as every command in the Command Line Tool for BPEL monitoring.

   • Monitoring Variable Enabled - required for using variable related API such as changeVariableValue, getVariableValue, listBPELVaraibles, as well as getInvokeeInstance, getInvokerInstance, and command:l, v, k, pr, and ch.

4. Set the Monitoring Enabled property to true (checked). Set Monitoring Variable Enabled to true also if you are using variable related API.

   

   ---

   Note –

   To monitor a BPEL project using the command line tool, deploy the project after the Monitor Enabled property is set to true, otherwise, the "a" command might not produce the correct results.

   ---

5. From your command line, cd to /bpelmonitor/scripts and execute runbpelmonitor.sh.

   The following list of available commands is displayed:

   • [a] Show deployed bpel processes

   • (su="suName") The service unit name is found in the NetBeans IDE Services window under /JBI/Service Assemblies/YourServiceAssembly/

   • [b] Show bpel instances status ([processId="string"] [status="running|completed|suspended|terminated|faulted"] [instid="instanceId"] [max="maximumInstances"] [sort="startTime|endTime|updatedTime"] [order="asc|desc"])

   • [c] Show activity status on bpel instance (instid="instanceId")

   • [f] Show instance fault (instid="instanceId")

   • [s] Suspend bpel instance ([instid="instanceId1|instanceId2|instanceId3|..."] [processId="string"] [csv="The CSV File"])

   • [r] Resume bpel instance ([instid="instanceId1|instanceId2|instanceId3|..."] [processId="string"] [csv="The CSV File"])

   • [t] Terminate bpel instance ([instid="instanceId1|instanceId2|instanceId3|..."] [processId="string"] [csv="The CSV File"])

   • [l] List bpel variables (instid="instanceId" [varname="variableName"] )

   • [v] View bpel variable value (instid="instanceId" varid="variableId")

   • [k] Change bpel variable value (instid="instanceId" varid="variableId" newval="theNewValue" [part="partName"] [xpath="theXpathToTheLeafNodeToChange"] )

   • [ch] Show invokee bpel instances status (instid="instanceId" [actid="invokeActivityId"] )

   • [pr] Show invoker bpel instances status (instid="instanceId" [actid="receiveActivityId"] )

   • [h] Help

   • [e] Exit

6. After the prompt ">", type the letter of the command, or type "help" or "h" for help or examples.

   IF you type "help" or "h" it displays the list of commands again, and includes the following:

   • Press: m + return for examples and usage.

   • Press: other key + return to return.

Command Usage Pattern

The "help" or "h" command displays a list of available commands and the required and optional parameters for each command. For example:[l] List bpel variables (instid="instanceId" varname="variableName" )

In this example, "l" is the command letter. instidis a required parameter. varnameis an optional parameter, which is implied by the enclosing brackets ([]). Parameters that are not enclosed by brackets are required with the command.

To specify a command with parameters do the following:

• After the prompt ">", type the letter of the command and any required parameters and any optional parameters as follows: >l instid="192.168.0.117:757d7361:115d8cdb431:-7fdc" varname="NewWSDLOperationIn"

• Specify the parameter and value as paramName=?Value?. The double quotes are required for the value. There are no spaces between and after '='.

• Type the command and its params in one line, or use '\' to continue to next line.

• Specify mulitple value for a parm using '|', for example: >b status=”running|completed|terminated”

• You can direct the command output to a file in file system, either in append or overwrite mode. This can be done for any command in the same way, the output to the console is unchanged.

  The output can be written to the specified file in the following modes:

  • Writing the output to the file, given the full file path, overwriting the file if it currently exists:>b status="running" >"c:\work\output.txt"

  • Writing the output to the file, given the full file path, appending to the file if it currently exists: >b status="running" >"c:\work\output.txt"+

More Information

For a more extensive manual on how to use the BPEL Monitor Command Line tool, see the BPEL Monitor User Manual included with the ZIP file.