This guide shows you how to import external rulesets into Kiuwan.
The Models Management feature in Kiuwan allows you to import rule data from various 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 custom rules.
Importing rulesets
In the Rules menu, select Import rulesets.
In the import rulesets wizard, you have the following options:
- Selecting a file: Upload a ruleset file.
- Mapping categories: Map user rules categories to CQM values.
- Adding rules to models: Add rules to users' models.
- Preview the import: Import preview.
- Import results
Selecting a file to import (Upload a ruleset file)
Select a file to upload by clicking Upload.
You can upload one of these files:
| File type | Description |
| 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 is valid, a summary of the detected engine, categories, and rules will appear. You can import rulesets from newer versions, but only rules compliant with the previous library versions will be applied during analysis. See the Kiuwan Local Analyzer documentation for more details.
Special features when importing checKingQA rulesets
In the previous situation, 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.
Mapping the imported categories (Map user rules categories to CQM values)
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. Not all rules read may be 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 by accessing the rule details from your library.
Adding the imported rules to existing models (Add rules to user's models)
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 into your account's library.
The preview page (Import preview)
Once you have completed the import configuration, a preview page will be shown.
Here you can see the rules that are 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).
The results page
Once the import has finished, a results pop-up will be shown:
This pop-up shows the summary result of the import run.
Analyzing your code with imported rules
To analyze code with imported rules:
- Add the rules to an existing model (you may have already done this during the import).
- Publish the model.
- Run your analysis using Kiuwan Local Analyzer.
Imported rules can be mixed with existing library rules. You can filter your library by Engine to find rules from PMD, Checkstyle, FindBugs, or checKingQA. If your rules are based on supported versions of these tools, the Kiuwan Local Analyzer will work without additional configuration.
For custom rules, use the Kiuwan Local Analyzer extension mechanism. Refer to the documentation for more details on adding custom libraries and how the extension mechanism works.