Troubleshooting common issues in out of the box IBM BPM Portal (8.x)


There are quite a few IBM Products that use Business Space as a browser-based graphical user interface to view and interact with content from various products in the business process management portfolio.

In IBM BPM 800 Business Space was fully built into IBM BPM Process Portal, meaning that it was a full business space serving pages from host:port/mum/enabler

Starting IBM BPM 801 Process Portal was disconnected from Business space but it still used a number of Business Space components like WebDav themes, dojo Business Space widgets, etc.

In this particular article I would like to focus on troubleshooting issues related to components of Business Space, Business Space itself and its usage in IBM BPM Product as well as standard troubleshooting techniques for IBM BPM Process Portal.

Business Space related folders in IBM BPM installation:

Binary Location / Install Location:
<WAS Home>/BusinessSpace

Profile Location
<BPM_Profile>/BusinessSpace (this folder will only appear after the start of the server, only next folder will be there after initial installation/migration)

Verify database name where Business Space related tables located:

Location of Business Space tables would vary based on the type of BPM installation. So, it would be best to check WAS admin console datasources.

Login to WAS admin console -> Resources -> JDBC -> Datasources -> Find "BPM Business Space data source" in the list and click it -> at the bottom of the screen you will see a table where one of the fields would be "Database name" (note: in this article we'll assume you have used default CMNDB for Business Space tables).

There are two important tables related to Business Space: FILESTORE_PATH and FILESTORE_FILE (the first one contains all file paths to the BS templates/themes/etc, second one contains files themselves in a BLOB column).

Missing Mashup Tables (FILESTORE_PATH, FILESTORE_FILE, etc) may cause BPM Portal not to render properly, you will likely see SQL errors in the logs (DB2 error example: Error code: 942, SQL State: 42000) suggesting missing tables. Check dbscripts as shown below and see what tables are missing and run the appropriate script to create them.

Business Space database scripts:


(createDatabase.sql, dropDatabase.sql, createAdvancedSchema.sql, -- script names would depend on BPM version and type of installation, you may search for FILESTORE_PATH to understand which script you want to review/re-run)

Issues related to Business Space templates/themes/widgets:

If you have migrated from an earlier version of IBM BPM or made a "reload" of your BPM database then your custom themes might have been lost along the way.

You may try to reload them using the following steps:

  • Find file under:


  • Update the following properties and set them all to true as shown below (please note - if you check this file before the first start of the server these properties will be set to true, they are reverted back to false after the start of the server):




  • In a clustered environment perform a full synchronize after this and then perform a full restart of a cluster.

WebDav - applying custom themes:

There is a number of WebDav clients available. I have personally used CyberDuck as per instructions in this community wiki article:

The only thing to note is - when you try to connect to your BPM server through WebDav client you might need to perform some additional steps:

  • Log in to the WAS admin console.
  • Click Applications > Application Types > WebSphere enterprise applications and select application that starts with:

mm.was_node_server (for a stand-alone server environment)

mm.was_cluster (for a network deployment environment)

  • Click Security role to user/group mappings.
  • Select the row for the Admin role, and click the Map Users button or the Map Groups button
  • Map either the user you're trying to connect or the group your user is a part of to the Admin role.
  • Click Save.
  • Restart the environment.

Troubleshooting Portal issues using browser built-in tools:

Google Chrome - Developer tools (Ctrl+Shift+I)

Firefox - developer tools (Ctrl+Shift+I)

IE - Debugger (F12)


Standard tabs in stock BPM Portal - WORK, TEAM PERFORMANCE, PROCESS PERFORMANCE. Starting BPM 8.5 all of these tabs are exposed BPM items. BPM Portal makes REST API calls to get exposed items, to retrieve user's tasks based on criteria, to see what actions can user perform on specific instance(s). All of these are REST API calls and it's often useful to capture them if something is not working a expected. You can use a Network tab in Developer tools to get this data, you can even edit it in Runtime using the developer tools and re-run as you can see in below screen-shot:

On the left-hand side we can see captured REST API calls to get exposed items (WORK, TEAM PERFORMANCE, PROCESS PERFORMANCE) and on the right hand side we can edit specific REST API call and re-run it for troubleshooting purposes.

IBM BPM 800 and 801 routing server for IBM Business Process Manager (BPM) Process Portal in a three- or four-cluster topology:

In a three- or four-cluster topology, Process Portal requires a routing server.

Routing server can be anything in this case - it can be existing proxy server, any other web server, reverse proxy server, HTTP server, load balancer, etc.

The following IBM technote contains instructions on how you can set up proxy server to use with IBM BPM and it has links to infocenter if you want to configure other types of routing servers:


There is a directory called UIStaticContent located under WAS_HOME (Example: /opt/ibm/Websphere/AppServer/UIStaticContent).

In turn this directory contains a number of directories like: ProcessAdmin, ProcessCenter, process-server that have teamworks.war, portal.ear/portal.war directories and each of those contain following zip files: and 

These are the images, jsp's, etc that are used in BPM web applications including Portal. 

For instance there is a login-logo.png image that contains one of the logo's in the Portal. It's referenced in logo.jsp file in here:


Most of these files can be modified using the WebDav client and that is a supported way of doing it but unfortunately not all of the files you will find inside these zip files are exposed via WebDav. You get the idea.

WARNING: modifying these static or dynamic files/jsp's is not supported by IBM support, so, use it with caution.

Useful traces to troubleshoot issues related to Portal / Business Space /security (server side):

  • General one:

     *=info: WLE.*=all:*=all

  • Include backend SQL calls (no SQL parameters):

     *=info: WLE.*=all:*=all: WAS.clientinfopluslogging=all

  • Security (this one can be pretty verbose, so, don't use in Production unless really required and then use it for a short period of time using the Runtime tab in WAS admin console):

     *=info: WLE.*=all:*=all:*=all

Have more questions? Submit a request


Powered by Zendesk