IBM Support

Collect troubleshooting data for Business Process Choreographer problems in IBM Business Process Manager (BPM) and IBM Business Automation Workflow (BAW)

Troubleshooting


Problem

You are having a WebSphere Business Process Choreographer or Business Process Choreographer Explorer problem in IBM Business Process Manager or IBM Business Automation Workflow. You would like to know what documentation you must collect (MustGather) so that the support team can diagnose your problem. If you gather this documentation before contacting support it will expedite the troubleshooting process, and save you time.

Resolving The Problem

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
  • Note: The profile_root variable refers to the location in which your profile is installed. The profile_name variable reference to the name of the profile in your environment. The server_name variable refers to the name of your server.  Be sure to include the Support Server directory since some BPC components run on it.
  • 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)
  • Installation log files (if related to an issue during installation or upgrade)
  • Staff and people directory information (if applicable)

Note: For more details, see the Instructions for collecting the diagnostic information.
 

Setting the trace setting

Set the trace string as shown in the following table and then reproduce the problem. For instructions, see the IBM Business Process Manager or WebSphere Process Server MustGather document.



Note: 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

When you are using Virtual Member Manager (VMM) or federated repositories:
com.ibm.websphere.wim.*=all:
com.ibm.ws.wim.*=all: com.ibm.wsspi.wim.*=all
 
Database IBM Business Process Manager products and WebSphere Process Server V6.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.
  • Set the number of historical trace files to 10 and set the size of the trace file to 100MB.
  • 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: these traces are written 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
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 one of the following menu selections when you use the IBM Support Assistant:
  • IBM Business Process Manager > Business Process Choreographer > General Problem
  • 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 that you believe might be involved in the issue.
    • How often does the problem occur? Include details about any recent problem occurrences including time stamps.
    • Are 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 IBM Business Process Manager or WebSphere Process Server environment.
    • Generate and upload a versionReport.html file:


      install_root/bin/genVersionReport.(sh|bat) -maintenancePackages
      The install_root variable refers to the location in which you installed the product.

      Run this command on each physical installation of an IBM Business Process Manager or WebSphere-branded product in your environment. Upload the resulting files along with information that indicates from where the files originate. Also, provide information on the versions of all the databases that you are using (especially the BPC database).
    • Provide the 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 recommended trace setting.
    • State the exact error message that you receive
    • 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 you are using the default IBM Business Process Manager or WebSphere Process Server profile directory, package the following directories:
        • install_root/profiles/profile_name/logs/server_name
        • install_root/profiles/profile_name/logs/ffdc
          The install_root variable refers to the location in which you have installed an IBM Business Process Manager or WebSphere Process Server product. The profile_name variable refers to the name of your profile. The server_name variable refers to the name of your server.
      2. If you are using the test server, package the following directories:
        • WID_IID_install_root/pf/profile_name/logs/server_name
        • WID_IID_install_root/pf/profile_name/logs/ffdc
          The WID_IID_install_root variable refers to the location in which you have installed WebSphere Integration Developer or IBM Integration Designer. The profile_name variable refers to the name of your profile. The server_name variable refers to the name of your server.
      3. If you are using a custom profile path, package the following directories:
        • profile_root/profile_name/logs/server_name
        • profile_root/profile_name/logs/ffdc
          The profile_root variable refers to the location in which you have created a profile for the IBM Business Process Manager or WebSphere Process Server product. The profile_name variable refers to the name of your profile. The server_name variable refers to the name of your server.
  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 IBM Integration Designer or 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 that all involved business processes and human tasks are included.
    3. Include any external dependencies, such as Java archive (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 business process choreographer (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 log files 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 that 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 IBM Integration Designer or WebSphere Integration Developer within 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 log files 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 your product, search the following support pages:  

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSFTDH","label":"IBM Business Process Manager Standard"},"Component":"Business Process Choreographer","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"8.6;8.5;8.0.1;8.0;7.5.1;7.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSFTBX","label":"IBM Business Process Manager Express"},"Component":"Business Process Choreographer","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"8.6;8.5;8.0.1;8.0;7.5.1;7.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSFTN5","label":"IBM Business Process Manager Advanced"},"Component":"Business Process Choreographer","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"8.6;8.5;8.0.1;8.0;7.5.1;7.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS8JB4","label":"IBM Business Automation Workflow"},"ARM Category":[{"code":"a8m50000000CcVKAA0","label":"Advanced Content\/ SCA->BPC (Business Process Choreographer)"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"18.0;19.0;20.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym

BPM; BAW

Document Information

Modified date:
01 March 2022

UID

swg21270939

Page Feedback