Collect troubleshooting data for Business Process Choreographer problems in Websphere Process Server

Collect troubleshooting data for Business Process Choreographer problems in WebSphere Process Server. Gathering this information before calling IBM support will help familiarize you with the troubleshooting process and save you time. You can use ISA Lite to automate part of this process.

Required diagnostic information

Gather the following information and files:

General diagnostic information

• Problem description
• Environment description
• Server logs: All files from the following directories:
  <profile_root>/<profile_name>/logs/<server_name>
  <profile_root>/<profile_name>/logs/ffdc
• Project interchange (PI) or enterprise archive (EAR) file

Business Process Choreographer diagnostic information

• Deployment manager or Stand-alone Server configuration directory
• Custom code artifacts using BPC APIs (if applicable)
• Install logs (if related to an issue during installation or upgrade)
• Staff and People directory information (if applicable)

Note: For more details, see the "Instructions for gathering the diagnostic information below".

Setting the trace setting

Set the trace string as shown in the following table, then reproduce the problem. For instructions, see the main WebSphere Process Server MustGather document.

Please note that trace strings vary depending on the problem. IBM support can help you determine the best string to use for the problem and for system performance. The following table includes examples of trace settings for various problems:

Problem	Trace setting
General BPC Issues	com.ibm.bpe.*=all: com.ibm.task.*=all
Business Process Choreographer staff, people, and authorization	com.ibm.bpe.*=all: com.ibm.task.*=all: com.ibm.ws.security.*=all: com.ibm.ws.staffsupport.*=all Versions 6.1 and 6.2 with the Virtual Member Manager: com.ibm.websphere.wim.*=all: com.ibm.ws.wim.*=all: com.ibm.wsspi.wim.*=all
Database	Version 6.0: com.ibm.bpe.*=all: com.ibm.task.*=all: RRA=all: Transaction=all Versions 6.1 and later: com.ibm.bpe.*=all: com.ibm.task.*=all: RRAMORE=all: Transaction=all Frequent deadlocks: com.ibm.bpe.*=all: com.ibm.task.*=all: WAS.clientinfopluslogging=all
Emitting events and payloads for Common Event Infrastructure (CEI)	com.ibm.bpe.*=all: com.ibm.task.*=all: com.ibm.websphere.cem.*=all: com.ibm.events.*=all: com.ibm.ws.events.*=all: com.ibm.websphere.events.*=all: com.ibm.bpe.events.*=all: CommonEventInfrastructure=all
Invoke activities	For a Service Component Architecture (SCA) binding: com.ibm.bpe.*=all: com.ibm.task.*=all: SCA.*=all For a Web services binding: com.ibm.bpe.*=all: com.ibm.task.*=all: com.ibm.ws.webservices.*=all
Business Process Choreographer Observer	com.ibm.bpe.*=all: com.ibm.task.*=all: com.ibm.bpe.observer.*=all
Business Process Choreographer Explorer only (excluding BPC Engine and HTM tracing)	com.ibm.bpe.client.*=all
Compensation	com.ibm.bpe.*=all: com.ibm.task.*=all: compensation=all
JavaServer Faces (JSF)	com.ibm.bpe.*=all: com.ibm.task.*=all: com.ibm.ws.jsf=all
Problems that require tracing a wsadmin script	To write wsadmin trace to the profile_root\logs\wsadmin.traceout file, in the profile_root\properties\wsadmin.properties file, remove the comment symbol from the following line: 'com.ibm.ws.scripting.traceString=com.ibm.*=all'

Guidelines for setting the traces

• Make sure that all active members of the cluster that contain the Business Flow Manager and Human Task Manager containers are traced.
• For deployment problems with installing or uninstalling, also trace the deployment manager and include the relevant files from each.
• For problems with Business Process Choreographer Explorer or Business Process Choreographer Observer: Beginning in version 6.1, these were moved to the support cluster in a standard deployment environment. The trace must reflect the appropriate clusters.
• If you suspect problems with node synchronization, including deployment-related problems, trace the node agents.

IBM Support Assistant

Automated data collectors are available in IBM Support Assistant to improve the accuracy of complete data collection. You can use ISA Lite to automate the gathering of the required log files.

Note: When you use ISA Lite, also gather a detailed problem description, environment description, and other requested materials, such as a PI file.

IBM Support Assistant Lite	IBM Support Assistant Workbench
Download | Learn more	Download | Demo | Learn more
A special offering that contains only the data-collector component of IBM Support Assistant Workbench	For a full range of problem-solving features, the workbench contains all of the data-collection capability of ISA Lite and much more!

Note: Use the following Menu Selection when using the IBM Support Assistant
WebSphere Process Server > Business Process Choreographer > General Problem

Instructions for collecting the diagnostic information

