Developing custom reports using the Coach Reporting Framework in IBM Business Process Manager

Learn how to use the TWList pattern, part of the Coach Reporting Framework, to create custom reports that query the application data for reporting purposes. We'll demonstrate the creation of two reports with drill-up and drill-down options configured using the custom toolkit. This content is part of the IBM Business Process Management Journal.

Share:

Smitha Venugopal (smvenugo@in.ibm.com), IT Specialist, IBM

Photo of Smitha VenugopalSmitha Venugopal is an IT Specialist with IBM Software Services for WebSphere (ISSW). She has over 10 years of IT experience, with a focus on business process management. She specializes in WebSphere Process Server, IBM Business Monitor, and WebSphere Business Modeler with strong experience in design, development, and deployment of BPM solutions. Her current focus is on WebSphere Lombardi.



Sateesh Balakrishnan (satebala@in.ibm.com), IT Specialist, IBM

Photo of Sateesh BalakrishnanSateesh Balakrishnan is an IT Specialist with IBM Software Services for WebSphere (ISSW). He has over 10 years of experience and is currently working on the BPM and BRMS track specializing in WebSphere Lombardi and WebSphere ILOG. In his previous assignment at ISSW, he worked on application infrastructure stream with in-depth skills in WebSphere Application Server, J2EE application migrations, and performance troubleshooting and tuning of WebSphere Application Server. He has worked in various capacities, including design and development of J2EE solutions. His current interests are BPM and BRMS systems.



12 December 2012

Also available in Chinese

Introduction

IBM Business Process Manager provides several reporting options: out of the box scorecards, customized reports and reports generated in third-party tools. Out-of-the-box reports enable you to analyze personal performance, team performance, business process performance and SLA violations. Customized reports enable you to analyze business data specific to your processes. You can define variables to track and create customized reports to query your tracked data in Process Designer. Users can view the resulting reports in Process Portal.

In this article, you'll learn how use the TWList pattern in the Coach Reporting Framework to create custom reports that query the application data for reporting purposes. We'll walk through the process of creating two reports with drill-up and drill-down options configured using the custom toolkit.

In our example, we won't use tracking events or the auto-tracking feature to capture the data for reporting. Instead, we'll query an existing custom application database that is used to persist the application data in lieu of the Performance Data Warehouse database (PDWDB). This approach improves performance by eliminating the additional database operations (DB INSERT) to the PDWDB database. Using this approach is advantageous in situations where business processes span across multiple products or integration frameworks that are logically connected in an enterprise. You can maintain a central database and build reports based on this central database, rather than tracking the required data in the PDWDB that is specific to BPM.

We'll demonstrate this by using the scenario described in the following sections.


Example scenario

In this scenario, we'll create a report for calculating the average salary of the employees for a particular department in an organization during any particular year.

For illustration purposes, a human service is created to demonstrate how to use the TWList pattern to develop custom reports in two Coaches, Yearly Salary Report and Yearly Income by Dept and Grade, as shown in Figure 1. The integration services used here facilitate the data to be shown in the Coach reports.

Figure 1. Diagram for the human service
Diagram for the human service

We'll use the TWList pattern of the Coach Reporting Framework Toolkit to build the reports. In order to use the data objects and other constructs and elements provided, you need to create a dependency between the Process App and the toolkit after importing the TW List Pattern toolkit from the BPM wiki.

The toolkit contains the following:

  • Data
    • lswR2ChartData
    • lswDrillDown
    • lswTestObject
    • lswTestObject2
    • lswTimeTrend
  • Chart Layout Types
    • Bar
    • Combo
    • Pie
  • Report
    • ReportFromTWList
  • Data transformation,
    • Object Data Transform is provided in the Toolkit will be used.

We'll use the DataObject lswR2ChartData to specify the data mapped in the report and the DataObject lswDrillDown to drill down into a detailed report from a top-level report. We'll also use the report ReportFromTWList from the toolkit in the Coach.

Report generation essentially comprises two steps:

  1. Generate the data to be shown in the reports.
  2. Embed the report in a Coach.

We'll demonstrate this by developing two reports in the following sections.


Create a yearly salary report

As seen in Figure 1, integration services can be developed to populate the data in the form of a list of type lswChartData. The Get Annual Salary services retrieves the required data (in our example, average salary for every department during the selected year) from a persistent media (the application database in our case) and constructs a list of lswChartData objects. Figure 2 depicts the Get Annual Salary integration service along with the SQL query used. The variable tw.local.results is of type lswChartData list.

Figure 2. Get Annual Salary integration service
Get Annual Salary integration service

(See a larger version of Figure 2.)

