Installing and Using Acrolinx for SonarQubesupport.acrolinx.com /hc/en-us/articles/203912352-Installing-and-Using-Acrolinx-for-SonarQube

Acrolinx Customer CareToday at 14:08Unfollow

From 1.1 onwards, we refer to " rule sets " as " writing guides. "

Applies To

Software Version

Acrolinx for SonarQube 1.1

What You Should Know before Installing

Before you install Acrolinx for SonarQube, make sure that you have the following software installed:

Software Version

SonarQube Server 5.6.3, 5.6.6, and 6.1

Java Runtime Environment (JRE) 1.8

Acrolinx Server 5.1 or later

Jenkins Server (optional) 2.65

Also make sure that Acrolinx for SonarQube is enabled in your Acrolinx license, otherwise you'll get a licensingerror. You can check this in the Acrolinx server Dashboard . If you need a new license, contact your Acrolinxproject consultant.

You'll receive the Acrolinx software files in a compressed zip file.

IntroductionYou can use Acrolinx for SonarQube to include language quality in your Continuous Inspection process.

This means that:

Your build engineers can set up automated tests to check the quality of the language in your projectdocuments and help resources.

Your developers can reject builds if there are too many issues in some documents.

Developers can also use tools like Maven and SonarQube Runner to check the language quality before1/15

checking the code quality.

Project managers can also review the content quality for entire projects.

To get started, review the following tasks and concepts:

1. Supported File Types

2. Installing Acrolinx for SonarQube

3. Configuring the Connection to the Acrolinx Server

4. Enabling and Configuring the Acrolinx Coding Rules

5. Configuring the Acrolinx Settings for a Project in the SonarQube Dashboard

6. Adding the Acrolinx Widget to Your Project Dashboard

7. Checking a Project

Include Acrolinx Checking in a Jenkins Build

Include Acrolinx Checking in a Maven Build

Check a Project with SonarQube Runner

8. Reviewing the Acrolinx Results

Supported File Types

Acrolinx supports the following file types when working with SonarQube:

Type Extension

Text *.txt

JSON *.json

Properties *.properties

XML *.xml

HTML *.html, *.htm, *.xhtm, *.xhtml,

The following formats are only supported in Acrolinx for SonarQube versions 1.0.4 or later.

Microsoft Worddocuments

*.docx

PDF *.pdf

Note that Acrolinx doesn't work consistently when checking PDFs. We recommend usingthe source document to check your content.

NOTE: SonarQube can't decode these file formats completely so you can't review the issues inline in yourcontent.

Instead, open the Issues page in SonarQube and filter for your project.

▲ Back to Top

Installing Acrolinx for SonarQube

2/15

To install Acrolinx to SonarQube, follow these steps:

1. Extract the contents of the zip file to the following directory:

<SONARQUBE_INSTALL_DIR>/extensions/plugins

2. Restart the SonarQube server.

▲ Back to Top

Configuring the Connection to the Acrolinx Server

Once you've installed Acrolinx, you should be able to configure the Acrolinx settings in the SonarQube webinterface. The first thing you'll need to do is configure the connection to your Acrolinx server.

Before you do this, you might want to set up a dedicated user account on your Acrolinx server that SonarQubecan use for checking. We recommend this if you use analytics reports that break down checking behavior byuser. You can isolate the automated checking that is done through SonarQube by filtering for this dedicated useraccount.

To configure the Acrolinx connection to your Acrolinx server, follow these steps:

1. Navigate to Administration > General Settings >Acrolinx

2. Enter the address of your Acrolinx server.

3. Enter the user name and password for the Acrolinx account that you want to use to connect to the Acrolinxserver.

4. Click Save .

If you're connecting to a secure Acrolinx server, on which you've installed Let's Encrypt certificates, but the Javaversion on your client machine doesn't support certificates from Let's Encrypt , then you need to import the

3/15

certificate manually.

