Creating Custom Rules with XPath

CodeScan allows you to create custom rules using XPath. You can use these rules to trigger violations based on any special requirements you may have.

Note:

1. The custom XPath Visualforce rule template uses XPath version 2 whereas the custom XPath Apex rule template uses XPath version 1.

2. This needs to be changed in the design as the rules are being developed or could introduce bugs.

Before you begin

• You will need an excellent working knowledge of XPath to get this operational.

• Download the Apex-Custom Rule Designer .

Installing the Apex-Custom Rule Designer

Run the following command to install the downloaded Apex-Custom Rule Designer:

java -jar <jar-file-name>.jar

Apex

Here are some examples of XPath queries for Apex.

Naming:

• XPath queries can be used to catch unwanted trends or enforce standards in the naming of your classes, methods, and variables.

• This query will catch any class names that do not start with PREFIX_

//ClassOrInterfaceDeclaration
[
  not(starts-with(@Image, 'PREFIX_'))
]

This example would catch the first class here:

class NewClass{}
class PREFIX_NewClass{}

starts-with can also be replaced with:

• ends-with - This checks for a string at the end of the @image name.

• matches - This uses the regular expression in place of the string to check for patterns in the @image name.

Note:

When using a regular expression with escapes ( \ character) in XPath, you will need to double escape them when adding them in the UI due to the way our rule engine parses them.

eg. \. will become \\.

Visualforce and Aura Lightning

You can also use this technique for VisualForce (in the Apex-Custom Rule designer, select the VisualForce language and use XPath 2.0 instead of XPath 1.0).

Naming:

XPath queries can be used to catch unwanted trends or enforce standards in the naming of your pages.

This query will catch any page names that do not start with PREFIX_

//Document [@Filename[not(starts-with(.,'PREFIX_'))]]

This example would catch the first Filename here, but ignore the second:

NewPage.page
PREFIX_NewPage.page

starts-with can also be replaced with:

• ends-with - This checks for a string at the end of the @image name.

• matches - This uses the regular expression in place of the string to check for patterns in the @image name.

Other Salesforce metadata

Most other metadata types come out of Salesforce in XML format. To scan these types, you can add any metadata you want to the list of file suffixes as seen in the Enable CodeScan Cloud Metadata Rules article.

XPath expressions for Salesforce metadata should start with double-slashes (“//”). For example-

//ValidationRule

Point to Note:

In CodeScan Designer, verify the XPath expressions. Using an XPath expression generated by any other online tool may not work because the XPath expression is dependent on how the AST is generated, which varies per tool.

If you want to create a rule for a new metadata type, spend time looking at the XML to determine where your fields, rules, decisions, or subtasks are, and then look into how to validate them. For example, if you want to limit a flow to 20 decision points, the XPath would look something like this:

//Flow[
 count(./decisions)>20
]

The type of component being visualized is flow. Decisions exist within that flow; they are a direct child of the flow within the XML. Finally, the count () method can determine if there are too many flows.

Adding your Custom Rule

1. Login to your CodeScan Cloud account or SonarQube™

2. Click on the Rules menu

3. In the Filters pane, search for Xpath rule template.

   
4. Select the XPath rule template of the language of your choice.

5. Under Custom Rules click on Create.

   
6. Assign the values to the Name, key, Type, Severity, Status, Description and Message fields.

7. Insert the Xpath created in the field provided and click on Create.

   

Now you can add it to your Quality Profile as you would any built in rule. Please refer to our guide for customizing Quality Profiles for these steps.