User Interfaces and User Interaction

It is common to want to present information to users and have those users return responses. Such human interactions were called Human Tasks in the old WPS product. In IBPM, they are called Human Services. Within a BPD we can define a User Activity and define a Human Service as the implementation of that User Activity. Contained withing a Human Service are one or more "Coach" units. Each Coach corresponds to a single screen as seen by the end users.

A Coach describes the visual nature of what a users sees and associates that with data contained within the process. The Coach is created in the Process Designer tool within the Human Services editor. Coaches may only be included in Human Service definitions. They may not be defined in other service types.

With the arrival of the IBM BPM v8.0 release, the implementation and design of Coach technology radically changed. To provide upgrade protection for users who had been using releases prior to v8, the old Coach technology remains in the product. This older implementation is termed "Heritage Coaches". For new users, the Coaches that should be used are the current "default" Coaches which are sometimes referred to as "Next Generation Coaches". All references to Coaches in this document will refer to the default Coaches found in v8 and beyond unless explicitly stated to be otherwise.

In the service diagram editor, a coach is represented by the following building block.

This can be created from the palette by dragging and dropping the following icon:

The Human Service editor has a tab that lists all the Coaches in that human service definition.

When a coach component is opened, a canvas area into which the visual aspects of the screen can be drawn. This editor is called the Coach Designer.

To the right of the canvas is a palette of selectable building blocks from which a page can be created.

To the left of the canvas area is the list of all coaches in this particular Human Service definition. The coach which is to be edited can be selected and the canvas editor changes its focus to that coach instance.

Inline User Tasks

With the arrival of BPM 8.6.0 and the latest fixes, Inline User tasks were added. The notion here is that when we create a process model, as long as we supply the types of user input and output, a Coach can be dynamically generated for us which will allow the process to be executed to present task information and allow user input without having to spend any time working on Coach screen creation. This allows the process to be unit tested as quickly as possible.

2017-12-20_15-52-16.png

Note the icon that represents this item as an in-line user task.

The settings are for this type of activity looks as follows:

2017-12-20_15-56-18.png

When we look at the data mapping section, we can define input and output variables.

2017-12-20_15-58-58.png

It is these variables that become the visualizations on the generated coach.

An example of the output might be:

2017-12-20_16-02-01.png

Variables mapped as input will be placed in an inputs section and flagged/tagged as read-only. Variables marked as output will be placed in an outputs section. A variable that occurs in both the inputs and outputs will be placed in the outputs section.

We can create a custom template for our in-line user tasks. They can look and feel as you desire. The BPM product expects to find two content box Coach View containers within the template. One shoule be given the Control ID of TaskInput and the other TaskOutput. It is within these that the BPM generated controls corresponding to input and output fields will be placed.

Coach Views

Contained within a page are visual building blocks that, when aggregated together, form the content of the page. IBM BPM calls each of these building blocks a "Coach View". Other UI technology products (such as Dojo) would consider these to be called "widgets" or "components" so if you are more familiar with those names, feel free to think of a Coach View as being a Widget or Component.

General Coach View settings

When a Coach View is dropped onto the Canvas, the properties area contains a variety of settings:

In the General area we have quite a few items of interest to us. First there is the Label. This is a string value that can be used as a label on many of the Coach Views.

The Binding property allows us to select a variable instance who's content will be used to populate the Coach View and/or will be populated by the Coach View.

Next the View entry names the type of Coach View that will be displayed on the Coach.

The Control Id names the unique identity of the Coach View within the Coach. Quite why we didn't call it the "Coach View Id" is unclear and feels like a hangover from the previous release.

The Label Visibility entry determines if the label associated with the Coach View will be shown when rendered. For some Coach Views such as the section views, we simply want them to be containers with no headings associated with them.

Positioning Coach View Settings

The Positioning Coach View settings allows us to set the browser "box model" widths, heights, margins and paddings for the control.

When entering values for these, one should also specify the CSS units specifiers such as "px" for pixel or "in" for inch.

The margin and padding attributes can have simple values in which case the spacing will be equal in all directions. However, by clicking on the squares to the right of the entry fields, we can provide distinct values for the different sides:

Should the content contained within the Coach View attempt to use more space than is defined for its size, the "Overflow Content" option provides instruction on what should happen. The choices are:

  • Show all content (visible)
  • Hide overflow content (hidden)
  • Permanent scroll bars (scroll)
  • Optional scroll bars (auto)

The values in parenthesis to the right of the text are the corresponding CSS Overflow property values.

Visibility Coach View Settings

The Visibility settings controls some additional aspects of the Coach View. The phrase “Visibility” is an odd one as to my mind it should control whether the Coach View can be seen by the user (visible) or not shown on the Coach (hidden). However, the values of this property allow for much more. The property value can take one of a defined set of possibilities. These are:

Value Meaning
Default (Same as parent) Take the value from the parent Coach View
Required The Coach View is visible, editable and must have a value supplied for it.
Editable The Coach View is visible and editable
Read Only The Coach View is visible but not editable
None The Coach View is not visible and does not reserve any space for it
Hidden The Coach View is not visible but does reserve space for it

The value for the property can be supplied in a number of different ways. The first is by direct selection:

The pull-down options are:

  • Same as parent
  • Required
  • Editable
  • Read-only
  • None
  • Hidden

In addition, the property value can be supplied by a named variable. The value contained within the variable will then be used to control visibility.

The second style for setting the property is Rule. In this mode we can define a set of expressions that are evaluated. The first expression that evaluates to true is the one that sets the visibility property value. The rules can use the values of variables or team membership (or lack of membership) to determine the values.

The final style is called Script.

Be especially cautious when thinking about visibility in terms of list based variables. Attempting to use "currentItem" within rules appears tempting but appears simply not to work.

IBM supplied stock Coach Views Controls

When IBM BPM is installed, IBM supplies a starter set of Coach Views that are basic controls and are available out of the box to be used within Coaches. These stock controls are:

Button

This control shows a button on the Coach web page. When clicked, it can broadcast a boundary event that will inform the Human Service that the coach has completed.

From the palette it looks as follows.

When dropped on the canvas it looks like:

Example visuals on a web page:

The binding for this control is to a Boolean valued variable which records whether or not the button was clicked.

Configuration:

Name Default
Allow multiple clicks FALSE

If the button's visibility is set to READONLY then it is disabled and will not respond to button presses but still be visible in a disabled state.

Checkbox

This control shows a check-box on the Coach web page. When clicked, it will toggle its value from true to false or false to true.

Example visuals on a web page:

The binding for this control is to a Boolean value variable which records whether or not the checkbox was checked.

Configuration:

Name Default
Show As Checkbox
True Label Yes
False Label No

To set the size of the Text control, the following CSS can be used:

div[data-viewid="*viewId*"] {
 width: 20em;
 }

This CSS can be included in an HTML widget … eg:

<style type="text/css">
 div[data-viewid="myTextId"] {
 width: 20em;
 }
 </style>

Date Time Picker

The Date Time Picker provides a mechanism to show a date (and optional time) to the user and, if desired, allow them to pick a new value. From the palette, this control looks as follows:

When added to the Coach, it looks like:

This control allows the user to select a date and time.

Example visuals on a web page:

The binding for this control is a variable of type Date. This will hold the date value selected.

The configuration options for this view are:

Name Default
Show Calendar On Click
Calendar type Gregorian
Include Time Picker FALSE
Date Format "MM/dd/yyyy"
Blackout Dates None

The width of the Date Time Picker can be changed using CSS, for example:

.Date_Time_Picker .dijitDateTextBox {
 width: 50px;
 }

Decimal

The Decimal Coach View is used to show and enter decimal numbers.


Horizontal Section

This control is a layout control/section. It allows other controls/sections to be added as children to it. Each child will be laid out to the right of the previous child forming a horizontal row of controls.

Example visuals on a web page:

Default

Round corners

Square corners

Right aligned

The Horizontal section can be bound to a list and the content of the section will repeat for each entry in the list.

Configuration:

|| |Name|Default|Description| |Show Border|FALSE|If the value is true then a border will be shown around the horizontal section| |Square Border Corners|FALSE|If set to true and he borders are shown, then the corners of the border will be square instead of round.| |Align Right|FALSE|If set to true then the content of the section will be aligned to the right.|

The width of a section can be controlled by setting the control's CSS "width" style to a value. The default appears to be "100%". This can be set in the HTML Attributes section of the control using the style attribute with an explicit width value.

Children in the Horizontal Section appear to be "top" aligned. This can sometimes cause layout problems where items appear too high. A solution to this is to over-ride the following CSS Style:

.Horizontal_Section > div > div > * { vertical-align: middle; }

Here is an example of two <div> elements within a Horizontal Section:

Notice the padding around them. What is we wanted to remove that? Creating a class called noSpaceHS defined as:

.noSpaceHS > div > .BPMSectionBody.LastContentBox, .noSpaceHS > div > div { margin: 0px; border-spacing: 0px; }

and assigning noSpaceHS as a class to the section will result in:

Image

The Image control is used to add an image onto the page. When seen from the palette, it looks as follows:

When added to the page, it looks like:

The binding property of the Image control is a String which we treat as a URL. The image located at the end of that URL is what will be shown in the Coach. Commonly, we may wish to package the image with the Process Application as a managed file. We can select the managed file from the Select button and the Web Files section:

The selected image is shown within the Process Designer canvas.

This control has the following configuration properties:

|| |Alternate Text|| |Height|| |Width|| |Caption|| |Caption Vertical Position|Above or Below| |Caption Horizontal Position|Left, Right or Center|

Integer

This Coach View allows us to enter an Integer value. From the palette, it looks as follows:

and when added to the Coach, it appears as:

The configuration of this view provides the following properties:

If a validation error is encountered, the Coach View shows the following indication:

To set the size of the Integer control, the following CSS can be used:

.em20Integer .dijitNumberTextBox { width: 20em; }

This CSS can be included in an HTML widget … eg:

<style type="text/css"> .em20Integer .dijitNumberTextBox { width: 20em; } </style>

When added to a table, the CSS appears to be:

.em20Integer .dijitTextBox { width: 20em; }

To set the background color of this widget we need:

.xxx .dijitInputInner: { background-color: red !important; background-image: none }

Output Text

This control displays output text directly in the Coach web page.

Example visuals on a web page:

The binding for this control can be a String variable. The content of the variable will be used as the content in the Coach. If no variable is bound then the label text can be used for the text shown.

To set the size of the Output Text control, the following CSS can be used:

div[data-viewid="viewId"] label { display: inline-block; width: 20em; }

This CSS can be included in an HTML widget … eg:

<style type="text/css"> div[data-viewid="myTextId"] label { display: inline-block; width: 20em; } </style>

Radio Buttons

Radio buttons present a series of click-able items that are grouped together. Only one of the items may be selected. Clicking a different item will result in the previously selected item being unselected and the new item being selected. For those who do not know why this user interface style is called "radio buttons", I'd suggest you dial a a colleague on the telephone and ask them.

From the palette, the radio buttons control looks as follows:

When added to the page, it looks like

The properties of the Radio Buttons control are:

|| |Property|Description| |Selection Service|| |Selection List|A list of Strings or objects. Each entry in the list will contribute a new radio button entry.| |Selection Service Input Text|| |Display Name Property|| |Disable Sorting|| |Layout|Vertical or Horizontal|

The result of showing a radio button Coach View can look as follows:

The width of a radio button area (an individual button) can be set to a constant using the following CSS recipe:

.radioWidth80 .dojoxMultiSelectItem { width: 80px; }

If a validation error is thrown, it will be shown to the user:

Select

The Select Coach View provides a drop-down widget. This is also known as a Select or Combo Box in HTML/Web programming.

In the palette, the "Select" Coach View looks as follows:

When added to the canvas, the following is shown:

This control allows the user to select a value from a set of possible values.

Example visuals on a web page:

The binding for this control should be a List variable. The content of the list will be used for the content within the combo box. The entries in the list can be simple Strings. Each string will then be a single entry in the combo box. Alternatively, the entries in the list can be business objects. If business objects are used, we need to tell the Coach View which field in the list should be used for display. This can be set with the "Display Name Property". What ever items in the list are selected will also be initially selected in the visuals.

Configuration options:

|| |Name|Default|Description| |List Type|Single Selection|- - | |Selected Item||If the list type is Single Selection, then this entry defines which entry was selected.| |Selected Items||If the list type is Multiple Selection, then this entry defines which entries are selected.| |Selection Service||A service which, when called, will return a list of possible values to be shown as selectable. The signature for this service should be an input of "text" of type String with an output of "results" which should be a List of ANY.| |Selection Service Input Text||Input data to be sent to the selection service. This appears as the input parameter called "text". If this property is bound to a variable then when the variable changes its value, the Selection Service is called to generate a new list of values to show.| |Display Name Property|Name|The name of a property in the list of Business Objects to be used as the list name.| |Value Property|Value|The name of a property in the list of Business Objects to be used as the list value.| |Disable Sorting|FALSE|By default, the items in the selection list are displayed sorted alphabetically. This may be different from the order in which the items actually occur in the bound list data type. If we want the items to be shown in the order that they occur in the list, we need to set this property to "true" which disables alphabetic sorting of the items.|

If the List Type property is set to be Multiple Selection, the list shows as:

A good data type for binding to this control is the IBM supplied "NameValuePair" where the display property is called "name" and the value property is called "value".

The height of the select area can be controlled with

<Root> .dojoCheckedMultiSelectWrapper { height: xxx; }

To set the visual width of the Select control, the following CSS can be used:

This CSS can be included in an HTML widget … eg:

<style type="text/css"> .em20Select div.dijitComboBox { width: 20em; } </style>

Select Sample 1 – Selection based on other selection

In this sample, we will discuss how we can achieve the following effect. If the first select chooses the US state of Texas, then the cities will be Texas cities.

If the user selects California, then the cities will be Californian cities:

The Human Service that contains the solution looks as follows:

It prepares the static data for states and then shows the Coach.

The Coach looks like:

which is basically two Select controls. One for the State and one for the City.

The State control is bound to a list of Strings which represent the states:

The State control also has a configuration option as shown:

What this means is that when the selection value changes, that value will be stored in the "selectedState" variable.

The second Select, the one called "City" is configured as follows:

It uses a dynamic Selection Service to select the values it will show. The input parameter to the service is the variable "selectedState". What that means is that when "selectedState" changes, the Selection Service will be called to generate new values for the control. Here is the what the "Choose Cities" AJAX service contains:

The variables for this service look as follows:

The input variable called "text" is passed in the "selectedState" value. The "results" variable returns the list of cities. In my sample code, I have hard-coded the following code but it could just as easily have been a database query or some other logic:

Table

From the palette, the table looks as follows:

When dragged and dropped onto the canvas it shows as:

The table control provides a mechanism to show a list of business objects in a row/column format. When the table control is added to the canvas we can then insert further controls as its children. Each of these children will be used to visualize a particular column of data. The control will be repeated in the same column for each row that is displayed. Some common control types that make useful children include:


Examples of visuals on a web page:

|| |Name|Default|Description| |Selection Type|Single Selection|- - - | |Double Click-to-Edit||| |Set Editable Columns||| |Show Add Button|no|When selected, a button (+) appears beneath the table which allows us to add a new row into the table.| |Show Delete Buttons|no|When selected, a (X) button appears to the right of each row. If clicked, the selected row will be deleted.| |Add Button Hover Text|none|Text which is shown in a tooltip when the mouse hovers over the Add Button. Only meaningful if the corresponding "Show Add Button" is also selected.| |Delete Button Hover Text|none|Text which is shown in a tooltip when the mouse hovers over the Delete Button. Only meaningful if the corresponding "Show Delete Buttons" is also selected.| |Disable Sorting||| |Enable Pagination||| |Number of Rows Per Page||| |Initial Width|700px|Initial width of table| |Column Widths|(evenly sized)|Comma separated list of integers| |Column Width Unit|%|CSS Units for widths| |Hide Columns|||