To import the certificate manually, follow these steps:

1. Download the 'lets-encrypt-x3-cross-signed.cer' file from https://letsencrypt.org/certs/lets-encrypt-x3-cross-signed.der .

2. Import the certificate:

1. Open a command prompt and run the following command:

keytool -trustcacerts -keystore %JAVA_HOME%\jre\lib\security\cacerts -storepass <PASSWORD>-importcert -alias lets-encrypt-x3-cross-signed -file <DIR_PATH>\lets-encrypt-x3-cross-signed.cer

The <PASSWORD> is your key store password.

The <DIR_PATH> is the directory where you saved the downloaded certificate.

▲ Back to Top

Enabling and Configuring the Acrolinx Coding Rules

Acrolinx comes with a set of coding rules for each file supported type, but they're all disabled by default. Youhave to enable them first and set the severity level for each one.

There's a coding rule for each combination of file type and issue type. For example, grammar issues in text files,grammar issues in XML files, and so on. We recommend that you filter by file type first, then filter for all ruleswith the tag "Acrolinx". This makes the list of rules is more manageable.

To enable and configure the Acrolinx coding rules, follow these steps:

1. Make sure you're logged in to SonarQube as an administrator.

2. Open the Rules page, type "Acrolinx" in the Rules search box and press Enter.

You should be able to see the new Acrolinx coding rules listed.

3. Click the name of a rule to open it, and in the Quality Profiles section, click Activate .

4. In the dialog box that appears, select your preferred quality profile and severity level, then click Activate .4/15

Acrolinx for SonarQube comes with a built-in quality profile called "Acrolinx". If you want to test theAcrolinx rules first, you can activate the rules for this quality profile only and assign the quality profile to atest project.

When you're ready to use the rules in production you might assign the rules to a quality profile thatcontains all your project-specific coding rules such as error-handling or well-formedness rules.

5. Repeat the process for all remaining Acrolinx coding rules.

6. If you’ve existing projects that you want to check, make sure that they're using a quality profile thatcontains Acrolinx rules.

You can do this in the Quality Profile section of your project Administration settings.

▲ Back to Top

5/15

Configuring the Acrolinx Settings for a Project in the SonarQube Dashboard

Once you've enabled the Acrolinx coding rules, you'll need to configure the Acrolinx settings for each project. Ifyou don't have any projects yet, check the SonarQube documentation for more details on how to create projects.

The most important settings that you'll need to configure are the Language and Writing guide settings. Youcan't run any checks until you've configured these settings. You also have to configure these settings in theSonarQube plug-in configuration the first time you check a project .

The remaining settings have default values so you can leave them at their defaults if you want to get startedquickly.

You can also configure the Acrolinx settings in your SonarQube plug-in rather than updating them in theSonarQube dashboard. However, you might use the SonarQube dashboard if you prefer to edit the settings inweb interface rather than editing a plug-in configuration file.

To configure the project settings in the SonarQube dashboard, follow these steps:

1. Open a project and in the Administration menu, select General Settings , then click the Acrolinxcategory.

2. Configure the checking language.

In the Checking Language field enter the language code of your checking language,

For example, for English you would enter "en", for German you would enter "de" and so on.

3. Configure the Writing guide

Enter the exact name of the Writing guide that you want to use. Make sure that you enter as it appears in6/15

your Acrolinx server installation. For example, see the Resources section of the Acrolinx dashboard.

4. Configure the type of issues to check for.

For each of the issue types, select "true" or "false" depending on whether you want Acrolinx to check forthat issue type

5. Configure the file format and character set.

6. Click Save .

▲ Back to Top

Adding the Acrolinx Widget to Your Project Dashboard

After you run an analysis on your projects, you'll want to see a summary of the Acrolinx results for each project.The easiest way to do this is to add an Acrolinx widget to your project Dashboards.

To add an Acrolinx widget to your project dashboards, follow these steps:

