Contents


Impact analysis in WebSphere Message Broker V7

Comments

What is impact analysis?

Impact analysis is the identification of development artifacts that may be affected by changes to other artifacts. Links between artifacts may be far from obvious, so an automated feature that identifies relationships between artifacts can save large amounts of time and trouble during the development process.

For example, in an IBM® WebSphere® Message Broker (hereafter called Message Broker) environment, if you have a message map using a message named input, then there is a relationship between the message map and input. If the name input is changed to request, then the message that the message map refers to will no longer be found, causing a validation error in the message map because there is a dependent relationship between the message map and the message input.

If you are an application developer preparing to make a change to a development artifact, impact analysis can tell you what actions need to be performed, in addition to the initial change, to counteract and prevent potential validation errors in dependent artifacts. Message Broker change operations that support impact analysis include:

  • Renaming an artifact or a construct within an artifact
  • Moving an artifact or a construct within an artifact to another location

Expanding on the previous example, if you are working with a message map that uses the message input, and you want to rename the message to request, the impact analysis feature will report that renaming input to request requires that the message map be updated.

Impact analysis only reports what artifacts may be affected by a change -- it does not perform the changes. Also, impact analysis reports only those artifacts that are directly dependent on the constructs that may be changing. For example, if you have a message flow using the message map, renaming input will not list the message flow as a potential impact because it is an indirect relationship.

Impact analysis can identify dependent relationships within the workspace, because relationship information is cataloged within an indexing system. In order to populate this catalog, a process called indexing is performed on artifacts in the workspace.

Description of application

To illustrate the advantages of using impact analysis in Message Broker, an example is provided in a zip file that you can download at the bottom of the article. In the example, two banking operations, deposit and withdrawal, have been modeled. These operations can be initiated by sending a SOAP message to the message flow. The format of the SOAP messages is defined by the WSDL shown in Figure 1:

Figure 1. WSDL defining the format of the operation SOAP messages
WSDL defining the format of the operation SOAP messages
WSDL defining the format of the operation SOAP messages

When either the deposit or withdrawal operation is called, Message Broker transforms the input data into a message format that is understandable by the bank's back-end system. In this example, for the purpose of simplicity, a subflow emulates the connection to the bank's back-end system.

The response from the bank's back end system is returned and a SOAP message is constructed, using ESQL code, to produce a reply message for the operation. Figure 2 shows an overview of the message flow, BankOperationFlow.msgflow, which implements the scenario just described:

Figure 2. Message flow depicting example scenario
Message flow depicting example scenario
Message flow depicting example scenario

The WSDL described in Figure 1 is imported into the message set, and the MXSD definition ops.mxsd, which contains the messages transferIn and transferOut, is created from the import. transferIn is the input message when a deposit is performed, while transferOut is the message used when a withdrawal is requested.

The emulated back-end system takes the message changeRequest as input and returns updateConfirmation. These are defined in the file BackendOperationMessages.mxsd.

Depending on the operation that is invoked, the message transferIn or transferOut must be mapped to the message changeRequest in order to persist the change to the storage system. An example of that mapping is shown in Figure 3:

Figure 3. Example of mapping performed to create message format suitable for the backend system
Example of mapping performed to create message format suitable for the backend system
Example of mapping performed to create message format suitable for the backend system

The mapping from the transferOut message is similar. Since the focus of this article is not on mapping, a straightforward mapping example is used for the purposes of illustration.

Once the message flow has updated the information on the back-end by calling the emulation subflow, the main flow passes control to a Compute node, which invokes a module within ESQL to determine whether the change was successful.

The second function of the ESQL is to construct the SOAP reply message by copying the fields from the updateConfirmation message. Here is the ESQL code:

Figure 4. ESQL code snippet that constructs the SOAP reply message
 ESQL code snippet that constructs the SOAP reply message
ESQL code snippet that constructs the SOAP reply message

While this application does not have any validation errors, it has been built to mirror the state of an application under development; that is, several locations for artifacts do not follow best practices and some constructs are not clearly named. This article shows you how to use impact analysis to help you modify artifacts and constructs while maintaining the final valid state of the application.

Prerequisites for impact analysis

To function correctly, impact analysis requires that an index of the relationships between artifacts in the development workspace is built and maintained. Without this an index, impact analysis cannot function, because it cannot identify the relationships among the artifacts. Similarly, it cannot identify newly-created dependencies, nor report dependencies that no longer exist following modifications to artifacts. To keep the index current, Message Broker indexes an artifact whenever the artifact is built, provided that indexing is enabled.