Sizing the table

In the properties of the table there are three attributes that define the size of the table and the columns contained with. The first is "Initial Width". This value defines the size of the table as a whole. Setting this to be 100% causes the table to fill the available space.

The next parameters work together. The first is "Column Width Unit" which is a CSS sizing selector such as "%" or "px". The second is a comma separated list of "Column Widths". There should be a value for each of the columns in the table.

Adding rows

New rows can be added by enabling the "Show Add Button". However, this is only one technique and has some draw backs. Using this mechanism:

By realizing that the table reflects the current list data, any changes made to the list data are immediately reflected back in the table. What this means is that we can provide our own "add row" capability. Imagine adding a button to the page (say beneath the table). The button can be styled in any fashion we choose. When the button is pressed, it can call-back to a server script which can create a new record of data with initial values and add that record into the list of existing records. The server script can then loop back to the original coach. This will have achieved the same function as the default add button but will have provided a wealth of additional options to us.

Disabling selection

It is possible to disable a table from showing anything selected. To do this, we need to copy the Table Coach View and add:

selectionMode: 'none'

to the construction properties of the DataGrid. In addition, we can switch off the cell highlighting with:

.claro .dojoxGridCellFocus { border: 1px solid transparent !important; border-color: transparent #E5DAC8 #E5DAC8 transparent !important; }

Tabs

The Tabs Coach View is a container for other Coach Views. It allows a page to be displayed where the user can select from a set of Coach Views to be shown at one time. The selection is made via a tab at the top of the control.

The width and height of the tab container is controlled by the style class called "BPMTabControl". Knowing this you can change the size of the container as in:

.BPMTabControl { width: 250px; height: 250px; }

The width can be set to 100% to size the tab container to be the width of the page. As of the time of writing, the height must be sized to be a fixed pixel amount. No auto-sizing capability has yet been determined.

Text

The text field displays a text input box that can be bound to a string. The value of the bound string is shown within the text area. From here, a new value can also be entered.

From the palette, the Text Coach View looks as follows:

When shown on the Canvas, it looks like this:

The configuration properties of the Text Coach View are:

|| |Name|Default|Description| |Enable Autocompletion||| |Autocompletion Service||| |Autocompletion Delay||| |Validation|N/A|A JavaScript regular expression that will be applied to the entered data. If the data entered does not match the syntax, a client side error will immediately be shown.

|

To set the size of the Text control, the following CSS can be used:

.em30 div.dijitComboBox { width: 30em; }

With the above CSS class defined, we can now add "em30" as a class in the HTML Attributes of the Text Coach View:

This CSS can be included in a custom HTML Coach View … eg:

<style> .em30 div.dijitComboBox { width: 30em; } </style>

If a validation error is encountered, the Coach View shows the following indication:

Text Area

The Text Area Coach View shows an area of the screen into which text may be entered. From the palette it looks as follows:

and when added to a Coach it looks like:

This Coach View has a configuration option called "Text Area Type". This can have one of two possible values either:

When in Plain Text mode, the style of the Coach View remains as it is. However if Rich Text mode is enabled, when the Coach View has focus, it changes to show rich text selection capabilities as illustrated in the following image:

If a validation error is encountered, the Coach View shows the following indication in both plain text and rich text modes:

Take care when using this Coach View as it seems to wish to add newline characters at the ends.

To style the body of the plain TextArea, the following CSS can be used:

.CV_TextArea .dijitTextArea { color:red; text-align:center; font-weight:bold; }

And add the class CV_TextArea to the Coach View.

Vertical Section

The vertical section control allows us to have multiple coach views placed in a vertical column. On the palette, the control looks as follows:

When dragged and dropped into the layout area, it looks as follow:

The Vertical section can be bound to a list and the content of the section will repeat for each entry in the list.

If the label is "nulled", then the section will show without a visual container.

|| |Name|Default|Description| |Show border|FALSE|Adds a border around the body of the container.| |Square Border Corners|FALSE|If set to true and he borders are shown, then the corners of the border will be square instead of round.|

The height of a vertical section can be explicitly set with:

.MyClass .BPMBorder { height: 500px; }

Where "MyClass" is the name of a class added as an HTML attribute to the vertical section.

The width of a vertical section can be set with the width property of the HTML attributes.

Here is a Vertical Section with a couple of colored <div> blocks within it.

See that there is space at border of the contained children. A common request is how to switch off that space. If we were to use a CSS explorer, we would find that a class called "BPMSectionBody" is adding a margin to the right and left. As of 8.5.0.1, this margin is "1em". If we create a class definition that looks like:

.noMargin .BPMSectionBody { margin: 0px; }

and then add the class noMargin to the Vertical section, we would eliminate the left and right space:

In addition, a class called CoachView also adds a top and bottom margin of 0.5em.

.noMargin .CoachView { margin: 0px; }

There is one final style that adds a margin at the bottom of the Vertical Section:

.noMargin > div.BPMBorder > .BPMSectionBody.LastContentBox > .CoachView:last-child { margin: 0px; }

putting it all together we have:

.noMargin .BPMSectionBody, .noMargin .CoachView, .noMargin > div.BPMBorder > .BPMSectionBody.LastContentBox > .CoachView:last-child { margin: 0px; }

which will result in:

Content Box

From the palette, the content box looks as follows:

Once added to the canvas, it is shown as:

The Content Box is an advanced control that shows up in the Advanced Section of the palette only when building custom Coach Views. Its purpose is to hold other Coach Views that will be added later by the UI designer.

As an example of using this control, consider a custom horizontal layout style. The Content box would allow us to add arbitrary Coach Views into its space at design time.

Within a Coach where the Coach View that contains the Content Box is added, the Content Box shows up as:

|| |Name|Default|Description| |Layout Preview|Vertical|One of:

| |This View will manage its own Content|FALSE||

It is important to understand how a Content Box creates HTML. First, it will insert a <div> element with a class of "ContentBox". Its immediate children will be the children added to the Content Box in Process Designer.

For example, imagine we have a Content Box that looks as follows in Process Designer:

As we see, it contains two further Coach Views of type Text.

The inserted HTML looks like:

<div class="ContentBox"> <div class="Text">...</div> <div class="Text">...</div> </div>

// AMD Mapping: // dojo/_base/array → array var cbElement = dojo.query("> *", this.context.element)[0]; var cbContentArray = dojo.query("> *", cbElement); array.forEach(cbContentArray, function(item, I) { // Do something with each item });

Each of the children will have an attribute called "data-viewid" which will correspond to the ControlID or viewID of the Coach View that introduced it.

An important aspect of Content Boxes occurs if the Coach View containing the Content Box has a list data type and is bound to a list of variables. This causes the Coach View to replicate the content box instance once per entry in the list. For example, imagine we created a new Coach View called "MyCV" and defined it as follows:

If the layout of this Coach View contains a Content Box, then the content box will be replicated once per entry in the list associated with an instance of the Coach View. Remember that the DOM "class" value of each Content Box will be "ContentBox" allowing us to locate and move them.

Custom HTML

Custom HTML allows us to inject raw HTML into the generated Coach shown to the user.

From the palette it looks as follows.

When added into the canvas area, it looks like:

It's properties area contains the following:

The HTML can be entered directly into Process Designer, come from a managed file's content or come from the content of a variable.

For Custom HTML components added to a Coach, the values of variables can be inserted by enclosing them in dual curly braces:

"{{tw.local.myvariable}}"

If a Coach View contains a Custom HTML component, it can access the tw.businessData or tw.options scoped variables.

IBM Responsive Coaches Toolkit

From IBM BPM 8.5.6 onwards, a technology preview of a new Coach Toolkit has been made available. A technology preview is when IBM releases function that can be examined but should not be used in a production solution as it is currently unsupported. The thinking here is that in future releases of the product, it is likely that what you see here will indeed become supported and become mainstream. You should talk with your own IBM rep and ask him about the current plans. It may be that by the time you read this, the formal support may either already be in place or else may be coming just around the corner. Either way, you should still read here to grow an appreciation of just what is contained within the toolkit.

The first thing to realize is that the toolkit is not distributed with the product. Rather, you must download it from an IBM website:

https://hub.jazz.net/project/ibmbpm/bpm-responsive-coach/overview

At that location you should download the whole ZIP file for the project. When we extract the ZIP, contained withing will be a TWX file called:

responsive-coaches.twx

That TWX can then be installed into Process Center. At the conclusion, you will have a new toolkit at your disposal which will look as follows:

The documentation for the Response Coaches can be found within the standard IBM BPM KnowledgeCenter.

Responsive Coach – Button

A button is available.

Responsive Coach – Check Box

A check box is available with a variety of styles:

Styling with CSS

The Coach Views supplied with IBM have a certain "look" to them. Since these Coach Views eventually resolve to HTML sent to the browser, we find that the look is defined by standard Cascading Style Sheets (CSS). This also means that the look can be changed by changing the CSS applied.

Looking in the Toolkit that supplies the Coach Views (called Coaches) we find the master style sheet called "coach_ng_controls.css". (Note: the "ng" here stood for "Next Generation … i.e. the post v8 and beyond coaches). It is this style sheet that defines the look. In principle, one could replace or edit this file with new CSS definitions and the result would be a new look. However, I do not recommend doing that. This is an IBM supplied file and a patch/new-release could reset the file back to its default and you would have lost your changes. Rather, I suggest overriding this.

Let is look at an example. Here is a basic Coach view that has a Horizontal Section.

We see that it is colored default "blue". What if we want our horizontal sections to have a different color? One of the first things we need to do is determine which styles are affecting the existing look. To do this, I use Google's excellent "Chrome" browser which has in-built development tools. Switching to these, I can select an HTML "part finder" and click somewhere on the page. This takes me to the HTML that renders that part. Once found, I can then see the class names and styles that are being applied to that HTML. Again using Chrome, I can dynamically "tweak" those styles to see what changes I would want to make in a custom style sheet to change the look.

For example, changing:

to

resulted in:

Obviously, this change is not permanent, so now we need to look and see what would be necessary to affect these changes in a broader scope.

Our first pass is to insert a "Custom HTML" control into the page which contains the following:

<style> .BPMSectionHeader.box.blue { background-image: -webkit-linear-gradient(bottom, #A21BBC 0%, #4B1280 100%); } </style>

What this has now done is overridden the original CSS property with the new property. Effectively creating a union of the two CSS styles with the later definitions replacing the same previous definitions.

Here is a second example for the button:

.BPMButton { background-image: -webkit-gradient( linear, left bottom, left top, color-stop(0, #4B1280), color-stop(1, #A21BBC) ) }

which results in:

This looks like we are done … but not so fast. If we hover over the button we get:

What is happening here is that styles can be qualified. For example, we can have one style for "normal" display and a second style to be shown when the cursor is hovering over the part. Changing the definition to:

.BPMButton, .BPMButton:hover { background-image: -webkit-gradient( linear, left bottom, left top, color-stop(0, #4B1280), color-stop(1, #A21BBC) ) }

Changes the style for both normal and hover. Digging further, we find that the button still turns blue when it is held down. Looking at the generated HTML for a button press, we find that the implementation code for the button adds a new class when it is pressed. That class is called "BPMButton-down".

The final styling for our button is:

<style> .BPMSectionHeader.box.blue { background-image: -webkit-linear-gradient(bottom, #A21BBC 0%, #4B1280 100%); } .BPMButton, .BPMButton:hover, .BPMButton-down { background-color: #4B1280; background-image: -webkit-gradient( linear, left bottom, left top, color-stop(0, #4B1280), color-stop(1, #A21BBC) ); } </style>

Great!! … well … not so fast. This works great in Chrome … but will it work in FireFox and Internet Explorer? The answer is not quite. You see, the colors used in IBM BPM are not flat colors but are instead "gradients" and the CSS for gradients is browser specific. Yuk!! Fortunately, this is such a common problem that there are some elegant gradient generators for us. See for example:

http://www.colorzilla.com/gradient-editor/

To see how this works, we use the web page listed above and pick a green gloss:

Then we copy the generated CSS into our style. After application (and a few tweaks), we get:

This principle of overriding the default CSS formatting through the use of the Custom HTML Coach View within coaches can then be applied to each of the different controls to achieve a completely different look. So far we have concentrated on backgrounds but every aspect of the appearance is customizable including fonts (type, size, color etc), margins, boundaries, spacings and much more.

Once we have built our styles, we can then save them in a new CSS file and then make that a managed file. Once it is a managed file, we can then include the same styling in multiple Coaches over and over.

Making Left Labels

When adding text or other fields into a Coach, the label for the field is shown above the input area as shown in the following image:

This is fine, but it is a commonly asked request that the labels be shown to the left of the data input as in:

It was initially thought that this would require modification of the existing Coach Views to achieve but after some study of CSS, it was found that this could be achieved extremely easily. The following style sheet fragment shows how this can be done:

<style> .leftLabelText .textLabel { display: inline-block; width: 60px; } .leftLabelText .content { display: inline-block; } </style>

For the text elements that you wish to have with left labels, add the class called "leftLabelText" to the HTML Attributes:

And that is all there is to it. The styling will be slightly different for the various controls:

|| |Select control| |.leftLabelSelect .selectLabel { display: inline-block; width: 60px; }

.leftLabelSelect .content { display: inline-block; }| |DateTimePicker control| |.leftLabelDateTime .textLabel { display: inline-block; width: 60px; }

.leftLabelDateTime .BPMDateTimePicker, .leftLabelDateTime .dateTimePickerReadonlyDiv { display: inline-block; }| |TextArea control| |.leftLabelTextArea .textLabel { display: inline-block; width: 160px; vertical-align: top; }

.leftLabelTextArea .dijitTextArea { display: inline-block; width: 30em; }|

Adding a TextBox icon

A nice effect is to add an icon into the inside of a text box. For example:

This can be achieved with CSS similar to the following:

.dijitInputInner { padding-left: 20px !important; background-image: url('http://img.viralpatel.net/2008/11/magnifying-glass.gif') !important; background-repeat: no-repeat; }

Styling a Dojo button for BPM

Buttons supplied by IBM Coaches have a particular look and feel, here is the recipe to create such a styling for Dojo buttons:

<style>

.claro .myBPMButton .dijitButton .dijitButtonNode {

height: 26px;

color: #f2f2f2;

background-color: #1b69a9;

-moz-border-radius: 4px;

border-radius: 4px;

text-align: center;

font-size: 14px;

font-weight: bold;

background-repeat: repeat-x;

padding-bottom: 0px;

border: 1px solid #21486c;

border-top-color: #4178aa;

border-left-color: #4178aa;

border-bottom-color: #21486c;

border-right-color: #21486c;

filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#1B76BC', endColorstr='#124B80');

-ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorstr='#1B76BC', endColorstr='#124B80')";

background-position: 0px 0px;

background-image: linear-gradient(bottom, #124B80 0%, #1B76BC 100%);

background-image: -o-linear-gradient(bottom, #124B80 0%, #1B76BC 100%);

background-image: -moz-linear-gradient(bottom, #124B80 0%, #1B76BC 100%);

background-image: -webkit-linear-gradient(bottom, #124B80 0%, #1B76BC 100%);

background-image: -ms-linear-gradient(bottom, #124B80 0%, #1B76BC 100%);

background-image: -webkit-gradient( linear, left bottom, left top, color-stop(0, #124B80), color-stop(1, #1B76BC) );

}

.claro .myBPMButton .dijitButton .dijitButtonNode:hover {

color: #fff;

border-top-color: #4178aa;

border-left-color: #4178aa;

border-bottom-color: #21486c;

border-right-color: #21486c;

filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#429CE2', endColorstr='#124B80');

-ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorstr='#429CE2', endColorstr='#124B80')";

background-image: linear-gradient(bottom, #124B80 0%, #429CE2 100%);

background-image: -o-linear-gradient(bottom, #124B80 0%, #429CE2 100%);

background-image: -moz-linear-gradient(bottom, #124B80 0%, #429CE2 100%);

background-image: -webkit-linear-gradient(bottom, #124B80 0%, #429CE2 100%);

background-image: -ms-linear-gradient(bottom, #124B80 0%, #429CE2 100%);

background-image: -webkit-gradient( linear, left bottom, left top, color-stop(0, #124B80), color-stop(1, #429CE2) );

-moz-box-shadow: 0 2px 3px rgba(0,0,0,.5);

-webkit-box-shadow: 0 2px 3px rgba(0,0,0,.5);

box-shadow: 0 2px 3px rgba(0,0,0,.5);

}

.claro .myBPMButton .dijitButtonDisabled .dijitButtonNode, .claro .myBPMButton .dijitButtonDisabled .dijitButtonNode:hover {

color: #a0a0a0;

background-color: #113f66;

cursor: not-allowed;

}

.myBPMButton .dijitDisabled * {

cursor: not-allowed;

}

.myBPMButton .dijitButtonText {

margin-top: 2px;

}

</style>

Data Validation

When we present a Coach screen to a user we are expecting that user to enter some new information. Once the user has entered their data it is common for them to click some form of submission button to complete the coach and move on to the next activity. Unfortunately, humans have the ability to enter incorrect information, miss adding necessary information or make other types of mistakes. Ideally we want the coach to examine the data entered and, to the best of its ability, validate that the data entered is logically correct and consistent. Generically, this is known as data validation. Let us consider a trivial Coach that looks as follows:

We can imagine a user working with this screen. Examples of data validation rules for this might be:


Looking at our Human Service diagram, the basic flow of a normal Coach mechanism is:

This should be read as the Human Service starts, the Coach is shown and when the OK button is pressed the Human Service completes. At this basic level, there is no validation. Let us now look at how to add our validation functions.

First we define when the validation is to be performed. The answer to this (in our story) is when the OK button is pressed. Clicking on the OK labeled link, we see the following properties:

The one of interest to us here is the entry called "Fire Validation". The default value of this is "Never" which means that no validation will occur. Changing this to "Before":

informs the solution that when the link is followed, validation is to be performed. Although we have not yet described how to achieve this, at a high level you can now imagine that some how validation will be tested and, if the validation fails, it is as though we had not followed the link. Turning that around, the link will only be followed if the validation passes its tests.

After setting the Fire Validation property, the Human Services diagram changes:

Specifically, two new entries can be seen attached to the Coach. The first is that the attachment point on the Coach for the OK link now has a check-mark associated with it. This is a visual indication that this link has validation enabled and associated with it.

The second change is that there is now a new attachment point on the Coach which is shown at the bottom of the Coach. It is a filled green circle with a check mark inside it. This is the core of our story. When the coach recognizes that it needs to perform validation, control is passed through this validation attachment. Attached here will be logic which will perform the data validation rules to ensure that the data entered is correct. When we finally reach the end of job, we will have a Coach which, if rules fail, will visually indicate those errors:

Now we need to start getting technical and product specific and think about how the mapping between the logic of our rules is made known to the Coach so that it can display correctly.

First we introduce the data structure called "CoachValidation". We should think of this as a container for zero or more validation errors that we detect in our own logic. This data structure is supplied for us by IBM. When we execute our validation logic, we will populate this data structure with any errors we find. If we do not detect any errors, we will not have added any entries to the structure and this will be an indication that the Coach is "good" and that the link that caused the validation may proceed.

Within a Human Service, a singleton variable called "tw.system.coachValidation" is pre-defined. This is an instance of "CoachValidation". It is this variable that will be used to communicate between our validation logic and the Coach. With this in mind, we can fill in more of the picture. Our Human Service now looks like:

The way to interpret this is that when the "OK" link is to be traversed, validation is to be performed. Control will now pass through the validation attachment point to a Server Script called "Validate". This will perform the rules necessary for checking our variable values. This Server Script will update the singleton variable called "tw.system.coachValidation" and the return control back to the Coach. The Coach will now check to see if there are any errors indicated and, if not, allow the "OK" link to be followed to completion. If there were indicated errors, the "OK" link will not be followed and the screen will display indications of the errors. This will be the end of the validation until the next time the "OK" link is to be followed at which time the story will be repeated until there are no further validation errors.

Now we can turn our attention to the logic contained within the Server Script:

if (tw.local.name == "") { tw.system.addCoachValidationError(tw.system.coachValidation,"tw.local.name", "A name must be entered"); } if (tw.local.amount == undefined || tw.local.amount <= 0) { tw.system.addCoachValidationError(tw.system.coachValidation, "tw.local.amount", "Invalid number"); } if (tw.local.approved == true && tw.local.amount > 10000) { tw.system.addCoachValidationError(tw.system.coachValidation, "tw.local.approved", "Too big to approve"); }

Within the script, we perform data validation rules. If a rule fails, we then execute the method called:

tw.system.addCoachValidationError

This method takes three parameters:

|| |Parameter|Description| |coachValidation|An instance of a CoachValidation object which acts as a container of discovered errors. This is likely to be the predefined tw.system.coachValidation object.| |variable path|The path to a variable that has failed the validation. It is important to note that the string supplied here is the name of the variable (as known to the Coach) which is in error. We are not validating individual Coach Views/controls in the Coach … rather we are validating data. What this means is that when we encounter an error, we need to tell the coach which "data" is problematic and the Coach itself then determines which controls need to be updated to show the error.| |message|A text message that can be shown to the user to explain the reason for the failure.|

Executing this method adds a new validation error entry to the CoachValidation container. Remember that the singleton variable called "tw.system.coachValidation" is the variable that must eventually contain the errors for the Coach to work with them. It appears that each time the Validation attachment is fired, this variable is initialized to an empty set of errors (which is what we want).

From the previous description, we see that a validation service is associated with a Coach however it is a single validation service. We may want to execute different validations depending upon which button was pressed. One way to achieve this is to bind a Button control to a boolean variable. When the button is pressed, the associated variable is set to true. This can then be used as a distinction expression to determine which validations to perform.

Responsive Web design handling

Responsive web design is a term given to the notion that the content of a web page can be governed as a function of the size of the real-estate available to that browser. When browsers were first created, we could assume that they would run on desktops with monitors. As such, we kinda-sorta could assume that most users would have a similar sized screen. As tablets and phones started to provide more prevalent browser support, this story changed. A web page seen on a desktop may have a different set of requirements than one seen on a tablet or phone. This could be accommodated by designing multiple different web pages and choosing the one to show at runtime as a function of the screen size available. However, this seemed to duplicate work and introduced extra testing needs.

The solution making the rounds just now is the technique known as "responsive web design". If we discard the actual "English" of this phrase … what we are really saying is that this is a set of patterns and procedures that allow us to write a single web page which when viewed on different types and sizes of devices will alter its appearance and content to show a result chosen by the designer as a function of the devices type and size.

From IBM BPM 8.5.5 and onwards, the notion of responsive web design has been added to the Coach technology.

When we open a Coach Editor, at the top right we see a set of new icons:

These icons are used to represent different sizes of screens. There are three icons. The first represents small (a phone), the second represents medium (a tablet) and the third represents large (a desktop monitor).

IBM BPM has chosen that the width of the available browser space shall be broken into:

|| |Type|Screen width| |Small|640 pixels or less| |Medium|641 to 1024 pixels| |Large|More than 1024 pixels|

With these basics out of the way, let us now consider how to use this feature.

When in the Coach Editor, the editor will always be in one the three modes of small, medium or large. The default is large.

The current mode is the one which has the blue background. Here we see visuals of the three possible modes:

|| |Type|Icons| |Small|| |Medium|| |Large||

When in the large mode (default), the Coach Editor fills the whole of the Process Designer editor area. However, if we switch to medium or small, the size of the Coach Editor shrinks to the size associated with the selected type. In addition, an icon appears within the Coach Editor page to further indicate that we are in the non-default size mode:

Type is medium

Type is small

By selecting the size type, we can immediately see what our screens may look like in the smaller size. However, there is much more to the story than that.

First let us remember that a Coach is composed of multiple Coach Views placed on the Coach canvas and that each individual Coach View can have properties associated with it. Amongst these properties for Coach Views are positioning (size and borders) as well as visibility (hidden/shown). What the Coach architecture provides is the ability to have the values of these properties set differently for the different size types.

For example, we can say that a Coach View section is visible in medium and large screens but should the screen be shrunk to a small size, it will be hidden.

See also:


Boundary Events

Within a Human Service a Coach can loosely be thought of as a screen or web page. When the user interacts with the Coach there will come a time when the user would like to end their interaction with the web page and pass control back to the server. This will logically mean the "completion" of that Coach. To flag this, the Coach generates what it calls a "boundary event". This is an odd name but I can't think of anything better. It flags the exit from the current Coach and the entry into the next activity in the Human Service diagram.

By default, Button Coach Views within a Coach will generate a Boundary Event when they are pressed. For each boundary event added to a Coach, the result will be the ability to wire from the Coach to a subsequent activity within the Human Services definitions. Initially, when a new Coach has been created, there will be no Coach Views within it. This means that until Coach Views which generate boundary events are added, the Coach can not be wired as the source of a link in the Human Services editor.

See also:

Dynamically controlling visibility based on user

Note: As of v8.5, the visibility settings of Coach Views have been dramatically updated.

A recurring pattern that keeps appearing is the desire to show a Coach where the fields in the coach are editable or not editable based upon the group a user belongs to.

For example, imagine a group called "managersGroup". If the user is a member of this group, he can edit the a field.

If he is not a member of this group, he will be disallowed and any attempt to edit the field will be prevented.

If we remember that a field has a visibility attribute and that attribute can be set to "EDITABLE" or "READONLY" then we can build some logic that determines whether or not the current user is a member of the "managersGroup". If yes, we can set a variable to be "EDITABLE" and if not, set the same variable to be "READONLY". If we then bind the visibility attribute of the control to this variable, at run-time, the control will behave appropriately.

Here is the code for the "Set Visibilities" script:

tw.local.commentsVisibility = "READONLY"; var user = tw.system.user; if (user == null) { log.info("User is null!"); } else { if (user.roles == null) { log.info("No roles!"); } else { for (var i=0; i<user.roles.length; i++) { if (user.roles[i].name == "managersGroup") { tw.local.commentsVisibility = "EDITABLE"; break; } } } }

The TextArea coach view is then bound to the "commentsVisibility" variable:

and we have achieved the effect we were looking for. This recipe can be repeated for different fields. A field can also be set to "NONE" to hide it from view so we can also hide a control from visibility. Note that this should not be used for security as the data is still present at the Coach but simply not shown.

IBM sample Coach Views

On the IBM BPM Wiki there are a ton of additional Coach Views that are supplied "as-is". What this means is that the Coach Views can be freely downloaded and used in your own BPM solutions but if something goes wrong with them, you are basically on your own. Because of this, the Coach Views are provided with full source and the onus is upon you to read and review that source and treat the Coach View as if you had written it yourself. If you come back to the provider of the Coach View and are looking for support, there is no assurance that you will get any. This section of the book provides some examples of using some of these Coach Views for different purposes.

Data Change Boundary Trigger

The Data Change Boundary Trigger is a non-visual Coach View. It monitors data variables and when a variable changes, fires a boundary event.

See also:

Data Change Boundary Trigger – Updating one list when another changes

Imagine we have two lists on the screen. When the selected entry in one list changes, we want the content of the second list also to change. The Data Change Boundary Trigger can help to make that happen. What we do is insert a Data Change Boundary Trigger into the coach and bind it to the data for the first list "listSelected" property. When the first list changes its selection, a boundary trigger now fires. In the Human Service logic, we can now determine what the new selection of the list is and change the content of the second list correspondingly. A sample called "KolbanTK – Test – Data Change Boundary Trigger – List Changes" is supplied with the toolkit.

Dashboard Coach Views

A toolkit is supplied with the product named "Dashboards". When added to a Process App project an additional set of Coach Views are available. By default, these are not shown in the Coach editor and must be explicitly enabled within the filter menu:

Once done, a new set of building blocks will be found underneath the Dashboard grouping:

With the controls now available to be added to our Coaches by the coach designer, we will turn our attention to descriptions of each of them.

See also:

Batch Modify Dialog Control

It is not yet known how to properly use this Coach View

Palette icon:

Canvas appearance:

Configuration parameters:


Breadcrumb Control

It is not yet known how to properly use this Coach View

Palette icon:

Canvas appearance:

Configuration parameters:

Category Selection Control

The Category Selection Control shows a list of potential selectable options as what appear to be "links". Each entry is separated by a vertical bar:

The possible choices are supplied in the "Selection List" configuration property as a list of name/value pairs. The current select is available as the bound variable to the Coach View as a string value which is the value of the corresponding name/value selected.

Palette Icon:

Canvas appearance:

Configuration parameters:

Chart Control

The Chart control is used to create and display charts that show data to the end user. The types of charts available include pie, bar, column and line. The data type used for binding this control is called "ChartData". These charts are based upon the Dojo charting controls.

Before we get into the details of a Chart Control, let us first ensure that we are grounded in what we want to achieve. A chart is used to graphically display some data. Commonly, we can visualize that data as a table:

|| |Month|Sales| |January|$1,000.00| |February|$3,000.00| |March|$600.00| |April|$2,500.00|

If we now think of the Month values as the X-Axis and the Y-Axis as the values, we can achieve a chart like:

It is important to visualize in ones mind the relationship between table data and a potential chart to show that data. If necessary, write down on paper some sample table data and ensure that you solidly comprehend how your would take that table data and create a chart.

Palette icon:

Canvas appearance:

Configuration parameters:

The primary chart configuration is its data binding which is of type ChartData. It is a highly nested structure which is described next bottom up.

The ChartDataPoint object contains two fields:

The ChartDataSeries object contains two fields:

A ChartDataSeries contains the data to be shown in the chart. For different chart types, the ChartDataPoints represents different entities:


A ChartDataPlot object contains the following:

The ChartDataPlot contains multiple ChartDataSeries.

A ChartData object contains the following:

The resulting structure then looks like:

Here is an example of a template of a variable to hold a ChartData object:

tw.local.myChartData = { plots: [ { series: [ { label: "My Label", data: [ { name: "name1", value: 1 }, { name: "name2", value: 2 } ] } ] } ] };

So, with this interesting series of data structures out of the way, let us look at some simple plots of data.

|| |Horizontal Bar|Vertical Bar|Line|Area Line|Pie| ||||||

The primary configuration of a chart is through the chart properties page which contains:

Title (String) – The title of the chart. This appears to be an HTML Head Level 2 tag.

Width (Decimal) – The width of the chart in pixels.

Height (Decimal) – The height of the chart in pixels.

Theme – The theme used to describe the visuals of the chart. Values include:

These themes are supplied by IBM BPM.

Custom Theme – If the Theme setting is "Use custom theme", this property describes the style of theme to use. This will be a JSON version of a dojox.charting style object. The JSON data is provided as constructor information to the Theme() object.

Legend (ChartLegendPositionSelection)– Where (if anywhere) the chart legend is shown. Choices are:


In the following image, we see a legend shown to the right:

Stack bar plots

Stack line plots

Stack area plots

Force categorical data – Forces the scale on the X axis to include space for items not present and scales from the minimum value to the maximum value in width to make the chart "even".

On Click – This option can be bound to a variable of type ChartClickEvent. This data type contains:


When a section of the chart is clicked on by the user a boundary trigger event is fired and the variable's values changes to reflect the item clicked. This can be used by other Coach Views or functions to cause an update as a result of a user selection. A good example of this might be a drill-down where the user sees something interesting in the chart and wishes to see more about that item.

When one clicks on a chart, we can see it become hi-lighted. This may not always be the desired effect. We can disable this by setting the chart's style attribute to "outline-style: none".`

The way the data is shown is based on the configuration property called "Display options". This is a rich data structure that contains a list of ChartPlotDisplayOptions:

plotType (ChartPlotType) – The type of chart to draw for this plot. The choices are


plotTypeFixed (Boolean)

displayHorizontalAxis (Boolean) – If set to true, a horizontal axis is drawn for all chart types but Pie. Pie has no axis. Here are samples for columns and bars:

|| |Bars|Columns| |||


In this example, we set the gap to be 1 pixel:

When working with chart data, we also have the opportunity to show corresponding tables of the data. If we look carefully at the Series, we see it is a list of ChartDataPoint objects where each of those contains a name and a value property. If we bind a BPM Table Coach View to the list of ChartDataPoint and then create two columns … one of text and bound to "name" and other of decimal bound to "value", we end up with a pleasant table showing the data in the chart:

Chart with Time Selector Control

Although this control advertises itself as a chart with time selection, reality seems to show that it is actually a specialized chart that shows bar and column items with a trend line running through it. This seems to "spoil" it for general purpose use.

Palette icon:

Canvas appearance:

Configuration parameters:


This is an Ajax service that has the following inputs:


which returns the following output:


Dashboard Layout template

This control provides the template for layout for Process Portal.

If we want a normal white backgound, add the following in a Custom HTML component:

<style> .Dashboard_Layout_Template.CoachView.CoachView_show .BPMDashboardContent > .ContentBox { background-color: white; background-image: none; } </style>

If we want the font for a title to look large, add the class "CurrentPage" to the HTML Attributes of an Output Label.

Data Control

The Coach View displays data associated with the process instance. The thinking behind this is that someone reviewing or examining this instance can immediately see exposed "data" to quickly see information about that instance.

Within a process's variable definition, there is a check box that defines whether or not the variable in the process will be shown:

Here is an example of the Coach View in action:

The data shown in this control is retrieved from an Ajax Service call. The default version supplied by IBM is pretty rich but should it need to be replaced, the following is the signature that needs to be implemented:

This Coach View works in conjunction with the Refresh Controller.

Palette icon:

Canvas appearance:

Configuration settings:


See also:

Data Section Control

The Data Section Coach View is a mix between a Data Control and a section.

Palette Icon:

Canvas appearance:

Configuration parameters:


Dialog Control

The dialog control is used to open a child window within the Coach. Initially, when the Coach appears, the dialog box is not shown. The control can be bound to a Boolean typed variable. When the variable becomes true, the dialog is shown. Here is an example of what the dialog control looks like:

Its top area is composed to two title areas. One defined by the property called "Title" and the other defined by the "Subtitle" property. In the upper right of the dialog is a close button which appears to be the only way to close the dialog.

Palette icon:

Canvas appearance:

Configuration parameters:

The properties for this Control are:


Default Instance Details template

Palette Icon:

Canvas appearance:

Configuration parameters:

Floating Layout Control

Palette icon:

Canvas appearance:

Configuration parameters:

Follow Button Control

Failed to get this working.

Palette Icon:

Canvas appearance:

Configuration parameters:

Gantt Chart Instance Details Control

The binding type for this control is an instance of GanttChartInstanceDetailsData. This data structure contains:


Here is an example of this control:

Palette icon:

Canvas appearance:

Configuration parameters:


Gantt Chart Process Overview Control

The binding data for this control is an instance of GanttChartProcessOverviewData. This contains the following fields:


A service provided as part of the Dashboards toolkit called "Process Gantt Chart Initialization Service" returns an instance of this object when called with:


Here is an example of what this control looks like:

Palette icon:

Canvas appearance:

Configuration parameters:

Icon Button Control

Could not get this working

Palette Icon:

Canvas appearance:

Configuration parameters:


Instance Activities List Control

Palette Icon:

Canvas appearance:

Configuration parameters:


Instance Activities Section Control

Palette Icon:

Canvas appearance:

Configuration parameters:

Instance Details UI Service template

Palette Icon:

Canvas appearance:

Configuration parameters:

Instance List Control

Palette Icon:

Canvas appearance:

Configuration parameters:


Instance Summary Section Control

Palette Icon:

Canvas appearance:

Configuration parameters:

Navigation Controller Control

The Navigation Controller control appears to be an unusual component in the mix. It almost appears as an after-thought. It provides no visual appearance, no parameters and no data-binding. It simply "is". The documentation on it is light … presumably because there is so little that can be done to configure it. However, from examination and reverse engineering, it seems to be an event subscriber that, when triggered, causes a jump to a different web page or a refresh of the current web page with different content.

Palette icon:

Canvas appearance:

Configuration parameters:

None.

See also:

Process Diagram Control

This Coach View draws a diagram of a BPD process with optional annotations and other goodies upon it.

In order to draw a diagram, we need to tell the Coach View which process to draw.

The property called "Process ID" is the BPD ID of the process. This is a string that starts 25.xxx. An instance of this can be retrieved from a TWProcess instance from the "id" property. Since we also have branches and snapshots, these can further define what the diagram looks like. If we ask to draw a diagram and that the process has changed over time, we still need to know which version of the diagram to show. As such, we need to supply one of Snapshot ID (2064.xxx) or Branch ID (2063.xxx) or Project ID (2066.xxx).

Palette icon:

Canvas appearance:

Configuration parameters:


Process Due Date Control

Palette icon:

Canvas appearance:

Configuration parameters:

Process Instances List Control

Palette icon:

Canvas appearance:

Configuration parameters:


Process Summary Control

This control provides a summary in terms of numbers of overdue, at risk and on track counts of a given process type.

The binding data for this control is a ProcessSummary instance. An example of sourcing data for this might be:

var myProcess = tw.system.model.findProcessByName("Process 1"); tw.local.processSummary = myProcess.performanceMetrics.retrieveProcessSummary(null, false);

Palette icon:

Canvas appearance:

Configuration parameters:


See also:

Refresh Button Control

Palette Icon:

Canvas appearance:

Configuration parameters:

Search Control

Palette icon:

Canvas appearance:

Configuration parameters:

Service Controller Control

Palette Icon:

Canvas appearance:

Configuration parameters:

Split-Panes Section Control

Palette Icon:

Canvas appearance:

Configuration parameters:

Stream Control

Palette icon:

Canvas appearance:

Configuration parameters:

Task List Control

This control shows the list of tasks available for a user. The control seems to be able to update itself dynamically so as tasks are added or removed, the control dynamically changes. Here is an example of a task list with three tasks:

The heritage of this Control models the Process Portal that was built for v8.0 of the product. The Task List basically shows horizontal bars with one bar for each task. If we click on a task, the details of that task are shown. This is the value defined in the "Narrative" section of the task definition.

A pull-down menu on each task allows the user to perform additional actions.

The "Modify Task" option opens a dialog which allows the priority and due date of the task to be changed.

We have the option of only showing a subset of available tasks using the "Initial list size" option. This controls how many items are initially shown. If there are more items to be shown than we have initially asked for, a "Show More" button is displayed:

Clicking on the description of the task should launch the Coach for that task. At present, it is not known how to achieve this. When clicked and there is no current own

If no tasks are available, the phrase "No tasks were found" is shown:

The Task List Control has a relationship to the "Navigation Controller" control.

Unfortunately, it appears that the height of the Task List controller is fixed at 600 pixels. There is no apparent way this can be changed through the use of a style sheet.

Palette icon:

Canvas appearance:

Configuration parameters:

Height (Integer) – The height of the control measured in pixels. If not supplied, the default value is 600 pixels. If more tasks are available to be shown than can be displayed in the supplied height, scroll bars are automatically added. A special height of "0" causes the control to be tall enough to show all the available tasks.

Initial list size (Integer) – The initial number of items to show in the list. The default is 25 items.

Team ID

User ID

List scope – A filter to specify which class of tasks are shown. This property is an instance of "TaskListScope". The options for this property are:


Include assigned users

Filter by due range

Search filter

Retrieve task list – This is an Ajax service which, when called, returns the tasks to be shown in the Coach View.

Expand all rows (Boolean) – Show each of the tasks in the list already expanded and hence their details are also shown.

Assigned users

Tasks – The lists of tasks that are currently display.

The Task List service has the following signature:

The core implementation makes a call to tw.system.retrieveTaskList() to return the taskListData.

See also:


Tasks Due Control

Palette icon:

Canvas appearance:

Configuration parameters:

Team Roster Control

This control display a list of users belonging to a team:

The binding data for this control is a List of TeamRosterEntry. This data type has the following structure:


The function called retrieveTeamMemberList() can be used to retrieve a list of TeamRosterEntry structures:

var myTeam = tw.system.org.findTeamByName("Team A"); tw.local.rosterList = myTeam.dashboard.retrieveTeamMemberList();

Palette icon:

Canvas appearance:

Configuration parameters:


See also:

Team Summary Control

Palette icon:

Canvas appearance:

Configuration parameters:

Text Filter Control

Palette icon:

Configuration parameters:

At runtime, it looks as follows:

It provides a "pretty" text input area specifically designed for filtering values.

Two-Column Section Control

Palette icon:

Configuration parameters:

Zoom Control

Palette icon:

Canvas appearance:

Configuration parameters:

Exposing a Human Service as a portlet

Java provides a standard called JSR-286 which describes how visual components called "Portlets" can be build to be used in products called "Portlet Servers". IBM builds a product called IBM WebSphere Portal. IBM BPM provides the ability to expose certain types of Human Services as JSR-286 compliant portlets for inclusion in such a portal server.

For a Human Service to be used as a portlet, we must define the Human Service as "Exposed As: Dashboard". From there we will find an option to create a portlet:

Before the portlet can be created, the Process App which includes it must be part of a snapshot. Once done, the "Create a Portlet from the Dashboard" link can be clicked. This will launch a wizard used for the creation of the portlet. The screen for the wizard is shown next:

We are asked for the name of the portlet which will be shown to the portal user. We are also asked for a description. Possibly the most important attribute at this stage is the notion of the "File location". A portlet manifests itself as a Java EE Web Archive File (a .war file). We supply the location where the war file will be written.

Once the wizard is complete, we will now find that the WAR file has been generated for us. We are now able to deploy this to our portal server.

|| |

To deploy the WAR to Liferay, we can copy it to the <Liferay>/deploy directory where it will be automatically consumed.|

Page Flow/ Screen Flow Solutions

The model of using Coaches with Human Services is that when a Human Service is reached, the BPMN process described by the BPD pauses until the Human Service completes. When the Human Service is reached, a new entry is added to the task list commonly seen in the Process Portal. A user selects the task from the task list and at that point sees the Coach. The user then works on the Coach/Human Service and completes the Coach allowing the process to continue. When the next Human Service is reached, the story repeats including picking the task from the task list.

This story paints the picture of human interaction as "task" oriented meaning that each Human Service is a discrete tasks that has a beginning and end and, when ended, has no relationship to the next.

In some scenarios, an alternate style of human interaction is desired that is termed "screen-flow". In this style, the desire is for a screen to be shown to the user and, when the user completes the screen, the BPD/BPMN process gets control back, does some further work and then reaches the next Human Service. At this time, a new screen is shown to the user as soon as possible. The effect is a page transition under process control as opposed to a task claim, view, complete, claim, view, complete story.

Unfortunately, this style of process modeling and user interface design is simply not possible with the IBPM product at this time when working with Coaches. A circumvention is to code/design a series of Coaches in a single Human Service such that transition from one Coach to another follows a screen flow. Nested Service calls in the Human Service can then be used to call additional services. The down-side of this approach is that it bypasses all the features of BPDs. This includes:


Let us now drill down to see what would be involved in creating a Human Services style screen flow solution. We will start by assuming that there is a Human Service which contains multiple Coaches wired together perhaps with logic and service calls between them.

To begin, we need a mechanism to start an instance of this Human Service. We will assume the existence of a function called “startInstance”. What this will take as input is a description of which service to start. This will be of the form “<ProcessApp>@<ServiceName>”.

We can next make a REST call that looks as follows:

/rest/bpm/wle/v1/service/<service>?action=start&createTask=true

This will start our task instance. The return data from the REST request is also important. It contains a lot of details about the newly started Human Service. Among these, the following fields of information will be necessary to keep around:


In a screen flow solution, we will be instructed on which screen to show next. We retrieve that from the “data.step” data. We should then assume that the UI knows how to display the information on such a screen.

When the user has completed the current screen, the UI code will invoke a function I have called “finishUI”. This function takes two parameters:

The design of “finishUI” looks as follows:

if we have return Data then REST /rest/bpm/wle/v1/service/<serviceId>?action=setData&params=<jsonParams> Complete the page using REST /rest/bpm/wle/v1/service/<serviceId>?action=<action> Save the response data

Screen Flow using BPD

Let us take a second look at Screen Flow techniques. This time we will look at how this might be achieved at the BPD level. The first thing we have to do is read the section on:

One of the challenges of this techniques has been that virtually anything between two Human Activities on the BPD diagram will cause the auto-flow to break. However, an intriguing opportunity has been noticed. Imagine we have two BPD Human Activities (lets call them A and B) and we wish to perform other work between them. If we place yet another Human Activity between A and B but the Human Service that implements this activity has no Coach UI within it, then screen flow progresses. This means that we can include a variety of service integration calls as nested services.

The activity labeled “Integration” is defined as a Human Activity but its content can include a variety of different integration functions.

User Interface fragments

As experience with IBPM grows, a number of useful fragments and techniques can be captured. Here are a sample of such:

Embedding another HTML page

We can embed an HTML page from another location within the coach. We can achieve this through the use of the HTML iframe tag. Create a Custom HTML component and define its body to looks as follows:

<iframe src="http://www.ibm.com" width="100%" height="620px"></iframe>

The src attribute names the web page to be shown. The width and height should also be supplied to describe the size of the internal frame used to display the content. Here is an example:

Making a REST call from a Coach

Imagine we have a coach and we wish to make a REST call from it. An example of such a call would be to make a callback to BPM to invoke one of its exposed REST services. We will assume the existence of a modern browser. The secret to being able to make the REST call is to leverage the XMLHttpRequest API. At a high level, we will use the following:

var request = new XMLHttpRequest();
request.addEventListener("load", function() {
   console.log("Load complete!");
});
request.open("GET", "http://myurl");
request.send();

See also:

Debugging a Client Side Human Service JavaScript fragment

We have the ability to include JavaScript within our Coach web pages without resorting to using Coach Views. We can achieve this by creating a Custom Html Coach View and, within the HTML of that coach view, inserting an HTML script tag. For example:

<script>
function generateRandom() {
	var val = Math.floor(Math.random() * 1000);
	debugger;
	alert ("New value is " + val);
}
</script>

We can then call the function that we named generateRandom() as the result of an event. This works great. However, if we want to debug the code, things start to go wrong. Note the debugger; statement that we added. This should cause the debugger to be invoked when that statement is encountered. When we run this in the latest Chrome, sure enough ... the debugger is encountered but we have a problem. The source code of the function is not displayed. The reason for this is to do with the architecture of BPM Client Side Human Services. Specifically, the HTML that is sent to the browser appears to come from a database and not a file and has no file associated with it. What this means is that when the browser encounters our request to show the source, it doesn't know which file to view/display containing the source. Thankfully, there is some magic that solves the problem. I don't like describing code and techniques as magic as that diminishes the science of our technology but, in this case, I can't really describe it better than a piece of magic.

The trick is to use a subtle feature of JavaScript which interprets a value in a comment as meta data to give hints to the compiler/debugger. Specifically, we inject a comment that is of the form:

//# sourceURL=filename.js

for example:

<script>
function generateRandom() {
	var val = Math.floor(Math.random() * 1000);
	debugger;
	alert ("New value is " + val);
	//# sourceURL=myFile.js
}
</script>

This has to be inserted before the close of the script. It informs the compiler "Should you need to debug this code, make the assumption that it is part of a source file with the file name given.". Magic indeed. However, the result is perfect. When we now run this within the context of a client side human service and the breakpoint is encountered, we are shown the correct source statements and breakpoints and variables as desired.

No Comments
Back to top