1. Open a project and navigate to Dashboards, go to Manage Dashboards and click Configure Widgets .

2. In the section that appears, select the Acrolinx category.

3. In the widget that appears, click Add widget .

You should now have the Acrolinx widget on all project dashboards.

7/15

▲ Back to Top

Checking a Project

When you run analysis on a project with SonarQube, Acrolinx automatically checks content quality for thesupported file types in your project. There are many ways to analyze a project with SonarQube . The followinganalysis plug-ins fully support Acrolinx checking.

1. SonarQube for Jenkins

2. SonarQube for Maven

3. SonarQube Runner

In each of these plug-ins, you can send the Acrolinx settings as part of the analysis configuration for a project. Inother words, you can configure the Acrolinx settings for a project in your SonarQube plug-in, instead of theconfiguring them in the SonarQube project dashboard.

However, you must send your language and Writing guide the first time you check a project, even if they'reconfigured in the SonarQube Dashboard.

▲ Back to Top

Include Acrolinx Checking in a Jenkins Build

If you use Jenkins to manage your software builds, you can include automated Acrolinx checking as part of aJenkins build. If you don't have it already, install the SonarQube Plug-in for Jenkins first.

To include Acrolinx checking in a Jenkins build, follow these steps:

1. Open the Configure page for your Jenkins project and in the Build section, click Add build step andselect the action Invoke Standalone SonarQube Analysis.

2. In the Analysis properties section, add the following SonarQube project properties:

sonar.projectKey=xml:testsonar.projectName=XML Testsonar.projectVersion=1.0sonar.sources=srcsonar.sourceEncoding=UTF-8

3. After the SonarQube project properties, add the Acrolinx check settings.

Most settings have default values, but at a minimum, you'll need to configure the language and Writingguide as follows:

sonar.acrolinx.language= <CHECKING_LANGUAGE>sonar.acrolinx.writing.guide= <WRITING_GUIDE_NAME>

For a full list of the Acrolinx properties, see the Acrolinx for SonarQube properties reference .

Your project settings should look something like this:

8/15

After you build your project, you should see information about the analysis in the Jenkins console. Thisinformation includes details of the resources that were checked with Acrolinx.

▲ Back to Top

Include Acrolinx Checking in a Maven Build

If you use Maven to manage and build your Java-based projects, you can include automated Acrolinx checkingas part of a Maven build. You must have Maven version 3.0+ or later to use Acrolinx for SonarQube with Maven.

If you don't have it already, install and configure the SonarQube Plug-in for Maven first. You should have alreadyset up a project for analysis with SonarQube according to the SonarQube documentation .

To include Acrolinx checking in a Maven build, follow these steps:

9/15

1. Open the pom.xml file for your project and add the Acrolinx check settings.

Most settings have default values, but at a minimum, you'll need to configure the language and Writingguide as follows:

<properties><sonar.acrolinx.language>en</sonar.acrolinx.language><sonar.acrolinx.writing.guide> US English </sonar.acrolinx.writing.guide></properties>

For a full list of the Acrolinx properties, see the Acrolinx for SonarQube properties reference .

After you have set up your pom.xml , it might look something like this simple example:

<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"><modelVersion>4.0.0</modelVersion>

<groupId>org.codehaus.sonar</groupId><artifactId>example-java-maven</artifactId><version>1.0-SNAPSHOT</version>

<name>Java :: Simple Project :: SonarQube Maven</name><properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <sonar.acrolinx.language>en</sonar.acrolinx.language><sonar.acrolinx.writing.guide>Publications</sonar.acrolinx.writing.guide><sonar.acrolinx.spelling>true</sonar.acrolinx.spelling><sonar.acrolinx.grammar>false</sonar.acrolinx.grammar><sonar.acrolinx.style>true</sonar.acrolinx.style><sonar.acrolinx.reuse>true</sonar.acrolinx.reuse><acrolinx.deprecated.terms>true</acrolinx.deprecated.terms><acrolinx.valid.terms>true</acrolinx.valid.terms><acrolinx.admitted.terms>true</acrolinx.admitted.terms><acrolinx.new.terms>true</acrolinx.new.terms><acrolinx.term.sets>SmartTech</acrolinx.term.sets></properties>