To collect the information, follow these steps:

1. Problem Description: Provide a detailed description of your problem. Include sample input values as needed, along with your own analysis of the problem.
   • Provide detailed instructions for how to recreate your issue.
   • Provide the names of any modules, components, or bindings which you believe may be involved in the issue.
   • How often does the problem occur? Include details about any recent problem occurrences including timestamps.
   • Is there any workarounds you use for the issue?
   • If you have not provided it already, supply the impact this issue is having on your company, including:
     - any upcoming deadlines and dates
     - if the problem is seen in production, development, or testing
     - any realized or potential effect on customers
     
2. Environment Description: Provide information about your WebSphere Process Server environment.
   • Generate and upload a versionReport.html file:
     
     
     <install_root>/bin/genVersionReport.(sh|bat) -maintenancePackages
     
     Run this command on each physical installation of a WebSphere product in your environment, and upload the resulting files along with an indication of which installation it comes from.Versions of all the databases used (especially the BPC DB)
   • Version of the operating system. If you have a cluster, specify the versions of the operating systems for all the workstations in the cluster.
   • If the problem is occurring in a cluster, describe the topology of your clustered environment.
     
3. Server logs: Provide log information for each of the involved servers after reproducing the issue with the recommend trace setting.
   • State the exact error message received
   • Specify the log file in which the error occurs, as well as the associated time stamp
   • Use ISA Lite or gather the logs and FFDC files from each server that is involved in the issue.
     1. If using default WPS profile directory, package the following directory:
        <WPS_install>/profiles/<profile_name>/logs/<server_name>
        <WPS_install>/profiles/<profile_name>/logs/ffdc
     2. If using the test server, package the following directory:
        <WID_install>/pf/<profile_name>/logs/<server_name>
        <WID_install>/pf/<profile_name>/logs/ffdc
     3. If using a custom profile path, package the following directory:
        <profile_root>/<profile_name>/logs/<server_name>
        <profile_root>/<profile_name>/logs/ffdc
        
4. Project Interchange: Create a Project Interchange file for specific test scenarios. If possible, simplify the scenario to isolate the problem.
   Create this file as follows:
   1. From within WebSphere Integration Developer, select File > Export.
   2. Select Project Interchange, and select the modules relevant to your project, then export them to a file. Try to provide the most simplified test case that exhibits your problem. Make sure all involved business processes and human tasks are included.
   3. Include any external dependencies, such as JAR files, that are needed to run your test scenario.
   4. Include any input data or files needed to run the test scenario.
5. Configuration Info: Use ISA Lite or manually collect the contents of the <profile_root>/<profile_name>/config directory. Where the profile is the deployment manager for a clustered environment.
6. Custom code artifacts: If the problem involves the use of any BPC or HTM APIs with any client, such as Portal or a custom user interface, include all text readable artifacts the show the Business Flow Manager or Human Task Manager APIs.
7. Install Logs: If the BPC problem is related to installation or upgrade process, collect the logs from the installation and any related profiles:
   • <install_root>/logs
   • <profile_root>/<profile_name>/logs
8. Staff and People Directory Authorization: Also collect this information if the problem is related to staff, and people directory authorization.
   1. Include the XSL file that is used for transformations during the Business Process Execution Language (BPEL) deployment:
      • For the Lightweight Directory Access Protocol (LDAP) staff or people plug-in, the default sample file is LDAPTransformation.xsl.
      • For the custom user registry staff or people plug-in, the default sample file is UserRegistryTransformation.xsl.
      • For the Virtual Member Manager staff or people plug-in, the default sample file is VMMTransformation.xsl.
        
        To make sure the file is from the correct location, check the staff or people plug-in configuration. The location is defined as part of the configuration. The Java Naming and Directory Interface (JNDI) is also set in the project interchange in WebSphere Integration Developer, in the human tasks.
        
        Note: Do not use the default XSL files because they might be updated when maintenance is applied to the system. Instead, create a new staff or people configuration with a custom XSL file (which is usually initially copied from the supplied samples).
   2. If LDAP is involved, include a sample of the LDAP Directory Interchange Format (LDIF) data that is exported from the LDAP for at least one group and at least one user that are specific to the problem.
   3. If you are using custom verbs, include the Verbset.xml file.

What to do next

1. Review the logs and traces at the time of the problem to try to determine the source of the problem.
   
   
2. Use IBM Support Assistant to search for known problems in the information center, forums, and technotes.
   
   
3. If you cannot find related problems or cannot solve the problem, send the information you have collected to IBM by following the instructions in Exchanging Information with IBM Technical Support.
   
   

For a listing of all technotes, downloads, and educational materials that are specific to WebSphere Process Server , search the WebSphere Process Server support page.