This guide will show you how to import external rulesets into Kiuwan.
The Models Management in Kiuwan allows importing rule data from different sources.
If you work with PMD, Checkstyle, Findbugs or checKingQA, you can import your rule sets into Kiuwan, use them in your models and analyze your code with your own custom rules.
Open the hamburger menu next to the Rules title and select Import rulesets.
After clicking the "Import" button, a wizard will appear and will guide you through these steps:
Select a file to upload by clicking the "Upload" button:
You can upload one of these files:
|A PMD ruleset file||When analyzing code with PMD, a unique XML file defines the rules to consider, their metadata and their behavior. Upload a PMD ruleset XML to begin with the import. Rules are mapped to PMD rules. Note that referenced rules or rulesets that belong to external files will not be imported.|
|A Checkstyle configuration file||Checkstyle defines its style checks in an XML configuration file. This file only contains execution parameters. The import wizard will automatically look for the latest Checkstyle version metadata to extract the rule information needed in the import. Just upload a Checkstyle configuration XML to begin with the import. Rules are mapped to Checkstyle checks.|
|A Findbugs plugin JAR file||Findbugs needs various files to define its analysis behavior. These files are usually packed in a JAR file forming a Findbugs plugin. Upload a Findbugs plugin JAR to begin with the import. Rules are mapped to bug patterns.|
|A checKingQA ruleset file||Similarly to PMD, checKingQA uses a unique XML file to define the behavior of an analysis. Upload a checKingQA ruleset XML to begin with the import. Rules are mapped to checKingQA rules.|
If the selected file can be read by the import wizard, a summary of the read data will be shown: the engine detected, the number of categories identified and the rules read.
Although you will be able to import rulesets from newer versions, only rules compliant with the previous library versions can be applied when analyzing. See Kiuwan Local Analyzer to read more about this topic.
Special features when importing checKingQA rulesets
|When importing checKingQA rulesets you can reference product rules by using their standardized identifier. Rules with a name that starts with "OPT." will be identified as Kiuwan rules and will be searched in the current Kiuwan rules library. If found, they will not be installed in your account's library but identified to be added to the selected models in the next steps. This means that when working with checKingQA rulesets that reference Kiuwan's rules the only available operation is adding those rules to the specified models. You can mix product and user rules in the same ruleset. Product rules will not be imported, but user rules will.|
In the previous situation, note that only priority and repair difficulty will be imported. The rule classification under the characteristic criterion will be taken from the library defaults for each rule. This is the reason why you will not see the "Mapping" step when importing rulesets containing only product rules.
Kiuwan needs the imported rules to be classified under CQM categories. In this section, you can map the read categories to CQM values through a simple interface. It is possible that not all rules read are associated with a category. Here you can map these rules to a CQM value as well.
Note that it is not necessary to map all the read categories in the import wizard, but you won't be able to add to a model any rule that is not classified under CQM. You can always classify the rules later accessing the rule details from your library.
Once you have configured the CQM mapping, and if you have created at least one model, it is possible to add the imported rules to any of them:
A full CQM mapping is needed in the previous step to be able to add any rule to a model. You can also leave all the models unselected so the rules will only be imported in your account's library.
Once you have completed the import configuration, a preview page will be shown.
Here you can see the rules that will be added/modified to your library or models selected. Furthermore, each rule contains information about its CQM value, Priority and the Action to do (Install or Merge).
Once the import has finished, a results pop-up will be shown:
This pop-up shows the summary result of the import run.
First, you need to add the imported rules to an existing model (you can have done this with the import wizard already). You can mix any imported rule with the ones already in your library in the same model. To look for imported rules in your library you can select Engine in the filter Engine. This will help you identify which rules come from a PMD, Checkstyle or Findbugs import (checKingQA imported rules will be classified under "Kiuwan" engine value).
Once your model contains imported rules, you need to publish it, and then, you can run your analysis from the Kiuwan Local Analyzer.
You can analyze your code using your own rule implementations from PMD, Checkstyle, Findbugs or checKingQA as long as you add your custom libraries using the Kiuwan local analyzer extension mechanism. Read the Kiuwan local analyzer documentation on how to add custom libraries and how the extension mechanism works.
If your rules are based on the standard rules supplied in the supported versions of PMD, Checkstyle, Findbugs or checKingQA, the Kiuwan Local Analyzer will work out of the box.