Support for Business Process Modeling Notation (BPMN) was added to IBM® Rational® Software Architect Version 8.0. You can now produce reports of your BPMN models, using several built-in Eclipse Business Intelligence and Reporting Tools (BIRT) report designs. This tutorial demonstrates how to use the BIRT report designs to produce basic diagram and metrics reports of BPMN models. It also demonstrates how to modify the included designs to fine-tune reports to your specifications. The new BPMN data source and several useful XPath functions will also be covered. The instructions described in this tutorial pertain to Rational Software Architect 8.0 and later.
Prerequisites and setup
This article is based on the assumption that you have some knowledge of using Rational Software Architect to model BPMN diagrams, as well as some familiarity with BIRT reports.
Ensure that the following features have been included as part of your BPMN installation:
- BPMN modeling
- Architecture reporting (BPMN) with BIRT
Also ensure that you have access to two or more BPMN models, either in your current workspace or accessible in your file system.
Using built-in BPMN reports
Rational Software Architect v8.0 comes preloaded with two built-in report templates designed for BPMN models. These templates are accessible through the Report Configurations dialog window.
- In the Modeling Perspective, select Run > Report > Report Configurations from the menu. Alternatively, click the arrow beside the Launch As button on the toolbar and select Report Configurations, as Figure 1 shows.
Figure 1. The Launch As… toolbar drop-down menu
In the Report Configurations dialog that appears, you can create, manage, and run various configurations.
- The left panel should show BIRT Report as a category. Select this category and click the New button to create a new report configuration. Optionally, rename the new configuration.
- Ensure that the Built-in radio button is selected, and click Browse to see the built-in BPMN report designs.
Figure 2 shows the Report Configurations dialog at this point.
Figure 2. The Report Configurations dialog view before browsing
Figure 3 shows the two built-in reports for BPMN models.
Figure 3. Sample BPMN model reports
Diagram report for a single model
- Select the BPMN Model Diagram Report from the list of built-in reports. This is a simple report design, showing the name of the model, the primary documentation of the model’s process and collaboration, and its diagram.
Back in the Report Configurations dialog, the Report Data > Data Sources pane now shows BPMN Data Source.
- Click that entry in the Data Sources pane.
When the Add button next to the Instance Models pane becomes enabled, click it and navigate to a single BPMN model.
- In the Load Resource dialog that appears, navigate to a BPMN model in the current workspace or in your file system. After you have selected a model, click OK.
As Figure 4 shows, the Report Configurations dialog now shows the name of the selected model in the Instance Models pane.
Figure 4. The Instance model has been set
BIRT reporting in Rational Software Architect permits various output formats, such as HTML and PDF.
- For this example, leave the default Report Output, HTML.
- By default, the report is generated in a temporary directory, but you have the option to change it to whatever location you prefer. To change the location of the report output, use the Workspace or File System buttons in the Report Output portion of the dialog, as Figure 5 shows.
Figure 5. Changing the report output location
- To create the new report, click Apply and then Report.
The report will be generated and saved in the location that you specified earlier. In addition, it will open in the default reader for that particular output. In this instance, your default browser will show the new HTML report.
Depending on your browser and the BPMN model that you used to generate the report, the new report will look something like Figure 6.
Figure 6 Sample HTML report
Diagram report for multiple models
In the previous figure, notice that the title of the report indicates the name of the single model used in the report. It is possible to associate a diagram report with multiple BPMN models by following these steps:
- Return to the Report Configurations dialog and create a new BIRT report. Name this one
- Using the Browse button, browse to the BPMN Model Diagram Report again.
- Select the BPMN Data Source line in the Data Sources pane and use the Add button to add the same instance model used in the previous configuration.
- Now, use the Add button again to add a second BPMN instance model. Remember that the models can be in the same workspace or anywhere in your file system.
- Rather than creating the default HTML report, change the format of the report to Adobe® Acrobat® PDF® format.
- (Optional) Change the location of the report to make it easier to find later.
- Click Apply.
After the new report configuration is saved, the configuration details should look similar to Figure 7.
Figure 7. The Report Configuration dialog for multiple models report
- Click the Report button to generate the PDF version of the report. The new report should open in your default PDF reader and should look something like Figure 8.
Figure 8. PDF report with multiple models
Notice that the title of the report indicates the names of both models used in the report.
Metrics report for a single model
One of the report templates included in Rational Software Architect is a simple metrics report suitable for a single BPMN model.
- Return to the Report Configurations dialog and create a new BIRT report. Name this one
- Using the Browse button, browse to the BPMN model Metrics report.
- Select the BPMN Data Source line in the Data Sources pane, and use the Add button to add a BPMN instance model to this report.
- Leave the format of the report as the default HTML, but change its location to something that you can find more easily, such as your current workspace.
- Click Apply to save the report configuration and then click Report to launch the report.
Depending on your browser and the BPMN model that you used to generate the report, the new report will look something like Figure 9.
Figure 9. Sample metrics report
The included metrics report simply provides basic metrics about the associated BPMN model. The following sections are included:
- Name and primary documentation of the model
- Count and type of visible elements in the model (model elements that appear in the diagram, such as call activities, data objects, events, gateways, tasks, and flows)
- Count and type of ‘invisible’ elements in the model (model elements that do not directly appear in the diagram, such as escalations, event definitions, interfaces, messages, or signals)
- Summary metrics for tasks and global tasks, including the primary documentation of each (for example, business rule task, service task, user task)
- Summary metrics for events, including the primary documentation of each (examples: start event, intermediate events, boundary events, end events)
- List of all events and the event definitions associated with each
- List of all interfaces and operations associated with each
The default metrics report will not meet your exact needs. Its purpose is to serve as a jumping-off point when creating customized BPMN reports, as discussed in the next section.
Customizing an existing BPMN report design
You can use the Report Design perspective, as well as the Report Explorer view, when customizing existing report designs or creating new ones.
- To switch to the Report Design perspective:
- From the menu, choose Window > Open Perspective > Other.
- If necessary, check the Show all check box.
- Select Report Design from the list, and click OK.
This perspective offers several views that are useful when editing report designs, such as the Data Explorer view.
- Open the Report Explorer view by selecting Window > Show View > Other.
- Navigate to the Reporting > Report Explorer view and click OK.
The Report Explorer view is prepopulated with several reports designed for BPMN models, as shown in Figure 10.
Figure 10. Report designs
Each report design is contained in a
rptdesign file, the exact name of which is shown in parentheses after the name of the report. The "BPMN Model Diagram Report" and "BPMN Model Metrics Report" are the same report designs that are included as the built-in reports in the Report Configurations dialog. The third design, "Blank BPMN Model Report," contains data sets suitable for BPMN models but no specific layout.
Copying an existing report
To customize an existing report design, you must make a copy must and save it to your file system.
- Select the report to be customized from the list in the Report Explorer view. In this case, select the BPMN Model Diagram Report.
- Right-click and select Copy from the drop-down menu.
- Click the BPMN Model entry in the Report Explorer view, and select Paste from the right-click drop-down menu.
The Paste Report dialog that appears contains a name for the new report,
copy_0_BPMN Model Diagram Report, as well as a description of the report. The description is copied from the source report.
- Modify the name and description as you choose. For instance, rename the report to
My BPMN Diagram Report,and leave the description unchanged, as in Figure 11.
Figure 11. Naming the new report
- Click Next.
The next page of the Paste Report wizard requires a location on your local file system where the report will be saved. When the page first appears, it shows an error: "The file cannot be saved in the specific location." This is because you have not yet chosen a location.
- Use the Browse button and navigate to a location in your file system.
The dialog is now updated with the exact path name for the report (and its associated properties file), as the example in Figure 12 shows.
Figure 12. Choosing a location for the new report
- Click Finish.
The new report will now be listed with the other BPMN report designs in the Report Explorer view, as shown in Figure 13.
Figure 13. New report listed in the Report Explorer
properties file saved with the new report can be used for localization of your report. The properties file is automatically assigned as a resource for the new report.
- To start editing the new report (customizing your copy of the Blank BPMN Model Diagram report), double-click the new report in the Report Explorer view to open it.
Exploring the Report Explorer perspective
This article is based on the assumption that you have some basic knowledge of BIRT reporting. The Resources section lists several useful ways to learn more about how to use BIRT reporting. Here, we simply introduce those parts of the Report Explorer perspective that you can use for customizing your existing BPMN reports.
When you first open a report design, the main editor shows the layout of that design. For this example, it would look something like Figure 14.
Figure 14. Main editor window
At the bottom of the main editor window, notice that there are several tabs, including Layout and Preview.
- Click the Preview tab. A preview of the current report will be generated. The report will be empty, except for the title, because you have not yet assigned an instance model to this report.
- The Report Explorer perspective includes the Property Editor view. Select that view to see the properties related to the current report design.
The General tab of the properties view includes information about the path of the current
rptdesign file, as well as the display name. In addition, there is a layout preference near the bottom of that tab. Use this layout preference to choose between Auto Layout and Fixed Layout," (see Figure 15).
Figure 15. Layout preference radio buttons
The Auto Layout preference is selected by default and would normally be selected when the report design is finalized. However, you might have noticed that the preview just generated was very wide. During the process of customizing the report, we suggest that you switch to the Fixed Layout, because that will force the generated report to a more manageable width.
When the main editor window is in layout mode, the Data Explorer view is populated. It contains a list of the Data Sources and Data Sets used for the current report (see Figure 16).
Figure 16. Data Explorer view
The data source used for the current report design is a standard BPMN data source; however, it currently has no instance models associated with it. In order to make the preview of the report more meaningful, assign an instance model (from your local file system) to this data source:
- Right-click on the BPMN Data Source in the Data Explorer view.
- Select Editfrom the drop-down menu.
- Select the Models entry in the left panel and click the Add button.
- In the Load Resource dialog window, use the Browse File System (or Browse Workspace) button to navigate to an existing BPMN process model. (Ensure that the process model has elements on the diagram and that the process itself has at least two documentation elements associated with it.)
- Click OK.
Now the data source is associated with a BPMN model, and there will be contents to populate the data sets and the report preview mode.
To confirm this, click the Preview tab in the main editor window.
When the preview is generated, it should show the following:
- A title
- The name of the BPMN model
- The first documentation element of the model
- The diagram associated with that model.
- Return to the layout view by clicking the Layout tab of the main editor window.
The BPMN Model Diagram Report uses several data sets:
- The Diagram data set
- Used to extract the actual diagram from the BPMN model.
- The Root Elements data set
- Used to extract the documentation elements from the root elements. In this example, you are retrieving the documentation for the actual process in your BPMN model.
- The Joint: Root Element Diagram data set
- Used to create an intersection between the other two data sets, so that you can extract the diagram and the documentation associated with the model’s process.
You can explore these data sets by selecting them and choosing Edit from the drop-down menu. More information about BPMN data sets will be presented here later.
Adding a new element
The current report design displays only the first documentation element associated with the process or collaboration. However, it is possible that any process or collaboration has multiple documentation elements. You are going to modify the existing report design to include a second documentation element, below the first.
The report is laid out in a table, one column wide.
- Select the row containing the first documentation element by clicking slightly to the left of the
When the correct row is selected, the middle row (in this table) should be highlighted, as Figure 17 shows.
Figure 17. Selecting the [firstDoc] row
- After the correct row is highlighted, right-click and choose Insert > Row > Below. A new Detail Row is added to the table, directly below the
[firstDoc]refers to the firstDoc column in the Root Elements data set. Right-click on that data set now and choose Edit.
- Navigate to the Column Mapping page.
Notice that the column query for the firstDoc column is
documentation/@text. This column query will extract the default, or first, documentation element. However, the documentation element associated with BPMN elements is actually a collection, and it is possible to specify exactly which index to use.
Adding a new column mapping
You are going to add a new column to this data set, extracting the second documentation element.
- Still in the Column Mapping page, click Add new column here.
- Insert a name for the new column, such as
- Change the column query to
documentation/@text, and leave the type as String. To test the new column mapping, select the Preview Results page.
Assuming that the instance model associated with the data source has a second documentation element, it will appear in the secondDoc column of the appropriate line. See Figure 18 for an example.
Figure 18. Preview results with secondDoc column
- Click OK to finalize the changes to the data set.
An aside: Queries for documentation
Table 1 lists the queries (including XPath functions) that you can use to extract documentation elements. Remember that documentation can be associated with most BPMN elements, not just the process or collaboration itself.
Table 1. Queries for documentation
|Retrieve the default (first) documentation element.|
|Retrieve the ith documentation element.|
| Retrieve all documentation elements, each element prefaced with the |
Returns a string.
| Retrieve the first ‘depth’ documentation elements, each element prefaced with the |
Returns a String.
getSomeBPMNDocumentation(., 3, "*") retrieves the first three documentation elements, using * as a bullet.|
getSomeBPMNDocumentation(., 10, "-->") retrieves the first ten documentation elements, using --> as a bullet.
Notice that using depth = 0 is equivalent to requesting all documentation elements, meaning that
Editing the joint data set
Although you have modified the Root Elements data set, you cannot yet use the new column mapping in the layout. That is because the layout is actually bound to the Joint: Root Element Diagrams data set, so you need to modify that data set to account for the new secondDoc column mapping:
- Right-click the joint data set and select Edit.
When the Edit Data Set dialog appears, focused on the Query page, it shows both the Diagram and Root Elements data sets. You can see the new secondDoc column mapping included under the Root Elements data set, as Figure 19 shows.
Figure 19. Editing the joint data set
Do not make any changes to this page. The common field between both data sets is Name. In fact, just by opening the data set to edit it, you have updated it.
- You can confirm this by clicking the Preview Results page. Notice the new Root Elements::secondDoc field.
- Click OK to close the dialog.
Notice that the new Root Element::secondDoc is now visible in the Data Explorer view.
Binding column mapping to detail row
Now that you have modified the data set to include the second documentation element, it is time to insert it into the actual report layout:
- Simply drag the new secondDoc column mapping from the Data Explorer view to the new (empty) detail tow in the report layout.
As you hover your cursor over the detail row, you will see the mouse cursor annotated with the + sign, indicating that this location is an acceptable target for the column mapping (see Figure 20).
Figure 20. Dragging the new column mapping to the detail row
When you have completed the drag-and-drop operation, you can confirm the placement of the new column mapping by previewing the layout:
- Click the Preview tab of the main editor window.
You might notice that the padding for the original (first) documentation is not the same as for the new (second) documentation. By default, the new documentation has
padding = 1 on all four sides; the original documentation has larger padding.
(Optional) Select the new element in the layout window and navigate to the Padding tab of the Property Editor view.
Change the padding.
Other tabs in the Property Editor can be used to change the font, border, etc.
You can also customize other parts of the report. For example, you can add a new label to identify the new documentation field, or change the font, margins, borders, and so forth. These customizations are not specific to BPMN, and you can learn more about them from citations in the Resources section.
Creating a new BPMN report design
When creating a new report design, it might be easiest to simply make a copy of the Blank BPMN Model Report, which is prepopulated with a BPMN data set and several data sources. However, if you prefer, you can create a new, empty report and then associate it with a BPMN data source and BPMN data sets.
Creating a report from scratch
- In the Report Design perspective, select File > New > Report from the menu.
- In the New Report dialog, choose a project as the parent folder, and provide a name for the file. Note: The file name does not have to be the same as the report’s name.
- Click Next and, from the Report page, select the type of template to use. For a blank report, select Blank Report.
- Click Finish.
A new report is created, with no data sources or data sets.
Creating a new BPMN data source
To create a new data source, right-click Data Sources in the Data Explorer view, and select New Data Source from the menu.
Figure 21 shows the New Data Source wizard that will then be available.
Figure 21. New Data Source wizard
- Ensure that the "Create from a data source type in the following list" option is selected and choose the BPMN data source. You can rename the data source, but that’s optional.
- Click Next.
On the Models page of the wizard, the Metamodels pane is already populated with the relevant BPMN and GMF metamodels. You can use the Add button to browse to one or more existing BPMN models to use as input for your new report (optional).
- For this example, browse to the same process model that you were using in the previous section.
- Click Finish.
The Data Explorer view now shows the new data source.
Creating a new BPMN data set
- To create a new BPMN data set, right-click Data Sets in the Report Explorer, and select New Data Set from the menu to open the wizard.
Figure 22 shows the New Data Set wizard.
Figure 22. New Data Set wizard
- Choose the data source that you want from the list of existing BPMN data sources. The Data Set Type will be "BPMN Data Set."
- Change the name of the data set (optional). if
- Click Next, and then click Next again on the Parameters page.
On the Row Mapping page, notice the Browse button in the left pane. There are two ways to browse: browse in a particular metamodel or browse in a specific instance model. With the first, you can create a row query based on anything in the metamodel. The second restricts you to row queries based on items that exist in the instance models associated with the data source. For example, compare the next two figures. Figure 23 shows the contents of the BPMN meta-model, and Figure 24 shows the contents of the process model used in the previous section.
Figure 23. Browsing the BPMN metamodel
Figure 24. Browsing a BPMN instance model
- Assume that you want to create a data set based on call activities. There are two ways in which you can accomplish this:
- You can browse to the metamodel and select CallActivity > Activity from the tree in the left pane.
- Or you can browse to the instance model (assuming that it contains a call activity) and select a call activity from the tree in the left pane.
- Either way, the next step is to click on the > button in the Row Query pane.
- At this point, a Choose dialog window provides a list of query expressions to choose from. Currently, the only query expression supported for BPMN modeling reports is of the
If you have chosen to browse the metamodel, this will be the third option in the Choose dialog, as shown in Figure 25.
Figure 25. Choose dialog to pick query
If you have chosen to browse an instance model, choose the
instanceOf option, but then edit the expression so that the first term is
It is better to browse the metamodel when creating data sets to avoid having to edit the expression.
- On the same page, there is a check box for Evaluate for every data source instance model. Ensure that this is checked so that it is possible to preview the data set and report layout by using the instance model associated with your data source.
- Finally, the same page has a Type field. After setting the Row Query expression, click the > button by the Type field.
If you have browsed using the metamodel, the Type field will be automatically populated with the appropriate type:
bpmn2:CallActivity. If you had browsed the instance model, upon clicking the > button, you would be presented with the dialog window shown in Figure 26.
Figure 26. Choose dialog to pick a type
This dialog occurs because the call activity chosen from the instance model is not a root element. A CallActivity is an Activity, which is a FlowNode, which is a FlowElement, which is a BaseElement. Only CallActivity is shown in the instance model, so you would not have been able to choose one of the other element types. When browsing the metamodel, you can choose any BPMN type for the query expression.
- For this example, ensure that the type is
- Click Next.
The next page specifies the column mapping.
- Click the Browse button in the left pane and select CallActivity.
The left pane will show the structure of the CallActivity, based on the BPMN 2.0 metamodel.
The simplest way to create a useful column mapping is to select the CallActivity line in the left pane and then click the > button in the Column Query pane. At that point, you will see a message in the Add Columns dialog window asking if you want to create columns for the first-level, simple attributes (see Figure 27).
- Click Yes.
Figure 27. Automatically creating columns
Several column queries are automatically added to the right side, including the ID, Name, and Called Element fields. Only singleton attributes, which are owned by CallActivity, are included. It is possible to create a column mapping to elements of owned collections, as well. As discussed earlier, a column query of
documentation/@text refers to the first element in the documentations collection. Notice that, currently, it is not possible to create column queries referring to referenced (rather than owned) attributes or collections.
- Create a new column, named
documentation/@textas the query and String as the type.
- Click Finish.
- Next, in the Edit Data Set dialog window, the focus is on the Output Columns page.
- To confirm that the row query and column mappings are as expected, select the Preview Results page.
The resulting table will show the results of this data set on the instance models associated with the data source. For the instance model that you have been using, the preview looks like Figure 28.
Figure 28. Preview results of the new data set
Alt text =
Creating a simple report
Similar to the way that the results preview is shown in table form, it is possible to create a very basic report in table format.
To accomplish this, simply drag any data set, such as the new data set, onto the blank report layout.
A table will be created, where the first row contains the names of the columns, and subsequent rows contain information about all of the call activities in the instance models associated with the data source. See Figure 29 for an example.
Figure 29. Simple table report
Obviously, this report is very basic and not particularly useful. You can use the relevant citations in the Resources section to learn more about how to create and customize BIRT reports in general.
Starting with a Blank BPMN Model Report
Although it is possible to create a new, empty report and then create a BPMN data source and relevant BPMN data sets, it is easier to simply make a copy of the Blank BPMN Model Report. This report has no layout, but it contains a BPMN data source and a collection of potentially useful BPMN data sets. In fact, every data set used in the creation of the BPMN Model Diagram Report and BPMN Model Metrics Report is included.
Creating your own Diagram data set
A Diagram data set is included in the Blank BPMN Model Report; however, it might be desirable to create a new data set to retrieve the diagram of a model. An XPath function has been provided to permit the extraction of the diagram from an instance model.
- To create a diagram data set, create a new data set and navigate to the Row Mapping page.
- Using the Browse button, select the GMF metamodel from the drop-down menu.
- In the Expression pane, type this query:
- To select the type, select Diagram > View from the GMF metamodel in the left pane.
- Click the > button by the Type field. The type will be
- Click the Next button.
- On the Column Mapping page, select notation:Diagram in the Browse drop-down menu.
- Select image:Blob from the left pane and click the > button in the Column Query pane. A column query with the name image, query
getDiagramImage(.),and type Blob is created.
- Click Finish.
- To confirm that the row query and column mapping are correct, navigate to the Preview Results page of the Edit Data Set dialog.
You will not see an actual diagram, but rather a hexadecimal representation of the diagram. See Figure 30 for an example.
Figure 30. Preview results of diagram data set
Adding a diagram to the layout
Unlike the previous example, simply dragging this new diagram data set onto the report layout will not result in a diagram being displayed. The hexadecimal representation of the diagram will be shown instead.
- To show the diagram, right-click on the layout and select Insert > Image from the menu.
- When the Edit Image Item dialog window appears, choose the Dynamic image option.
- Click the Select Image Data button, which opens the Select Data Binding dialog window.
You must bind this new image to your new Diagram data set.
- Ensure that the Data Set option is selected, and choose the new diagram data set from the drop-down menu.
The table is now populated with the image information from that data set.
- Make sure to select the image row, as shown in Figure 31.
Figure 31. Binding an image to the diagram data set
- Click OK. The Edit Image Item dialog window now shows a dynamic image expression, linked to your diagram data set. See the example that follows.
Figure 32. Image is bound to Diagram data set
- Click Insert. The layout now shows a small square with a red x (Figure 33).
Figure 33. Diagram in the layout view
This icon represents the location of the diagram in the layout view.
- To see the diagram itself, click the Preview tab.
The diagram will be shown in context with the rest of the report.
By following these steps, you can create simple BIRT reports about your BPMN instance models. You can also customize existing reports to suit your needs, as well as create new reports from scratch.
- Read the official specification of the Business Process Modeling Notation.
- Find information about the Eclipse BIRT project on the BIRT Project page.
- Browse the Eclipse BIRT Project’s list of useful documentation, including books, on their documentation page.
- Learn more about:
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management. You can find product manuals, installation guides, and other documentation in the IBM Rational Online Documentation Center.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
- Download trial versions of IBM Rational software.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
- Join the discussion in the Rational Development Tools forum.
- Check out developerWorks blogs and get involved in the developerWorks community