In new workspaces, or workspaces migrated from previous versions of Message Broker, indexing is disabled by default, and indexing will not occur when artifacts are built. When working from a new or migrated workspace, you must enable indexing before using impact analysis. Under the Window menu of the Development Toolkit, go to the Preferences dialog and select Broker Development => Impact Analysis:

Figure 5. Preferences page that controls whether indexing occurs in Message Broker
Preferences page that controls whether indexing occurs in Message Broker
Preferences page that controls whether indexing occurs in Message Broker

This Impact Analysis sub-menu lists the changes that impact analysis can analyze for the selected item. If the item does not support impact analysis, then this sub-menu will not appear.

Figure 6. Impact Analysis sub-menu
Impact Analysis sub-menu
Impact Analysis sub-menu

The second way to invoke impact analysis is to select a construct within an editor and invoke the context-sensitive Impact Analysis menu. As with the first option, it appears only on those constructs that support impact analysis. In Message Broker V7.0, impact analysis support from within editors is available only in the Message Definition Editor.

An example of invoking Impact Analysis is shown in Figure 7 below. The reference constructs such as element reference and group reference cannot be referenced by other artifacts, and therefore the Impact Analysis sub-menu does not appear on the reference artifacts. To illustrate this concept, look at the element reference tns:id in message transferIn shown in Figure 7. It is not a global element definition but rather an element reference to the global element id (which is listed under Elements and Attributes). If you right-click on tns:id under transferIn, the context menu will not have the Impact Analysis sub-menu. However, if you right-click on id under Elements and Attributes, you will see the impact analysis sub-menu within the context menu:

Figure 7. Invoking impact analysis through the message definition editor
Invoking impact analysis through the message definition editor
Invoking impact analysis through the message definition editor

You can invoke impact analysis on many different types of objects within the application sample. This article focuses on two rename changes and one move change in order to provide an overview of the Message Broker V7.0 functionality. Later in this article, there is a list of other changes that you can make in order to learn more about impact analysis.

Performing Impact Analysis -- Rename

This section shows you how to rename an artifact, which you might do for a number of reasons, such as the current name not being descriptive of the function being performed. With the transferIn message, the name is not descriptive of the actual operation (deposit), so you might want to rename it to a more logical and intuitive name. Another reason for renaming might be that the external caller of a Web service may have requested a different format for the input SOAP message, which would require changing the transferIn name.

To check what other artifacts and constructs might be affected by renaming transferIn, you can do impact analysis on the transferIn message:

  1. Open the message definition ops.mxsd within the Message Definition Editor.
  2. Right-click on the definition of transferIn under the Messages section in the Overview tab.
  3. Select Rename on the Impact Analysis sub-menu.

Once these actions have been performed, a dialog opens asking for the new name of the construct, as shown in Figure 8 below. In this case, enter the name depositRequest and select Analyze Impact:

Figure 8. Impact analysis -- Rename Artifact dialog asking for new name of construct
Impact analysis -- Rename Artifact dialog asking for new name of construct
Impact analysis -- Rename Artifact dialog asking for new name of construct

Figure 9 below shows the modal dialog that appears with the results of the analysis. There are three tables within this window, denoted by the colored numbers 1, 2, and 3, and each one is described below:

Figure 9. Results from impact analysis of a rename
Results from impact analysis of a rename
Results from impact analysis of a rename
  1. Table 1 lists the operation that these analysis results pertain to.
  2. Table 2 lists the initial changes (also called primary changes), which are the actions that must be executed in order to perform the operations denoted in the first table. Each row in the initial changes table describes a single action, including the location of the file upon which the change must be performed, and a description of what must be done. In this example, the operation is the rename of transferIn to depositRequest and as such the action that must be performed is to change the message definition name from transferIn to depositRequest. Neither of the first two tables provide any information about items that will be affected by this change (which is of most interest when performing impact analysis).
  3. Table 3 lists potential impacts (also called secondary impacts). The artifacts in this table depend on the construct that is undergoing a change. Like Table 2, each row in Table 3 describes a single action that should be performed, in addition to the primary change, to prevent validation errors. Likewise, information in each row identifies exactly which file must be updated and what needs to be updated in that file. Scroll the table to the right to show more detailed instructions for each action. For example, the change to the message map contains the details:
