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.