IBM Business Automation Workflow Server-Side Paging Section Asset

Diorella Mari Tom

Published in

IBM Digital Business Automation Tips and Assets

11 min readMar 11, 2020

Leonard Blunt, Greg Ekaprana, Okka Sudaryanto, Diorella Mari Tom

Code Repository

Paging Section Toolkit GitHub Repository

Introduction

IBM Business Automation Workflow (BAW) provides a set of APIs that is used to retrieved data from a data source. The JavaScript API provides certain components to improve the behavior of your business process models. There are many ways to retrieve and display your data into data tables, and some of the components you can use are Service Call, Service Data Table and Table views.

You might find situations dealing with large data sets consisting of thousands, if not hundreds of thousands of records. In such scenarios, retrieving all the data at once to the client is not reasonable, impacts to resource consumption and system performance and efficiently make this impractical. To aid with paging through the records, a pattern supported by a standardized coach view asset was established. With the combination of Server-Side Paging Section Coach View (CV) and server-side queries, we can limit the results and page at the server side, reducing and limiting the number of records retrieved from the source.

The asset that we will discuss here limits the data retrieved to a table, manages the data paging on the server side and can help satisfy the performance and loading time for a better user experience. In our primary use case in the project for which it has evolved was on dashboards, and as such we found it useful to incorporate an Automatic Refresh feature where based on a fixed time interval the page is reloaded. This is useful on situations where the records are constantly updating in the table and you want to display the records in real-time, or in the business case that we had where the dashboard was a work initiation or trigger point using the records in the table to trigger next actions. Once we had multiple paging, we needed to incorporate to the asset a way to track selected records across pages. This is useful on situations like exporting selected records, mass updating of selected records, mass printing of selected records, etc.

In this article, we will show you how to use the Server-Side Paging Section Coach View. The example implementation provides the details of the following:

Setup and Configuration

In this section, let’s look through and identify the key components of the view to understand the setup and configuration needs. Figure 1 illustrates the key components of the coach view, we shall provide the explanation and detail on the numbered items.

Key Components:

Content Box — Table View

This is where you place the standard Table coach view and customize the columns specific to the data you wish to show. You still need to setup the configuration properties of the table view, how you want your records to be rendered, the look and feel and the behavior of the table. A simple example is shown here,

In the Behavior Configuration, if you select the Multiple Selection mode, this will trigger the selected record functionality of the paging section. You may check Configuration Properties and JavaScript Functions for more details on how to use Selected Records Tracking.

Figure 3: Table View — Behavior Configuration

Important: From the Table view configuration, do not set up the ‘Initial page size’ because this would affect the page size setting from the Server-Side Paging Section CV. Please keep the Behavior configuration setting empty, except for the ‘Selection mode’ configuration option.

2. Page Size

This contains the maximum number of records per page, which limits the records retrieve in the database. The default value is set in the Configuration properties of the Paging Section CV.

3. Page Counter and Navigation Buttons

This contains the number of the page the current records display in the table and the navigation buttons that allows you to move through the records in the table. Each button corresponds to the direction that you can move in the table.

4. Auto Refresh Settings

These settings are configurable where they set automatic refresh rate of the table.

On/Off Switch — allows a user to manually turn off refresh on a table that has been configured to auto refresh.
Interval setting — the time in minutes between the automatic refresh.
Refresh button — allows a user to manually refresh the table and not wait for the interval.

The starting properties of auto refresh are configurable in the coach view (Configuration Properties > Auto Refresh).

5. Selected Records

This contains an action button to clear the selected records in which if set to true (Configuration Properties > Configuration > Hide Clear Selected), will show the ‘Clear’ selected button, otherwise hide the button. This component will also depend on the chosen selection mode in the Table view configuration, if set to ‘Multiple’, then you should set and bind the value of the property in Configuration Properties > Selected Records Tracking section.

Note: In the coach view, we used style sheet to disable the select all on table. This is a deliberate architecture choice, remember that we are dealing with large data sets. This then created the need for a component to trigger the clear of selected records.

Data Binding — ANY (List)

Paging Section CV is bound to any list of objects, this should be the same as the list of objects bounded in the Table view inside the Paging Section CV, see example below.

Figure 4: Paging Section CV Binding and Table View Binding