</project>

2. Save your pom.xml and build your project with the Maven command mvn while adding the command

sonar:sonar as an extra argument like this: mvn package sonar:sonar

After you build your project, you should see information about the analysis in your command shell. Thisinformation includes details of the resources that were checked with Acrolinx.

10/15

▲ Back to Top

Check a Project with SonarQube Runner

If you want to test SonarQube analysis with Acrolinx before you include it in a build, you can use SonarQubeRunner as a standalone analyzer.

Acrolinx for SonarQube works with SonarQube Runner 2.4 or later.

To check a project with SonarQube Runner, follow these steps:

1. Create a file called “sonar-project.properties” in the directory that contains your project files.

2. Add the following properties to the file you just created:

# must be unique in a given SonarQube instancesonar.projectKey=<PROJECT_KEY># this is the name displayed in the SonarQube UIsonar.projectName=<PROJECT_NAME>sonar.projectVersion=1.0 # Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows.# Since SonarQube 4.2, this property is optional if sonar.modules is set. # If not set, SonarQube starts looking for source code from the directory containing # the sonar-project.properties file.sonar.sources=src # Encoding of the source code. Default is default system encoding#sonar.sourceEncoding=UTF-8

### Acrolinx for SonarQube Properties #### Requiredsonar.acrolinx.language =<LANGUAGE_ID>sonar.acrolinx.writing.guide =<WRITING_GUIDE_NAME>

#Optional<OPTIONAL_PROPERTIES>

3. Replace the placeholder values such as <PROJECT_KEY> and <OPTIONAL_PROPERTIES> with therequired settings.

11/15

You can find a list of all the optional properties, see the Acrolinx for SonarQube properties reference .

You can use the following basic example as a reference:

# must be unique in a given SonarQube instancesonar.projectKey=dita:topics# this is the name displayed in the SonarQube UIsonar.projectName=DITA topicssonar.projectVersion=1.0 # Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows.# Since SonarQube 4.2, this property is optional if sonar.modules is set. # If not set, SonarQube starts looking for source code from the directory containing # the sonar-project.properties file.sonar.sources=src # Encoding of the source code. Default is default system encoding#sonar.sourceEncoding=UTF-8

### Acrolinx for SonarQube Properties #### Requiredsonar.acrolinx.language=ensonar.acrolinx.writing.guide=Techpubs

#Optionalsonar.acrolinx.grammar=truesonar.acrolinx.spelling=truesonar.acrolinx.style=trueacrolinx.term.sets=Routers,Switchesacrolinx.deprecated.terms=trueacrolinx.admitted.terms=true

4. Open a command shell, navigate to the project root directory, and run the command sonar-runner .

You should see information about the analysis in your command shell. This information includes details ofthe resources that were checked with Acrolinx

12/15

▲ Back to Top

Reviewing the Acrolinx Results

After your project analysis has completed, you'll be able to review the Acrolinx results in the Acrolinx widget thatappears on the project dashboard.

You can see a summary of the number of issues for each issue type.

To get more details about a particular issue type such as spelling, click the measure and you'll see a list of files inyour project. Each file is listed with the issue count for that measure from lowest to highest.

The following screenshot shows an example of a summary for grammar issues.

13/15

To see the contents of a file annotated with all issues, click the file name.

To see all the issues within the rule filter, click the Issues measure in the Issues and Technical debitwidget.

You should then see the issues on the Rules page, where you can filter the rules by different criteria. Tosee only Acrolinx rules, filter for the Acrolinx tag.

14/15

▲ Back to Top

Was this article helpful?

Comments

15/15