The following information introduces tools, features, and guidelines that can be used for debugging and troubleshooting composite applications. This topic provides information on the following:
- Composite application debugging guidelines and tips
- Property Broker Monitor
- Topology Peek
- OSGi Console
- Using logging on the Notes plugin side
- Using Composite Application Editor logging
- Information on On-Disk Data
- Additional potential composite application issues
Composite application debugging guidelines and tips
Use the following guidelines and tips when debugging your composite application.
Did the layout of the application render? Check the following:
- Is the application on a server and can you access that server?
- Is there a problem with the CA XML file?
- Open the CA.XML to edit the composite application in Domino Designer by navigating to Composite Applications->Applications
- Verify there is only one CA.XML file.
- Export the file and view the contents in a browser.
- Export the file and then refresh the file to update the timestamp. This will force provisioning to occur again.
Why did one or more of the components not render?
The problem may be with an Eclipse plugin. Check the following to help you determine if this is the problem:
- Are the plugins installed? Check the file system to see if the plugin component was installed. An example of a typical plugin path might be C:\notes\data\workspace\applications\eclipse.
- If the plugins are missing and you have an update site then you can install them manually by enabling Install under the File menu. To enable install under File Install, add the entry "com.ibm.notes.branding/enable.update.ui=true " to the plugin_customization.ini file in \framework\rcp directory.
- If the plugins are missing and you have the plugins (but no updatesite.zip) then you can install them manually by copying them to the file system by doing the following
- Copy the plugins to the directory \framework\shared\eclipse\plugins
- Edit the file \framework\rcp\rcplauncher.properties and set"update.policy.managed=false"
Restart the machine.
- If the plugins are not missing then are they active? Check by doing the following:
- Type "ss" at the OSGI Console to determine the state of the plugin.
- You can use one of the following provisioning commands to install and enable the feature:
prov e - Enables a feature
prov d - Disables a feature
prov u - Uninstalls a feature
prov i - Installs a feature
prov ie [ (perfect|compatible|equivalent|greaterOrEqual)
[true | false] - Installs and enables a feature
prov m - Provisions via a manifest file
prov lu - Lists features on the uninstall list
prov ls - Lists sites
prov lc targetsite - Lists configured features
prov lf targetsite - Lists filtered features
prov lr targetsite - Lists raw features
The problem may also be with a Notes view. Check the following to help you determine if this is the problem:
- Is the database that contains the NSF component (view/form/frameset) accessible?
- Can you open the database and the NSF component stand-alone?
- Do you have access rights?
- Is com.ibm.rcp.visible set to true?
Property Broker monitor
The Property Broker monitor lets you display and view the following:
- property broker events
- active actions
- active wires
- registered properties and actions
This tool is used for a run time analysis of the property broker registry and events h appening in the broker.
More information about installing and using this tool can be found on this wiki by searching for "Property Broker Editor."
Topology peek
The "Topology peek" tool lets you view the internal topology cache for an installed composite application by displaying cached applications and component preferences.
The tool's user interface lets you view what is currently present in the cache. If information is not displayed in the Topology Peek tool then it is not in the cached presentation of the application. This can help you in determining what makes up the application on the client and what should be refreshed when CA.XML and definitions are changed on the fly.
This tool is also posted in the same file as the Property Broker Monitor at the following "Lotus Sandbox" location:
http://www-10.lotus.com/ldd/sandbox.nsf/ByDate/c264028381e066e1852572f80050dcf9?OpenDocument
To install:
- Download and extract the ZIP file from the Notes Sandbox location above.
- Copy ca_debug_tools.nsf to the your Notes data folder.
- Open this NSF in the IBM Lotus Notes 8 client.
- Follow the link to online help and then use Actions-Edit Application from the Lotus Notes 8 menu bar. You will be prompted to install the two features. Additional information and instructions are contained in ca_debug_tools.nsf.
OSGI Console
This tool is used to view trace information and to find out information about the property broker and topology handler. Use this console if you are having trouble with component loading.
To display the OSGI console when running Notes standalone add the "-console" switch to the Notes startup command.& For example:
C:\Program Files\IBM\Lotus\Notes\notes.exe -RPARAMS -console
At the OSGi prompt you can enter the "help" command to get a listing of the available arguments:
osgi> help
Here is a sampling of Eclipse Runtime and Property Broker-related arguments that are available, for example:
---Eclipse Runtime commands.---
diag - Displays unsatisfied constraints for the specified bundle(s).
active - Displays a list of all bundles currently in the ACTIVE state.
getprop { name } - Displays the system properties with the given name, or all of them.
.............................
.............................
---Property Broker Commands---
pbsh a - Show all Actions
pbsh a - Show all Actions for a specific owner
pbsh aa - Show all Active Actions
pbsh o - Show all owners
pbsh p - Show all properties by owner
pbsh p - Show all properties for this owner (string owners only)
pbsh w - Show all enabled wires
pbsh w - Show all wires for a specific owner
pbsh aw - Show all wires
pbsh ns - Show reqistered name spaces
pbt - Trace the path for the specified property
pbut - UnTrace the specified property, removes the trace
pblt - Show a list of the currently traced Properties
Best practices on how to use the OSGI console
To get the best results when running the OSGI console, do the following:
Set the command prompt box for your console to 2000 characters wide and 800 tall. The dumps are very long and wide.
Select all the information displayed and cut and paste the information into a text editor with "word wrap" disabled. You can now search the dumps for the information that you want. Wide dumps usually have less useful information to the right and with word wrap disabled you are not troubled with it.
Using logging on the Notes plugin side
You can change the logging level dynamically at the console or statically by changing the default logging level.
Changing the logging level dynamically at the console
Use the following procedure to change the logging level dynamically at the console:
- In the file \framework\rcp\rcplauncher.properties enable the console by adding the following lines:
config.notes.8=-debug
config.notes.7=-console
- Start Notes and enter the following in the console window:
setlogrlev com.ibm.workplace.notes.nrpc FINEST
setlogrlev com.ibm.workplace.noteswc.level=FINEST
setlogrlev com.ibm.rcp.portal.app.ui FINEST
setlogrlev com.ibm.rcp.provisioning.level = FINEST
setlogrlev com.ibm.rcp.portal.app.level=FINEST
Changing the logging level statically by changing the default logging level
Use the following procedure to change the logging level statically by changing the default logging level:
- In the file _\workspace\.config\rcpinstall.properties add the following lines:
com.ibm.workplace.notes.nrpc=FINEST
com.ibm.workplace.noteswc.level=FINEST
com.ibm.rcp.portal.app.ui=FINEST
com.ibm.rcp.provisioning.level=FINEST
com.ibm.rcp.portal.app.level=FINEST
- For composite applications that use PIM components you may also want to include the following line:
setlogrlev com.ibm.csi=FINEST
Tracing packages
You can also trace the following packages to assist you in troubleshooting
Notes plugin including the bridge from Expeditor Property Broker to Notes and NSF based applications:
- com.ibm.workplace.noteswc
Expeditor property broker:
- com.ibm.rcp.propertybroker
Expeditor topology handler:
- com.ibm.rcp.topologyhandler
Expeditor composite application infrastructure:
- com.ibm.portal.app
- com.ibm.portal.cai
- com.ibm.rcp.portal.app
- com.ibm.rcp.portal.app.adapter
- com.ibm.rcp.portal.app.ui
- com.ibm.rcp.portal.catalog.ui.internal
Logging on the "Notes side" for production builds
For production builds, you can also have logging turned on via the Notes.INI file by adding the following lines:
DEBUGGINGWCTENABLED=4
DEBUG_OUTFILE=c:\debug.out
This setting is useful for Notes Property Broker issues and issues with .NSF-based composite applications
Logging on the "Notes side" for non-production builds
For non-production builds, you can also have the following entries in your Notes.INI file to assist in logging:
DEBUG_APP=1
DEBUG_APP_LEVEL=4
DEBUG_OUTFILE=c:\Notes\NOTES_LOG.TXT
CLIENT_CLOCK=1
DEBUG_CONSOLE=1
DEBUG_COMPDEF=1
stx9=1
Using Composite Application Editor logging
The Composite Application Editor (CAE) currently does not use standard logging mechanism. The following presents guidelines for usi ng logging with the Composite Application Editor:
When ru nning from your IDE, add properties to your VM Arguments for your launch configuration.
When running standalone, add the following to \framework\rcp\rcplauncher.properties:
config.notes.11= Dcom.ibm.rcp.aaf.portalAdaptor.debug=true
config.notes.10=-Dcom.ibm.rcp.aaf.logginglvlÞBUG
config.notes.9=-vmargs
The following information gives more details about CAE logging properties:
- com.ibm.rcp.aaf.logginglvlÞBUG -- Turns on debug logging for the Composite Application Editor (goes to TraceLog).
- com.ibm.rcp.aaf.portalAdaptor.debug=true -- Turns on DEBUG mode for all calls to the AAFService portlet while editing WebSphere Portal based applications/templates. This results in more logging on client side for Portlet calls (TraceLog), as well as more logging on server side (systemout). It also stops temporary files on portal server from being deleted so they can be examined (for example, XMLAccess scripts, etc.)
- com.ibm.rcp.aaf.emc.SaveTopologyFile=true -- Saves a copy of the topology (CA.XML) that is being saved to \workspace\.metadata\.plugins\com.ibm.rcp.aaf
Information on On-Disk Data used in applications
The following directories contain data that is cached. When debugging, it is possible to delete all of this data. It is re-created when the applications is re-opened the next time. Deleting this data is rarely required. Here, you have to replace the placeholder with the directory location of your Notes data directory (e.g. C:\Program Files\IBM\Lotus\Notes\Data\ for default Notes installations).
- \workspace\.metadata\.plugins\com.ibm.notes.client
- \wsdls - Contains cached and merged WSDLs from NSFs plus translation files for WSDLs.
- \workspace\.metadata\.plugins\com.ibm.rcp.propertybroker - Contains map from view instances to owners.
- \workspace\.metadata\.plugins\com.ibm.rcp.topologyhandler
- \Applications - Contains the Topology XML (not the entire CA.XML) for all installed composite applications.
- \workspace\.metadata\.plugins\com.ibm.rcp.portal.app - As an example, this can contain mapping from GUIDs to URLs
- \workspace\.metadata\.plugins\com.ibm.rcp.aaf
- \palette - Contains CAE palette files. These files can be exported and imported from the user interface in the palette
- \workspace\.metadata\.plugins\com.ibm.portal.cai
Additional potential composite application issues
This section provides information on additional issues that may arise when troubleshooting and debugging composite applications.
Issues with WSDL if the Property Broker Editor is used
The following issues may occur:
- actions require creations of properties on other tabs first
- The 'Allow publishing' option is not understood
- some terminology is confusing, e.g. parameter instead of property
Issues with manually edited WSDL
This method is not supported but may be done anyway (for example, Eclipse developers who do not want to leave Eclipse IDE. The following issues may occur:
- Incorrect case may pose problems as IDs in WSDLs are case sensitive.
- WSDL files may contain redundant information and other terminology
Issues with NSF components
If your NSF components do not show properties and actions in the Composite Application Editor (CAE), go into Domino Designer to any column and check in the Infobox whether you see any properties. If th ey are not visible, there is an issue with your WSDL file.
An NSF component view might not come up when defining the Notes URL manually. To check on this issues, try copying and pasting the URL from the Infobox in your web browser and check for more error messages.
Issues with Eclipse components
If an Eclipse component does not appear in your application, check the following:
If an Eclipse component does not show properties and actions in the Composite Application Editor (CAE), check or try the following:
- Check to see if the .JAR files on your machine contain the WSDL file. If the WSDL file is not there, check your development environment. To correct this. edit the plugin.xml file and check the Build tab. You must explicitly tell the build process to package the WSDL file with the .JAR file.
- Check in plugin.xml to see if there is an extension of the com.ibm.rcp.propertybroker.PropertyBrokerDefinitions point with a tag and "file=" attribute pointing at the file.
- Define the link to the WSDL file so it is associated with the view. Make a copy of your WSDL file somewhere and recreate just one property/action from it using the Property Broker Editor. Do not import from the old WSDL file.
- Try copying a WSDL file from a working component to your new component. If the new file works, then there is an unknown error in the Property Broker Editor/WSDL processing. Try to capture and report the error(s).