User-Defined Rules

The Migration Toolkit for Application Binaries allows for user-defined analysis rules to detect scenarios specific to your application migration. The user-defined rules are written in XML files. The rule files are grouped together in an XML list file and then specified using the --userRuleLocation parameter. The --userRuleLocation parameter is an absolute or relative path to a directory containing rule list XML files.

The Migration Toolkit for Application Binaries allows for user-defined analysis rules to be the only rules run by forgoing any pre-written rules inside the tool. To do this use the --userRulesOnly parameter in the command. This parameter must be used with --userRuleLocation.

Each XML rule must start with a <rule> element with an id attribute and a description attribute. The id must be unique amongst all the rules. It is recommended that the rule id begin with userDefined_. If the rule id does not begin with userDefined_, the binary scanner will add the prefix to the id to avoid conflicts with built-in rules. The <rule> element must contain exactly one child element. If the rule needs to combine multiple match criteria, then the <and> and <or> elements must be used. It is important to note that the logic used when combining multiple match criteria is consistent with the name of each of these elements. With the <or> element if any of the nested rules are flagged, then the overall rule is flagged. With the <and> element all of the nested rules must be flagged for the overall rule to flag. Rules can be defined with multple level of nested <and> and <or> elements. The rule schema must be included with the <rule> element:

xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule binary-scanner-rule_1_0.xsd"

For example the following rule will flag an application that contains the javax.ws.rs.core package and either the javax.ws.rs.ext package or the application/json string literal. Any results for the string literal will not be included in the results list of the report and the rule will only be flagged once per archive. 


<rule xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule binary-scanner-rule_1_0.xsd" id="userDefined_MyExampleRule" description="This is my example rule">
    <and>
        <detectPackage names="javax.ws.rs.core" flagOnce="true"/>
        <or flagOnce="true">
            <detectPackage names="javax.ws.rs.ext"/>
            <detectStringLiteral hideResult="true">
                <literal value="application/json"/>
            </detectStringLiteral>
        </or>
    </and>
</rule>

The rule types supported by the Migration Toolkit for Application Binaries are:

Each user-defined XML rule can have an HTML help file written alongside to describe the issue being flagged. These HTML help files have certain requirements for our report writer to process correctly:

  • All viewable content must contain a <p> inside <div> within <body>
  • The beginning of the content is indexed at the first <p> and the end is indexed at the last <div> within the <body>
  • The header is at the top of the <div> within <span class="SubHeader">

            <body><div>
            <span class="SubHeader">Rule Name</span>
            <p>Information about</p>
            <p>
            The rule can be written
            </p>
            <ul>
                <li>here</li>
                <li>here</li>
                <li>and here</li>
            </ul>
            </div></body>

The rules are grouped in lists by category. In the lists more information for the rule can also be provided, including the path to HTML help to include in the report, severity, and development cost. The rule lists must start with a <rules> element. The <rules> element should have a mainCategory and can have a secondaryCategory specified describing the category of rules that are contained in the list. These categories are used for grouping the rules in the analysis report. The <rules> element can have one to many child <rule> elements that specify and provide additional information about the rule XML files. The <rule> elements can have the following attributes:

  • fileName - A string attribute defining the relative or absolute path to the XML file containing the definition for the rule. This attribute is required.
  • help - A string attribute defining the relative or absolute path to an HTML file containing rule help to include in the report when the rule is flagged. The content in the HTML file must be contained within a <body> element. This attribute is optional.
  • severity - An enumeration that defines the severity of the rule. The supported values are: severe, warning, and info. This attribute is optional.
  • devCost - A float value defining the base development cost, in days, that it will take to resolve the migration scenario flagged by this rule. This is a one-time cost to fix a rule. This information is available in the JSON reports and in Transformation Advisor. This value is used with the instanceCost to calculate the developement cost in Transformation Advisor for this rule. This attribute is optional, and the default is 0.
  • instanceCost - A float value defining the development cost, in days, that it will take to resolve each instance of this rule being detected. This information is available in the JSON reports and in Transformation Advisor. This value is used with the devCost to calculate the developement cost in Transformation Advisor for this rule. This attribute is optional, and the default is 0.
  • complexity - An eumeration defining the complexity associated with the migration of an application that flags this rule. The supported values are simple, moderate, and complex. This information is available in the JSON reports and in Transformation Advisor. This attribute is optional.
  • recipes - A list of recipes provided in the OpenRewrite repository associated with the migration of an application that flags this rule. When multiple values are added to the list the first recipe is chosen. This attribute is optional.

The rule list schema must be included with the <rules> element:

xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list binary-scanner-rule-list_1_0.xsd"

For example: 


<rules xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list binary-scanner-rule-list_1_0.xsd" mainCategory="Primary rule category" secondaryCategory="Secondary rule category">
    <rule fileName="detectDeprecatedMethod.xml" help="/rulehelp/detectFindMethod.html" severity="warning" devCost="0.5" instanceCost="0.1"/>
    <rule fileName="detectOldLibrary.xml" help="/rulehelp/detectOldLibrary.html" severity="severe" devCost="5" complexity="complex" />
</rules>

For ease of developing rules, the schema files for both the rule XML and rule list XML files are placed in the wamt/user-rules directory. Update the schema file location in the schemaLocation attribute to specify the file path to get validation when writing rules if supported by your Integrated Development Environment (IDE). This is not required, but can make it easier to catch errors when writing rules.

For example, if the rule files are located within a directory in the wamt directory: 

xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list ../user-rules/binary-scanner-rule-list_1_0.xsd"