Renaming message '{http://ImpactAnalysis/Bank}transferIn' will impact file 
'/BankMF/impactanalysis/bank/BankOperationsFlow_Convert_Withdrawal.msgmap', in message
map 'BankOperationsFlow_Convert_Withdrawal', at location '$source, accountID, amount

In some instances, not all secondary impacts are reported. The link by numeral 4 in Figure 9 links to a description in the information center of some of the limitations.

Important: WebSphere Message Broker impact analysis does not actually perform any changes. Use the impact analysis report as a guideline to determine what needs to be changed.

Generating reports from impact analysis results

If you click the Copy Analysis To Clipboard button at the bottom of the Impact Analysis dialog in Figure 9 above, the entire report will be copied to the clipboard, from where you can paste it into . an external application to use as a checklist to perform the changes. If you paste the report into an application that supports tables, such as a word processing or spreadsheet application, the output will be in table format, as shown in Figure 10:

Figure 10. Impact analysis report copied into a spreadsheet
Impact analysis report copied into a spreadsheet
Impact analysis report copied into a spreadsheet

If you paste the report into a generic text editor, the table formatting may not be present.

Limitations of impact analysis

The impact analysis report is a very useful for identifying changes that need to be made. Try performing the changes to the message definition name (initial change) and the global element (in this case, the global element is automatically renamed when the message is renamed) now. Notice that after you make these two changes, there is an error in the message set, as shown in Figure 11.

Figure 11. Workspace after impact analysis changes are performed
Workspace after impact analysis changes are performed
Workspace after impact analysis changes are performed

There is an error in the deployable WSDLs due to the changes that you just made, because the element transferIn was renamed to depositRequest (recall that impact analysis was performed on the message and not the element).

This example illustrates one limitation with impact analysis -- it only reports artifacts that are directly dependent on the construct being changed. In this case, the WSDL depends on the element transferIn, which in turn depends on the renamed message depositRequest. To prevent this scenario from occurring, perform a second impact analysis before renaming the element to detect the secondary impacts that will occur, as shown in Figure 12:

Figure 12. WSDL listed as a secondary impact
WSDL listed as a secondary impact
WSDL listed as a secondary impact

When the element transferIn is renamed, the Deployable WSDL BankOperations.wsdl is listed as a secondary impact, as expected. The message definition transferIn is also listed as a secondary impact, but this is because the name of the message definition and element must be identical.

Performing impact analysis -- Move

Moving artifacts and constructs is another change that can benefit from impact analysis. Performing an impact analysis on a move is similar to doing it on a rename. The first step is to highlight the artifacts or constructs to be moved and then invoke impact analysis. One difference for the move operation is that multiple artifacts or constructs (but not both) can be selected, as shown in Figure 13:

Figure 13. Invoking impact analysis on a move operation for multiple artifacts
Invoking impact analysis on a move operation for multiple artifacts
Invoking impact analysis on a move operation for multiple artifacts

In this example, the message map BankOperationsFlow_Convert_Withdrawal.msgmap and the ESQL file BankOperationsFlow.esql belong to a broker schema named testing. These files have been tested and they need to be moved to the broker schema impactanalysis.bank. But before moving them, you need to determine whether the move will impact other artifacts.

The Impact Analysis -- Move Artifact modal dialog is shown in Figure 14 below. It displays the artifacts or constructs that will be analyzed and lets you specify the target location and then click Analyze Impact.

Figure 14. Impact Analysis -- Move Artifact dialog
Impact Analysis -- Move Artifact dialog
Impact Analysis -- Move Artifact dialog

The next window shows the analysis based on how the artifacts to be moved were specified on the previous page. The interface is similar to the one for the rename operation, but the contents are different because of the different scenario. Table 1 has multiple operations because multiple files were selected. Table 2 lists the primary changes, which are several files and constructs that will be moved. Table 3 lists the secondary impacts:

Figure 15. Impact analysis results when moving several artifacts
Impact analysis results when moving several artifacts
Impact analysis results when moving several artifacts

In this example, there are four secondary impacts. Two impacts are within the ESQL file itself as there are references to schema-scope constants that are to be moved. When an ESQL file is moved, all constructs within the ESQL file are also moved.

The more important secondary impacts concern the message flow BankOperationFlow.msgflow. The message flow uses both the message map and ESQL file to transform message formats, and therefore if the functionality has moved to a new location, the message flow must know where it is. After the files have been moved, the message flow must also be updated in order for the application to validate correctly.

Further examples of impact analysis