Configuration Properties

Paging Section CV is also bound to configuration options which are used in managing and handling the data paging, filtering and sorting, automatic refresh and selected records tracking and console logging. The paging section has 4 specific configuration groups (Data Service Configuration, Configuration, Auto Refresh, and Selected Records Tracking) each will now be explained.

Data Service Configuration

This configuration group details the downstream service flow and the parameters for this flow.

Figure 5: Data Service Configuration Options

Table 2: Data Service Configuration Descriptions

The ‘Data Service’ specified in the configuration includes the implementation on retrieving the data from the database where you create and execute SQL statements and return the result as a list of data object. This service flow must have the following parameters:

Figure 6: Service Flow Parameters and Descriptions

Note:
1. Filter Data and Sort Data are used and discussed in detailed on the article, 'IBM BAW Filtering and Sorting Coach for Server-Side Paging Section Asset'.2. The pageSize value has a very important role on data paging because it limits the records retrieved from the database. It is advised to set the pageSize value to a more acceptable value where users can view the records without further scrolling down, because setting the page size to thousands of records would defeat the purpose of server-side paging solution and might also cause issues on performance and loading time.

2. Configuration

This group is more general operations and appearance settings for the coach view. Very important here is the control id of the embedded table.

3. Auto Refresh

This grouping captures the configuration options related to auto refresh of the table data.

4. Selected Records Tracking

This grouping is specific to a business object that is used to track the selected records over multiple pages.

Figure 9: Selected Records Tracking Options

Table 5: Selected Records Tracking Descriptions

Note: On the next version of Paging Section asset, Selected Records Tracking configuration will be removed as a configuration options instead it will be placed and handled in inline JavaScript.

Events

Custom JavaScript Functions

This section provides the detailed documentation of the custom JavaScript functions to manipulate data in coach view. These functions are defined in the Inline JavaScript of Paging Section CV.

init — Returns: {Object[]}

The init() function initializes the table and loads the first page as the current state.

reload

The reload() function reloads the table and retains all state.

refresh

The refresh() function refreshes the table, loads the first page as the current state and clears all the records selected from the table.

getAllSelectedRecords — Returns: {Object[]}

The getAllSelectedRecords() function returns all the selected records in the table (if any).

Example:

var data = _this.ui.get("Paging_Section_CV1").getAllSelectedRecords();

hasRowSelected — Returns: {boolean}

The hasRowSelected() function returns whether a particular record is selected.

Example:

if (_this.ui.get("Paging_Section_CV1").hasRowSelected()) {     _this.ui.get("Button1").setEnabled(true);} else {     _this.ui.get("Button1").setEnabled(false);}

clearSelectedRecords

The clearSelectedRecords() function clears all the selected records from the table.

Example:

_this.ui.get("Paging_Section_CV1").clearSelectedRecords();

Implementing the Server-Side Paging Section Coach View

This section details an example and shows how to use the Server-Side Paging Section CV. The example requires to retrieve and display the product purchase data records in the table and to preview the selected product purchase data records. The example will walk you through setting up and retrieving data by creating the end user view as seen here in Figure 11.

Figure 11: Server-Side Paging Section User View

There are four steps to this example:

Create the client-side human service
Create the coach view and embed and configure the Paging Section Coach View and Table
Write the server-side query to retrieve the data
Extend the example to demonstrate the selected records processing

The code is available in the Paging Section Toolkit stored in the Git repository.

Step 1: Create the client-side human service

In the Diagram view, add a coach that provide the user interface to display the product purchase data records in the table, see Figure 12.

Figure 12: *Paging Section CSHS implementation example*

In the view for the coach, add the PurchaseProductTableCV and bound it to the data list, see Figure 13.

Figure 13: *Paging Section CSHS coach layout example*

In the coach view configuration options, pass the PagingSectionInit business object and the selected data list, see Figure 14.

*Figure 14: PurchaseProductTableCV Configuration Options*

Step 2: Create the coach view and embed and configure the Paging Section Coach View and Table

PurchaseProductTableCV coach view is bound to the data list and has the PagingSectionInit business object passed as a configuration variable. It also has two other configuration variables which are: inputData string that is passed when you have an additional data on retrieving records and selectedPurchaseDataList that is used when working on selected records.

