Manage change in mainframe applications with IBM Rational Asset Analyzer: Part 3. Customize and aggregate impact analysis results

Software maintenance can require up to 70% of IT's budget, so managing change to shorten the maintenance cycle, reduce risk, and ensure quality is critical in today's economic climate. This series of three articles explains how you can use IBM® Rational® Asset Analyzer to achieve those goals, specifically for mainframe-based applications. Part 3 describes how to customize the impact analysis results and aggregate those results, using the Custom Query capability, and then how to create a “bill of materials” based on those results and share it as a spreadsheet.


Amy M. Silberbauer (, Executive IT Specialist, IBM

Amy is currently the Rational Industry Solutions architect lead and a member of the Unleash the Labs team. She specializes in enterprise modernization, service-oriented architecture (SOA), and business process management. She has been with IBM for 25 years, with 22 years in development and six as lead architect of the Rational Asset Analyzer team.

08 November 2011

This is the final part in this series of articles.

  • Part 1 described a typical software maintenance lifecycle and walked through the process of identifying assets that are part of a change request, based on a set of best practices from our experience with customers.
  • Part 2 built on this scenario by offering best practices for performing an IBM® Rational® Asset Analyzer Impact Analysis using three different seeds as starting points and demonstrating how analysis results vary depending upon the seeds chosen. Observations about those results are included to educate you on how to approach impact analysis, depending upon your specific change scenario.
  • Part 3 continues with the lifecycle discussion, describing how you can use some customization capabilities available in Rational Asset Analyzer and Rational Asset Analyzer for System z to aggregate the results of impact analysis and identify owners for assets that are part of a change request. This enables you to move from analysis of changes into the implementation of those changes as part of the overall development lifecycle.

Please refer back to Parts 1 and 2 to refresh your memory on common terminology and the scenario in general.

Annotating assets

Rational Asset Analyzer has a capability enabling you to annotate various assets using free-form text as well as categorize annotations to provide you with a means of grouping assets in ways that are not provided out-of-the-box. The product ships with three categorizations: General, Comments, and Business Function. You can use these, change them, and add your own.

Annotations can also be configured for display on asset summary pages, which can be useful in providing more information about assets through free-form annotations and customization of page content. Finally, annotations can be used for queries. In the next section, we will combine annotations with a Custom Query you create to aggregate the results of analysis performed in Parts 2 and 3 and identify ownership for implementation of changes.

Because annotations are free-form text, you can extend your use of annotations to integrate into your software lifecycle. For example, by providing URLs that link to requirements, test cases, or team dashboards, you can easily share analysis information within the collaborative development environment.

Annotations are generally added through the user interface as a manual process. Because annotations are persisted in the metadata repository, you could automate the population of annotations or work with IBM software services to help.

Creating a customized annotation type

The management of annotation types is a manual configuration process in Rational Asset Analyzer, though quite simple. You must know where your Rational Asset Analyzer server is installed in order to locate the configuration files requiring updates, and you must have the authority to make those updates and recycle the Rational Asset Analyzer server so the updates are reflected in the product.

Once you have verified the Rational Asset Analyzer installation path and have the proper authorizations, create a customized annotation type Owner by performing the following steps:

  1. Locate the RAAInstall/config/wsaa-annotation-types.xml file, and open it for editing.
  2. Add a new <AnnotationType> for Owner as shown here (and in Figure 1):
     <AnnotationType id='154' name='Owner' label='Owner' />

    • id is the next unique, sequential numeric identifier for this new annotation text type
    • name is the annotation text type name as it is known to the internal system
    • label is the annotation text type label that is displayed on the user interface
    Note that the label can come from a properties file, through use of the $L{label} syntax, or it can come from a configuration file via use of the $C{label} syntax.
Figure 1. Create new annotation text type
Shows how to add new annotation text type
  1. Save your changes.
  2. Enable Rational Asset Analyzer to display this new annotation text type on a Program summary page through a configuration in the RAAInstall\config\Common.cfg file. Locate this file and open it for editing.
  3. Scroll to the [AnnotationText] section of the file, and add values as shown here (and in Figure 2):
     [AnnotationText] displayTypes=154 displayColNames = Owner DisplayCompTypes = 1

    • displayTypes is the set of annotation text type IDs to display (as specified in Step 1)
    • displayColNames is the set of column names for each text type displayed on the summary page
    • displayCompTypes is the component type IDs for asset type summary pages (in this case 1 = Program)
Figure 2. Configure display of annotation types
screen output of code
  1. Save your changes, restart the Rational Asset Analyzer server (IBM® WebSphere® Application Server), and then refresh Rational Asset Analyzer in the browser.
  2. Go to the Explore > MVS assets count page, and click on the total count for Programs. The Program summary page is displayed with the new Owner column that contains the annotation text for this new annotation text type. It is empty because you have not specified any text yet.
Figure 3. Owner annotation displayed on Program Summary page
Shows display of new text type on summary page

Larger view of Figure 3.

  1. In the Actions column for the first program, ASSIALS, click the annotate hyperlink to get the Manage Annotation Text wizard. Enter text for the new annotation text type, Owner, and click the Submit button.
Figure 4. Owner annotation
Shows how to specify new annotation text
  1. Close the wizard by clicking the Close button.
  2. Refresh the Program Summary page to see your new text in the Owner column for Program ASSIALS.
Figure 5. Program summary with Owner specified
Shows new annotation text is now displayed on page
  1. Repeat this for the QAD03 program. Now you can view impact analysis results created in an earlier exercise to view the Owner identified for affected (impacted) program assets.
  2. Go to the Impact Analysis summary page by selecting Impact Analysis > View mine from the Rational Asset Analyzer menu.

The summary page shows the three analyses created in earlier exercises (see Figure 6).

Figure 6. Impact Analysis summary page
Screen capture of the impact analysis summary page

Larger view of Figure 6.

  1. Select the All PART_NO Data Elements (Char 4)name hyperlink to go to the Impact Analysis results overview page.
  2. Scroll down to see the Overview results, and click the Details tab (Figure 7) to go to the results details page.
Figure 7. All PART_NO Data Elements (Char 4) Results Overview
Shows overview of analysis results

Larger view of Figure 7.

  1. On the results details page, scroll down until you see the table with Programs. Notice that the new Owner column is now displayed.
Figure 8. Impact analysis results - programs with owners
Shows details of analysis results with owner text

Larger view of Figure 8.

Now you are able to show owners associated with programs that may require changes as part of a change request.

Aggregating results of impact analysis on multiple seeds

In previous exercises, you created three impact analyses, using different seeds for that analysis. In this section, we explore the use of the Custom Query capability to aggregate those results. Custom Query is not covered in detail in this article. To summarize, it is the ability in Rational Asset Analyzer to create queries against the metadata stored in the repository to customize results through additional pages or actions on pages in the browser.

This exercise relies on a naming scheme for your impact analyses that can be used in the query, such as like ‘%PART_NO%’. If you have been following the exercises to this point, you will have such a naming scheme in place.

  1. From the Rational Asset Analyzer home page, select Explore > Custom queries from the menu.
Figure 9. Go to Custom Queries summary page
Shows Custom queries selected on a drop-down menu

Larger view of Figure 9.

  1. Select Create a new custom query from the Actions drop-down menu.
Figure 10. Create a new custom query
Shows how to create a new custom query

Larger view of Figure 10.

  1. In the Custom Query wizard, enter the name All Programs impacted by change to Part Number, leave the Assign as action to a page check box unchecked, and click Next.
Figure 11. Specify a name for your query
Step 1 of custom query wizard, specify name
  1. In Step 2, enter the SQL query in Listing 1 in the field labeled SQL query (required): and click Next. You can simply copy and paste this directly into the wizard.
Listing 1. SQL query
select distinct as cmpntType,
    ci.cmpnt_type_id ,
    text.char_value as owner, 
    ci.related_id_1 from 
        ${tschema}.DMH_CHANGE_PROJECT cp ,
        ${tschema}.DMH_CHAR_PROPERTY text,
        ${tschema}.DMH_CHANGE_IMPACT ci ,
        ${tschema}.DMH_CMPNT_TYPE ctype ,
        ${tschema}.dmh_compile_unit cu where
   like ‘%PART_NO%’ and
            ci.cmpnt_type_id = 1 and
            cp.project_id = ci.project_id and
            ci.cmpnt_type_id = ctype.cmpnt_type_id and
            cu.comp_unit_id = ci.related_id_1 and
            text.related_id_1=cu.comp_unit_id and

This query takes advantage of using annotation text to identify program ownership established in the previous exercise

Figure 12. Enter the SQL query
Enter the SQL query
  1. Specify the columns to be displayed in the results when the query is executed.

You can also create a user-friendly label to be displayed by overwriting the default label.

  1. Click Next to continue:
Figure 13. Specify columns in the result set
Step 3 of custom query wizard, results columns
  1. Specify the columns to enable for searching, and then click Next to continue.
Figure 14. Identify default search column
Step 4 of custom query wizard, search columns
  1. Specify the columns to display by default when the query is executed (see Figure 15). This might be a subset of the available columns, but it could include all of them.
Figure 15. Identify default columns to view
Step 5 of custom query wizard, view columns
  1. Click Next to continue.
  2. Specify those columns that serve as hyperlinks to other pages in the Rational Asset Analyzer browser.
Figure 16. Identify columns with hyperlinks
Step 6 of custom query wizard, hyperlinks
  1. Click Next to continue.
  2. Specify the mechanism to create the hyperlinks. The wizard provides suggestions on how to do this through the Available $C variables and Available $P variables, as shown in Figure 17.
Figure 17. Specify hyperlink information for the URL field
Step 7 of custom query wizard, hyperlink details
  1. Click Next to continue.
  2. Specify the columns to use for sorting results when the query is executed.
Figure 18. Identify default sort columns
Step 8 of custom query wizard, sort columns
  1. Click Next to view a summary of your new custom query.
  2. Click Finish.
Figure 19. Complete the creation of your custom query
Step 9 of custom query wizard, summary
  1. After the Custom queries summary page is refreshed to show the new custom query, click the custom query name hyperlink to execute this new query.
Figure 20. View your new query in the summary page
New custom query is shown, click to execute

Larger view of Figure 20.

You have a new custom query displayed on the Custom queries summary page. To execute that query, click on the name hyperlink. For each program that has an owner annotated, you will see that program listed as part of the aggregated impact analysis results.

Figure 21. View all impacted programs and their owners
Query results show all impacted programs and owners

This is just one example of how to use a custom query to aggregate impact analysis results. Clearly, other results could be aggregated given the appropriate SQL. For example, you might want to also aggregate analysis results that include data elements, IBM® DB2® columns, DB2 tables, and files that must be included in a change "bill of materials" (BOM).

Creating a bill of materials (BOM) for change

Now that you understand how to create and aggregate a set of potentially impacted application artifacts using Rational Asset Analyzer, you might want to create a "bill of materials" (BOM) to identify those artifacts and create work items to track implementation and test activities. One easy way to do this uses the Microsoft Internet Explorer capability to Export to Microsoft Excel, thus creating spreadsheets containing the list of artifacts involved in a change request. This is not a core capability of Rational Asset Analyzer but is provided by Microsoft Internet Explorer and must be configured separately. (The release of Rational Asset Analyzer current at the time of publication requires Microsoft Internet Explorer; Mozilla Firefox will be supported in a later release.)

Assuming that you have the capability configured, you can create a BOM from the aggregated impact analysis results by performing these steps:

  1. From the query results showing Programs and Owners, right-click on the results table and select Export to Microsoft Excel.
Figure 22. Export results for Microsoft Excel spreadsheet
Shows how to create spreadsheet from results

An Excel spreadsheet is created by performing the same query used to produce the results shown previously in Figure 22, which is why you are prompted to enter a user ID and password for Rational Asset Analyzer. The resulting spreadsheet appears in Figure 23. Of course, you can alter the formatting.

Figure 23. Microsoft Excel spreadsheet with query results
Shows spreadsheet of impact analysis results

The BOM can be created by invoking this export against any table of information on any Rational Asset Analyzer browser page.


In this final part of this three-part series, you learned how to use some of the capabilities in Rational Asset Analyzer to customize the results of impact analysis and aggregate those results using the Custom Query capability. You also learned how to create a "bill of materials" based on those results, and how to share it as a spreadsheet.



Get products and technologies



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 Rational software on developerWorks

ArticleTitle=Manage change in mainframe applications with IBM Rational Asset Analyzer: Part 3. Customize and aggregate impact analysis results