Examine the lswChartData object to find the three parameters Series(String), label(String) and Value(Decimal). This data is used in the Yearly Salary Report to display the report based on a filter value of 2009, 2010, 2011 or 2012.

To embed the report in the Yearly Salary Report Coach, we'll use a custom HTML control and paste the following in the Presentation tab in the properties of the custom HTML. To do this, complete the following steps:

  1. Create an instance of the report ReportFromTWList, which is available with the toolkit, as follows:
    <# var report = TWReport.getByName('ReportFromTWList'); #>
  2. Specify the chart type using the APIs provided by TWlist pattern, as follows:
    <#report.setFilterValue('reportType','3dGroupedBar'); #>

    The list of available chart types is provided in the BPM wiki.

  3. Specify the attributes as shown below to define the value, label and series, or dimension, to the chart.
    <#
    report.setFilterValue('listVariableName','tw.local.results');
    report.setFilterValue('seriesConstant',tw.local.filterSelection);
    report.setFilterValue('labelProperty','label');
    report.setFilterValue('valueProperty','value');
    #>

    Notice that the generated data (tw.local.results is set as the listVariableName property. Similarly, the attributes of the list variable are now set to specify the values for label and value using the labelProperty and valueProperty properties.

    In our example, because we're showing only one series value in the report (the selected year), we'll set the seriesConstant property instead of seriesProperty.

  4. Set the other properties, such as the x-axis and y-axis labels, height, width, as shown below.
    <#
    report.setFilterValue('chartBottomAxisLabel','Department');
    report.setFilterValue('chartLeftAxisLabel','Average Salary');
    report.setFilterValue('chartWidth',1000);
    report.setFilterValue('chartHeight',500);
    report.setFilterValue('chartColorTable','xff0f00_150,xfff00f_150,
    x0000ff_150');  
    #>
  5. In the Yearly Annual Report, we'll enable a drill-down capability to drill down from a department so that a user can view the next level of detail based on the selected department in the selected year, as shown below.
    <# 
    report.setFilterValue('ddButtonId','ButtonGroup2_Button0');
    report.setFilterValue('ddSeriesVariableName',
    'tw#local#drillDown#series');
    report.setFilterValue('ddLabelVariableName',
    'tw#local#drillDown#label');
    report.setFilterValue('ddDataVariableName',
    'tw#local#drillDown#data');
    #>

    To enable drill-down functionality, you need to set the ddButtomId to a hidden button's control ID (ButtonGroup2_Button0 in this case).

    Note: You need to have a button on the Coach for drill-down and set its visibility to hidden.

    When the user clicks on the bar in the graph for a particular department, the hidden button is clicked and the control is navigated outside the Coach based on the connections specified in the diagram. In our example, the control navigates to the Get Employee Salary service.

    When this is done, the year and the selected department needs to be passed to the service so that details of that department are extracted for the selected year. This value is set in the drill-down object using the ddSeriesVariableName, ddLabelVariableName and ddDataVariableName as seen in the previous listing.

  6. Finally, display the report in the Coach as follows:
    	<#= report.displayPage('report'); #>

The report should look like Figure 3. Notice the Average Salary (value) listed against the different departments (label) listed, with 2012 as the year (Series).

Figure 3. Yearly Salary Report for department
Yearly Salary Report for department

(See a larger version of Figure 3.)

When one of the bars in the graph is clicked, the report drills down to show the yearly income for the selected department with respect to the grades of the different employees in that department.


Create a yearly income by department and grade report

This report is initiated when the user drills down from the Yearly Salary Report with the year and department passed as input to this service.

Similar to the previous report, an integration service Get Employee Salary is used to generate the data for viewing in the report, which comprises the distinct grades and the average salary with respect to a department and year. Hence the lswChartData object list would have the grade as the label and the average salary as the value. We also augment the report with a table that provides more detailed information. To enable this, the services uses a list EmployeeSalaryData that comprises all the employees with their grades and salaries in the selected department and year.

Figure 4 shows the details of Get Employee Salary integration service.

Figure 4. Get Employee Salary integration service
Get Employee Salary integration service

(See a larger version of Figure 4.)

As shown in the SQL results below, tw.local.empSal is a list of a user-defined DataObjects, EmployeeSalaryData, which contains the salary details for each employee in the department with his or her grade for the selected year. The SQL results would look similar to the following listing.

<# 
report.setFilterValue('ddButtonId','ButtonGroup2_Button0');
report.setFilterValue('ddSeriesVariableName',
'tw#local#drillDown#series');
report.setFilterValue('ddLabelVariableName',
'tw#local#drillDown#label');
report.setFilterValue('ddDataVariableName',
'tw#local#drillDown#data');
#><object type="EmployeeSalaryData[]">
  <arrayElement size="4">
    <item type="EmployeeSalaryData">
      <property name="empcd" type="String">001</property>
      <property name="grade" type="String">B1</property>
      <property name="Salary" type="String">1500000</property>
      <metadata>
        <property name="dirty" type="Boolean">true</property>
        <property name="shared" type="Boolean">false</property>
        <property name="key" />
        <property name="version" />
      </metadata>
    </item>
    <item type="EmployeeSalaryData">
      <property name="empcd" type="String">002</property>
      <property name="grade" type="String">B2</property>
      <property name="Salary" type="String">1700000</property>
      <metadata>
        <property name="dirty" type="Boolean">true</property>
        <property name="shared" type="Boolean">false</property>
        <property name="key" />
        <property name="version" />
      </metadata>
    </item>
    <item type="EmployeeSalaryData">
      <property name="empcd" type="String">003</property>
      <property name="grade" type="String">B1</property>
      <property name="Salary" type="String">1200560</property>
      <metadata>
        <property name="dirty" type="Boolean">true</property>
        <property name="shared" type="Boolean">false</property>
        <property name="key" />
        <property name="version" />
      </metadata>
    </item>
    <item type="EmployeeSalaryData">
      <property name="empcd" type="String">004</property>
      <property name="grade" type="String">C</property>
      <property name="Salary" type="String">2200000</property>
      <metadata>
        <property name="dirty" type="Boolean">true</property>
        <property name="shared" type="Boolean">false</property>
        <property name="key" />
        <property name="version" />
      </metadata>
    </item>
  </arrayElement>
  <metadata>
    <property name="dirty" type="Boolean">true</property>
    <property name="shared" type="Boolean">false</property>
    <property name="key" />
    <property name="version" />
  </metadata>
</object>

The server script Split Lists is responsible for providing the data required for the chart lswChartData list, because two lists are required now: one for the report and the other for the table.

To embed the report in the Yearly Income by Dept and Grade Report Coach, we'll use a custom HTML control, as follows:

  1. Create an instance of the report ReportFromTWList, which is available with the toolkit, as follows:
    <# var report = TWReport.getByName('ReportFromTWList'); #>
  2. Set the desired chart type as shown below using the APIs provided by the toolkit:
    <# report.setFilterValue('reportType','groupedBar’);#>
  3. Specify the attributes as show below to define the value, label and series, or dimension, to the chart:
    <#
    report.setFilterValue ('listVariableName','tw.local.results');
    report.setFilterValue ('seriesProperty','label');
    report.setFilterValue ('labelProperty','label');
    report.setFilterValue ('valueProperty','value');
    #>

    Notice that the generated data is set as the listVariableName property (tw.local.results of type lswChartData)

    Similarly, the attributes of the list variable are now set to specify the values for series, label and value using seriesProperty, labelProperty and valueProperty properties.

  4. Set the other properties, such as the x-axis and y-axis labels, height, width, and so on, as shown in the following listing:
    	<#
    	report.setFilterValue ('chartBottomAxisLabel','Employee Grade');
    	report.setFilterValue ('chartLeftAxisLabel','Income');
    	report.setFilterValue ('chartWidth',600);
    	report.setFilterValue ('chartHeight',300);
    	report.setFilterValue ('chartColorTable','x00ff00_150');
    	#>
  5. Finally, display the report in the Coach as follows:
    <#= report.displayPage ('report'); #>
  6. In this report, we need to display a table to give specific details about the employees, their grades, and their incomes in a tabular format that can serve as a reference to the chart. To display this, drag the variable tw.local.empSal for the user-defined DataObject EmployeeSalaryData from the palette onto the Coach. A repeating table is automatically created. Make sure the Selection control checkbox is unchecked in the Properties view of the table.

Figure 5 shows the report for the Finance and Operations department in 2012.

Figure 5. 2012 Salary Report for the Finance and Operations department
2012 Salary Report for the Finance and Operations department

(See a larger version of Figure 5.)

We've have augmented the report chart with a table that lists the details of the employees in the desired department.

Additionally, we provided a drill-up functionality by introducing a button in the Coach that navigates to the Get Salary Service to retrieve the yearly income for each department for the year, given the filter selection. Upon drill up, the previous report is shown.


Conclusion

This article described an alternate approach to creating custom reports. It illustrated how report generation can be independent of the Performance Data Warehouse database and the tracking features provided in BPM out of the box. Because the reports are embedded in coaches with this approach, you gain more flexibility in terms of providing data for reporting, user interface, additional filter criteria and the way the reports can be accessed. For example, the service we built in the article can be exposed in the dashboard for a role or specific set of people just like any other human service.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=851589
ArticleTitle=Developing custom reports using the Coach Reporting Framework in IBM Business Process Manager
publish-date=12122012