*Figure 15: PurchaseProductTableCV variable declarations*

In the coach view, we embed the following view components:

Paging Section coach view
Table coach view which is placed in the context box of the Paging Section Coach View
Other components include a button and modal section that will be used to demonstrate working with selected records.

*Figure 16: PurchaseProductTableCV coach view layout and binding*

*Figure 17: PurchaseProductTableCV Configuration Options*

*Figure 18: Table View Binding and Configuration Options*

Note: Another component that you can add in this coach view is the server-side table filter and sort implementation which will be discussed in detailed on the article, 'IBM BAW Filtering and Sorting Coach for Server-Side Paging Section Asset', as this asset only focuses on data paging.

Step 3: Write the Server-Side Query

When the human service is launch, purchase data records are retrieved and displayed in the table. The table is populated by executing a service flow that query the records in the database, see implementation in Figure 19.

*Figure 19: Get Product Purchase service flow example*

This service flow includes the following:

Server scripts to construct SQL statements that will retrieve the records and total number of records in the database.

SQL statement to retrieve records

SELECT
EPP.ID AS ID,
RECEIPT_ID AS RECEIPTID,
PURCHASE_DT AS PURCHASEDT,
PURCHASE_AMT AS PURCHASEAMT,
COUNTRY AS COUNTRY,
CITY_CD AS CITYCD,
ECC.CITY_NM AS CITYNM,
PRODUCT_TP AS PRODUCTTP,
EPT.PRODUCT_NM AS PRODUCTNM
FROM <#= tw.env.DSN_NEWSCHEMA_NAME #>.EG_PRODUCT_PURCHASE EPP
LEFT JOIN <#= tw.env.DSN_NEWSCHEMA_NAME #>.EG_CITY_CODE ECC ON ECC.CD = EPP.CITY_CD
LEFT JOIN <#= tw.env.DSN_NEWSCHEMA_NAME #>.EG_PRODUCT_TYPE EPT ON EPP.PRODUCT_TP = EPT.ID

SQL statement to get total number of records

SELECT 'TOTAL' as NAME, CHAR(COUNT(*)) as VALUE FROM <#= tw.env.DSN_NEWSCHEMA_NAME #>.EG_PRODUCT_PURCHASE

2. Server script to add LIMIT and OFFSET clauses to the query. These two query clauses are very important in dealing with large result sets. LIMIT is used to limit the number of rows returned by the query and OFFSET instructs the database where to start returning rows within the query result. It is required to add LIMIT and OFFSET to your SQL query for the server-side paging section.

tw.local.sql = tw.local.sql + " LIMIT " + tw.local.pageSize + " OFFSET " + ((tw.local.currPage -1) * tw.local.pageSize);

3. Service tasks that will invoke SQL Integration service to execute the SQL and retrieve records from the database.

Figure 20: *SQL Integration Service Implementation*

Figure 21: Service Task > *Input and Output Mappings*

Note: Filter and Sort script contains the details on handling filtering and sorting of the table which will be discussed in detailed on the article, 'IBM BAW Filtering and Sorting Coach for Server-Side Paging Section Asset'.

To test, run the Paging Section CSHS from the Web Designer and this should display the screen in Figure 22.

*Figure 22: Product Purchase Data List Table example*

Step 4: Extend the example to demonstrate the selected records processing

Once you have the multiple paging view, you can also extend your implementation to incorporate the selected records tracking. This example includes a ‘Request Review’ button and modal section that will demonstrate the selected records processing.

*Figure 23: PurchaseProductTableCV coach view layout with ‘Request Review’ button and modal section*

Selecting of record/s in the table will enable the ‘Request Review’ button. To enable/disable the button, you need to call the enableRequestReviewButton() function on ‘On row selected by user’ event of the Table view. This will check if the user selected any record/s on the table.

Figure 24: *PurchaseProductTableCV Table View Events — On row selected by user*

Figure 25: *PurchaseProductTableCV — enableRequestReviewButton()*

When you click this button, it will launch the ‘Request Review’ modal section to preview the selected product purchase data. The ‘On click’ event of the ‘Request Review’ button calls the requestReview() function which will get all selected records and display the selected purchase data on the list table.