Customize the style of IBM BPM coaches
A pattern and a hierarchical approach
Today's IT projects demand rich, attractive, and efficient user interfaces more than ever before. A set of requirements that was once reserved for customer-facing systems is increasingly also being applied to internal systems. Businesses now want a consistent visual style in the user interfaces across all of the applications in their organization – reducing the need to train users of new systems, maximizing brand awareness, and increasing employee satisfaction.
Therefore, an increasingly common requirement for IBM® Business Process Manager (BPM) projects is to fully consider the style of coaches and how users interact with them. In addition, the coach designer in IBM BPM was designed with development speed as the priority rather than the ability to fine-tune the style of user interface pages. Both of these facts have led organizations to face some difficult choices when deciding how to proceed with IBM BPM coaches.
This article describes a pattern for building IBM BPM coaches, along with a hierarchical method for changing their style. The pattern allows customizations, which you implement by using the hierarchical method, rolled out across multiple IBM BPM applications from a central toolkit so minimal (if any) changes are needed at the application level. The pattern and the hierarchical method work with any version of IBM BPM starting with IBM BPM V8.0.1.
This article demonstrates an end-to-end journey of implementing
customizations and creating a responsive user interface that is displayed
correctly on all devices. This approach has been successfully implemented
with several organizations. The pattern recognizes the maintenance
challenges that arise when modifying the default coach views or when
creating brand new coach views from scratch. Both actions increase the
maintenance overhead for applications or can cause compatibility issues
when updating IBM BPM. To address these potential issues, the pattern only
uses default controls, does not require complex proprietary toolkits, and
uses new coach views are only when absolutely necessary. You can read this
article and implement the pattern without ever needing to look at the
sample code. However, a sample
.twx file is available on
GitHub for reference.
This article focuses on how to customize responsive coaches and gives you a pattern for maintaining the customizations across an entire enterprise. If you don't want to make major customizations to the style of your coaches, but you still want responsive user interfaces that work well on all devices, see the Access IBM BPM from anywhere series.
In IBM BPM V8.5.7, new capabilities include responsive controls, grid layouts, and a theme customizer in Process Designer. The Deliver Modern UI for IBM BPM with the Coach Framework and Other Approaches IBM Redbooks publication and the IBM BPM product documentation describe these capabilities in detail. If you are using IBM BPM V8.5.7 and don't have a need for compatibility with earlier versions, you aren't using Bootstrap, and you don’t need the granularity of the coach view customizations, use the capabilities described in the IBM BPM V8.5.7 documentation and IBM Redbooks publication. IBM has been collaborating with Salient Process, releasing incremental updates to the SPARK UI toolkit and IBM BPM in preparation to fully embed it in a future release of IBM BPM. Make sure to get the latest cumulative fixes for IBM BPM V8.5.7.
What you need to use this pattern
This article assumes a good understanding of IBM BPM development, CSS, HTML, and general web development. Knowledge of how the Bootstrap CSS framework functions is helpful but not necessary, because links to easy-to-follow tutorials are included.
This pattern can be used with any version of IBM BPM V8.0.1 through IBM V8.5.7, and in future versions, assuming there are no major changes to the coach framework. There might be small changes to the IBM BPM default CSS file between versions. If you upgrade to a new version of IBM BPM, run regression tests on your applications.
Throughout this article, screen captures and other examples use an example toolkit. You can download this sample application from GitHub at DeanCleaverIBM/CustomisingIBMBPMStylePatternAndMethods and experiment with it.
.twx file was developed in IBM BPM V8.5.6 and can
only be imported into IBM BPM V8.5.6 or later. Even if you are using an
earlier version of IBM BPM and cannot use the sample
file, you can still follow the pattern by reading this article.
The pattern for building coaches
The pattern for building coaches in IBM BPM is composed of two parts. The first part is a reusable template, which you should use on every coach throughout an application. The template contains the required library files, fonts, and CSS file. The second part of the pattern is Bootstrap and the coach views that you need to implement Bootstrap.
Coach Template component is the core of the pattern. It
contains the library files, the CSS file, and the basic branding elements.
The template implements the customization method that is discussed in
later sections. Therefore, every application that implements the
customization method must use this template as a base for all coaches.
The following screen capture shows the Layout tab for the
Coach Template component from the sample
file that is available on GitHub.
As you can see at the top of the previous screen capture, the Coach Template in the example has an IBM logo that is configured to be displayed in the top right of the screen. The next items in the template are a set of three custom HTML blocks that contain HTML formatting and a title block, which is set by a variable bound to a configuration option of the coach view. The content box is the next item in the template. Finally, there are four coach views, each containing a set of included files and scripts.
Instead of being included in the
Coach Template behavior tab,
the coach views that contain the files and scripts, are wrappers for their
contents. With this approach, the contents are easier to update, move, and
modify individually. You don't need to update the template. All developers
who use the toolkit have the flexibility to use the coach views
independently, if needed for a future requirement. These coach views serve
no purpose other than containing the files and scripts. Details are
explained in future sections of this article.
Font_Awesome coach view includes all of the files you need
for using Font-Awesome on coaches that use the
Coach Template. Font-Awesome is an icon font pack that you
can use for inserting lightweight, customizable, scalable, vector-based
images into your web pages. While it is not a focus of this article,
Font-Awesome is used by some of the coaches in the included example
toolkit. You don't need further knowledge about Font-Awesome for this
article, but you can learn more at http://fontawesome.io.
Bootstrap_Files coach view contains all of the files
needed for implementing Bootstrap on a web page (or in this case, a
coach). You learn more about Bootstrap and how to use it in the next
CSS_Overrides coach view contains the CSS overrides to the
base styles of IBM BPM, giving a unique appearance to the coaches in the
example toolkit. Learn more in the sections that follow.
IBM_CSS_Classes coach view contains all of the custom CSS
classes in the example toolkit that you uses to set the style of specific
elements. Learn more in the sections that follow.
There are many examples of Bootstrap implemented with IBM BPM, but often
they are tied to proprietary implementations, or they are in specific
visual styles that are difficult to customize. The approach in this
article shows how to implement the responsive capabilities of Bootstrap
with two simple coach views that implement the CSS framework. The coach
Bootstrap Row and
Bootstrap Column, are described in detail in the following
The Bootstrap Row coach view
Bootstrap Row coach view consists of two HTML blocks with
a content box in between. The first HTML block opens a
<div> tag and applies the
class, and the second HTML block closes the
as shown in the following screen capture.
The result is a coach view that can be dragged and dropped into the coach
designer. Everything that is placed in that coach view is then effected by
row class, which is needed by Bootstrap columns.
The Bootstrap Column coach view
Bootstrap Column coach view is built in a very similar way
Bootstrap Row coach view. The end result is a
<div> tag with a CSS class attached to the
<div> tag and a content box placed within the
<div> tag. In this case, however, the CSS class is one
of several classes available for this coach view, if you use the
columnWidth configuration option.
The custom HTML block that contains the opening
tag is not the simple
<div> tag with a CSS class like
Bootstrap Row coach view. Instead, the contents are
bound to the value of the
columnWidth variable, as shown in
the following screen capture:
As you can see, the
columnWidth variable has a variable type
BootstrapColumnSelectionType. The following screen capture
shows how the
columnWidth variable is set up on the Variables
tab for the
Bootstrap Column coach view.
BootstrapColumnSelectionType is a business object of the list
data type, which is basically a string. It can be set only to the value of
one of the list entries, which are set in the business object
configuration page, as shown in the following screen capture:
When you add a list data type to a coach view, as the example with the
Bootstrap Column coach view, it is displayed as a drop-down
list in the coach designer, as shown in the following screen capture:
Each of the options available from
BootstrapColumnSelectionType are Bootstrap CSS classes that
effect the behavior that the Bootstrap framework follows, based on the
size of the device screens for end users. Many more possibilities are
available in Bootstrap, but to keep the example toolkit simple only a few
commonly used ones are included. You can learn more with the Bootstrap 3 Tutorial on
the W3Schools website.
Use Bootstrap framework responsive features with the coach views
This section uses the example application and toolkit to demonstrate how to
Bootstrap Row and
coach views to create a responsive user interface.
The following steps show how to assemble a coach that mirrors the Unit Test example in the sample application and toolkit that you can download from GitHub. The examples in this article use heritage human services, so you can use them with versions of IBM BPM starting with IBM BPM V8.0.1. For more information, see the Difference between heritage human services and client-side human services topic in the IBM BPM documentation.
- Create a heritage human service, add a coach to it, and link it to the start and end events.
- Open the coach designer.
- Add the
- Click the template, and switch to the configuration tab.
- Add a title in the template configuration tab, as shown in the following screen capture:
- Add a
Bootstrap Rowcoach view, and you should see a Coaches tab that looks like the following screen capture:
- Add some
Bootstrap Columncoach views, and set their width to 12/4 in the configuration tab for each coach view. The following screen capture shows the Coaches tab with those coach views added:
- Add content to each of the columns, as shown in the following screen capture:
- Then run the Unit Test coach to test it.
The following screen capture shows the Unit Test coach displayed on a large screen, similar to how an end user of the process application sees it:
The following screen capture shows the Unit Test coach displayed on a small screen, similar to how an end user of the process application sees it:
The hierarchical method for coach styles
When you create a rich user interface in a web application, you can use several different approaches to creating the look you want. IBM BPM is no different. However, each approach comes with its own pros and cons, and each approach is suitable in different scenarios.
The following sections describe and prioritize each of the methods for setting user interface styles for your IBM BPM process participants. The first section covers the general style of the page, and the second section covers the style of the specific coach views.
This hierarchy of approaches is designed so that the methods at the top of the list are simplest, the most reusable, and most maintainable.
General style of the page
The following style techniques for the general style of the page are listed in order of priority: implement the first method, but if it is not possible, move to the next method in the list. The following sections discuss each approach in detail.
- A centralized CSS override file to override the standard IBM BPM CSS file
- A centralized CSS file with additional classes
- HTML attributes (inline style)
- Custom HTML blocks
Method 1: A centralized CSS override file to override the standard IBM BPM CSS file
The first place to modify the appearance of your user interfaces in IBM BPM is a centralized CSS file that overrides the standard IBM BPM Claro Theme CSS files. Every element that can be dragged onto a coach in IBM BPM has associated classes. This means that you can reference these classes to override the base style sheet and apply different style
You can create your coach as you usually would in IBM BPM, and run the service. Then, use browser development tools to look through the various page elements to discover what classes are referenced. You can place the classes in a centralized file, with the new style applied, and then attach the file to a template that is used as the basis for every coach.
In the example available on GitHub, see the CSS file
bpm&bootstrap-css-overrides.css) that is attached
attached to the
CSS Overrides coach view on the
Coach Template. The following screen capture shows the style
of a coach built with the example toolkit.
The example application and toolkit provide good examples of the scale of changes that you can accomplish with this method. The resulting style is substantially different than the default style from IBM BPM.
The reason this approach is first in the hierarchy is because it is quick and relatively simple to rapidly modify the appearance of all the user interfaces across an entire application (or even multiple applications, if implemented correctly).
The CSS file is stored centrally in the template, and changes are replicated everywhere it is used. If the file and template are stored in a toolkit, then all IBM BPM applications that reference it (and maintain their dependencies) keep up-to-date with style changes. It is even possible to store the CSS file on an HTTP server and reference it in the template, which means that you can update the user interface even after all IBM BPM applications are deployed.
The method for deciding which CSS classes to override is straightforward. Open an IBM BPM coach in any common browser, and use the element inspector to click each element and check what CSS classes are used for those elements. Then override those classes in your centrally managed CSS file.
In the following screen capture, the
headerContentNode div is
selected in the Chrome element inspector.
You can see to the right that the
dojoxGridHeader CSS style is
applied to this element. Any overrides applied to this class can be added
to a centrally managed CSS file that affects the style of the element on
This pattern and the associated example toolkit use a centralized CSS file that is bundled with the toolkit. This design means that each application has the CSS file inside, and each application can be updated independently if needed. However, with this approach, you need to redeploy each application to update the interface across all applications.
If your team doesn't want to deal with that requirement, an alternative approach is to place this centralized CSS file on an HTTP server and reference it inside the template. This approach gives less control over how each application is upgraded, but updating one file replicates changes across all IBM BPM applications. The CSS file also can be reused across non-IBM BPM interfaces.
Method 2: A centralized CSS file and additional classes
The next method in the hierarchy is another centralized CSS file attached to your template, but this time with additional classes. If you need to set style for a collection of elements that are unrelated to any current class, or if the current class is too broad, consider using this approach.
You have a centralized CSS file as in the previous approach, but the classes are unique to the particular organization or even the application. This file can be one you already use across the organization or, it can be entirely new. You can combine this CSS file with file described in the first method, or keep the files separate. Either way, remember that the classes must be added to each element that you want to have the new style.
To apply to a coach view, complete the following steps:
- Prepare the CSS class.
- Go to the HTML Attributes section of a coach and click Add a class.
- Type in the name that matches the additional class that you have defined in the style sheet on the template. The style is then applied to that element alone.
- Due to the structure of IBM BPM, some elements do not take on the style from applying the class. If you do not see the changes you expect, look at the element structure in your browser developer tools again. If needed modify your CSS to reference the style on any sub-elements.
If you are applying a CSS class to a piece of custom HTML, follow the same procedure as applying the class to any other type of web page.
The following three screen captures show an example of a custom CSS class from a centrally managed file used on the template to set the style of the title of the page.
The following screen capture shows the
The following screen capture shows shows the
applied to the title
<div> of the
Coach Template in the example toolkit:
The following screen capture shows how the user interface for the coach template looks at run time, with content and with the page title configuration option set to Unit Test.
Method 3: HTML attributes (inline styles)
The first two methods previously described don't work if you are making a very specific modification or you don't want the look of the element to change if global styles are updated. The next approach is to apply directly to an element by using inline style in the HTML attributes tab.
For example, this method is good for adding a left margin of a few pixels to an element. This approach should be used sparingly, because the application is very specific. From Process Designer, it is difficult to see if this method is used, and therefore it is more difficult to maintain. The following screen capture shows an example of using the HTML attributes method to change the text color of a text field:
The following screen capture shows the results of applying the inline style, like what the users of the coach see:
Method 4: Custom HTML blocks
If all the previous methods don't meet your requirements, or if you need to
make a very specific "one-off" change to a page (such as adding a
<div> tag or inserting white space in a specific
location), then you can place custom HTML blocks directly on the
The following three screen captures show examples of how to use custom HTML
blocks on the
Coach Template to add a custom title to the
The following screen capture shows the first example custom HTML block
selected, with a
<div> opening with the
pageTitle CSS class assigned to it:
The following screen capture shows the second example custom HTML block
bound to the contents of the
The following screen capture shows the
<div> opened in
previous section now closed, in the third example custom HTML block.
Style of specific components
Sometimes to get a specific style for a particular component, changes to the actual coach views are needed. If you want a particular component to have a different style than other components, simply changing the CSS file might not give the results you are looking for.
The following style techniques for the component-specific style are listed in the order to be implemented. The following hierarchy is listed in order of priority for methods to set the style for specific coach view components. The following sections discuss each approach in detail.
- Default coach view components wrapped in a reusable custom coach view
- A reusable custom coach view that uses default IBM BPM components as a base template
- A reusable coach view built from scratch
- A single-use coach view
Method 1: Default coach view components wrapped in a reusable custom coach view
The first method to try is to keep the default coach views as-is, but embed them in another coach view that implements the required style changes. For example, this is appropriate for a custom text field that requires specific styles placed around it.
Because this approach does not modify the underlying default coach view (or views, if multiple are used), all functionality of the base coach view is retained. Also, the actual default component is still supported by IBM BPM updates. Minimal or no changes to the custom coach view are required after an IBM BPM update.
The following three screen captures show a text field with a piece of HTML code placed after it. The HTML code adds cm (which represents centimeters) as text that appears after the text field. The idea behind this example custom coach view is to display measurements in centimeters.
The following screen capture shows the coach view in the coach designer.
The label field is bound to a configuration option named
label. Then, the label can be set by the top-level coach
The following screen capture shows the same coach view again, but with the focus on the custom HTML block that shows a page break (added to ensure that the text appears in the right location), followed by cm.
The following screen capture shows how the custom coach user interface looks at run time to the users of the process application:
Method 2: A reusable custom coach view that uses default IBM BPM components as a base template
When wrapping a default component is insufficient to get the style and functionality that you want for the user interface, use the second method in the hierarchy. For this method, you use a default component as a starting point when developing a new component. Duplicate the original method, move it to the relevant toolkit, and then make the necessary changes.
The advantage of this approach is that it retains the default IBM BPM capabilities that you are familiar with. However you lose IBM BPM support for the component if you take this route. If an update to IBM BPM is applied, any updates to the default component need to be applied to the custom component manually.
See the example toolkit for an example of this method. A custom button
example extends the default button to include an icon from the
Font-Awesome icon font pack in the text string that is displayed on the
button. The following example uses the
fa-check icon. The
following screen capture shows the
view from the example toolkit, as users view it from a browser:
Method 3: A reusable coach view built from scratch
Consider a third method in the hierarchy when you cannot make use of any of the default coach view components in IBM BPM. This approach builds a new coach view from scratch, but builds it in a way that is easy to reuse.
The example toolkit contains several examples of these types of coach
views, used to implement the previous method for using Bootstrap. The
Bootstrap Row and
Bootstrap Column coach views
are both completely custom views that are reusable. Another example is the
Notification Container coach view, as shown in the following
Method 4: A single-use coach view
In isolated cases, you might have a requirement for a "single-use" coach view in your project. The requirements that lead to these types of coach views are rarely motivated by style, but this situation warrants a mention.
The usual motivations for creating a single-use coach view are requirements like complex client-side logic implemented on a page. These requirements might be possible to implement only when using the coach view framework instead of the coach designer.
This method is OK to use if the coach view you create is well documented and built to be as easy to maintain as possible.
In our experience working with organizations that use IBM BPM, we have seen many examples of projects that faced issues because of too many single-use coach views. Code can become very difficult to follow if there are numerous single-use views are used in a project. Without documentation, maintenance tasks can become very difficult.
This article described methods for customizing the style of coaches in IBM BPM V8 and later using the Bootstrap CSS framework and multiple overrides of the default CSS file. Now you can apply these approaches in your own environment, to meet your organization's specific needs.
The hierarchical method of setting styles was successfully implemented with several organizations that use IBM BPM. The key to this success is adopting the approach outlined in this article from the outset, and building well-structured and maintainable UI toolkits. Throughout the projects, developers followed the method as closely as possible and put special efforts in place to ensure that no project-specific content was included in toolkits. The customers subsequently replicated this approach across the enterprise, providing a consistent style across multiple IBM BPM projects.
For example, one organization is now using this method for more than six projects. Because the UI toolkit contains only what is needed to implement the method, any changes to the toolkit don't greatly affect the projects that consume it. The style across the entire IBM BPM environment is maintained from one central point. Now, when the developers want to make changes to the style of the user interface, they simply make changes in the toolkit and take a snapshot. Then, when other projects are ready to upgrade, they adopt the latest toolkit snapshot. If the hierarchical method is followed, no additional work is required.
The authors would like to thank Gerry McLaughlin, Scott Glenn, and Dennis Parrott for reviewing this article.
- Access IBM BPM from anywhere: phone, tablet or desktop, Part 1: Explore the mobile Process Portal for process participants
- Access IBM BPM from anywhere: phone, tablet or desktop, Part 2: Update styles and themes for mobile user interfaces
- Branding and customizing the coach controls in IBM Business Process Manager
- Branding and customizing coach themes in IBM Business Process Manager
- Deliver Modern UI for IBM BPM with the Coach Framework and Other Approaches
- IBM Business Process Manager product documentation