The examples above show how you can use impact analysis in the Message Broker Toolkit to identify and resolve potential errors within the workspace when you make structural changes to artifacts or constructs. The examples in this article showed only a handful of artifacts that can be changed. For a full list of the supported constructs for impact analysis, see the Appendix below.

To understand impact analysis further, use the attached sample to make changes to a variety of constructs and observe the effects. Table 1 lists impact analysis examples within the sample application and what the secondary impacts should be:

Table 1. List of other impact analysis examples within the sample application
ArtifactConstructSecondary Impacts
BankOperations.wsdlWSDL import in BankOperationsBinding.wsdl needs to be updated.
CommonTypes.mxsdsuccessType
  • Derived type in BackendOperationMessages.mxsd will need to update its base type.
  • Element using successType in ops.mxsd will need to be updated.
BackendOperationMessages.mxsdupdateConfirmation
  • ESQL path in BankOperationsFlow.esql
  • Corresponding message definition name or global element (depending which you originally selected)
BackendOperationMessages.mxsdtransactionDetailscomplex type within BackendOperationMessages.mxsd
ops.mxsdSchema directive in BankOperations.wsdl
ops.mxsdtransferInTypetype of element transferIn
ops.mxsdsuccess (global element)
  • Two response types in BankOperations.wsdl
  • ESQL path in BankOperationsFlow.esql
  • Message definition name
ops.mxsdid
  • Message map BankOperationsFlow_ Convert_Deposit.msgmap
  • Message map BankOperationsFlow_ Convert_Withdrawal.msgmap
  • Two element references within ops.mxsd
BankOperationsFlow.esqlDB_SYSTEM_IDModule in BankOperationsFlow.esql
BankOperationsFlow.esqlnsModule in BankOperationsFlow.esql
BankOperationsFlow.esqlBankOperationsFlow_ Convert_to_SOAPMessage flow BankOperationsFlow.msgflow
BankOperationsFlow_ Convert_Deposit.msgflowMessage flow BankOperationsFlow.msgflow
BankOperationsFlow_ Convert_Withdrawal.msgflowMessage flow BankOperationsFlow.msgflow
Update.msgflowMessage flow BankOperationsFlow.msgflow

Conclusion

Artifacts in Message Broker frequently have dependent relationships between them. When one artifact is renamed or moved, other artifacts that are dependent on its original name or location will report validation errors. Fixing these errors is time-consuming, and therefore using the Message Broker V7.0 impact analysis feature to understand the scope of changes to dependent artifacts before changing an artifact can save you lots of time and work. The impact analysis feature can generate an external report that describes the additional actions that need to be performed on secondary artifacts and serve as a record of the changes that need to be made.

Appendix. Supported and unsupported artifacts and constructs

Table 2 lists those artifacts and constructs that support impact analysis in Message Broker V7.0 (in other words, these are the artifacts and constructs that can be primary changes), and also shows where impact analysis can be invoked for each type of artifact:

Table 2. Artifacts and constructs upon which impact analysis can be performed and where impact analysis can be initiated
ChangeEntry point
Artifact/ConstructRenameMoveBroker Development ViewMessage Definition Editor
Message definition fileYesNoYesNo
Global XSD Constructs
  • messages
  • elements
  • types
  • attribute groups
  • groups
  • attributes
YesNoYesYes
Local XSD Constructs
  • elements
  • attributes
YesNoNoYes
Deployable WSDLYesNoYesNo
Message flowsYesYesYesNo
Message mapsYesYesYesNo
ESQL filesNoYesYesNo
ESQL constructs
  • Modules
  • Schema-scope routines
  • Schema-scope constants
YesYesYesNo

Conversely, Table 3 lists the artifacts and constructs that can have dependent relationships upon the items in Table 2. These items in Table 3 can be reported as secondary impacts:

Table 3. List of artifacts and constructs that may be reported as a secondary impact.
Artifact/Construct
Message definition file
Global XSD Constructs
  • schema directives
  • messages
  • elements
  • types
  • attribute groups
  • groups
  • attributes
Local XSD Constructs
  • elements
  • attributes
Deployable WSDL
Deployable WSDL constructs
  • WSDL parts
  • WSDL imports schema directives
Message flows and subflows
Message flow constructs
  • Node properties referencing messages
  • XPath within node properties referencing message sets
Message maps and submaps
ESQL files
ESQL constructs
  • Modules
  • Schema-scope routines
  • Schema-scope constants
  • ESQL paths referencing message sets

Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=498772
ArticleTitle=Impact analysis in WebSphere Message Broker V7
publish-date=06302010