Campaigns

Required role  Campaign Execution
Access  CodeChecker Server →  Campaign Execution →  Campaigns

Campaigns are used to carry out a code review process and to keep records of these executions over time. Associate a code review with a target to define the context for each campaign's analysis. When a campaign is launched, the rule sets defined in the selected code review are executed on the associated target to check the code quality.

Once a campaign is completed, the campaign status indicates if the quality rules contained in the executed rule sets succeeded or failed. The campaign results can then be viewed to know which quality rules failed and which source members are concerned.

Example

You want to check the code quality of your application. You have defined quality rules to set code quality goals, and these quality rules are grouped into a rule set.

To execute the quality rules on the source code of your application, you need to create a code review to associate the rule set to that target application. You will then be able to generate campaigns using this context and carry out the code review process.

Reference

For more information about code reviews, refer to Code reviews.

For more information about targets, refer to Targets.

Campaigns can be manually created and launched, or scheduled to automate the creation and launch processes.

Reference

This chapter describes how to manually create and launch campaigns. For more information about scheduling campaigns, refer to Schedules.

Campaigns

The  Campaigns view is accessed from the  Campaign Execution node in the Navigator.

Enter any combination of the above search criteria, then click the Search button to display the results. To display the complete list, click the Search button without entering any search criteria.

Follow the subsequent steps to manually create a new campaign.

Note

When a campaign is created and correctly configured, it is also possible to duplicate it to quickly create predefined entities.

Reference

For more information about duplicating campaigns, refer toDuplicating campaigns.

Step 1   To access the Create Campaign wizard, either click the  Create icon in the toolbar of the  Campaigns search view, or right-click anywhere in the search list of the view and select  Create Campaign.

Step 2   Select a Code Review from the drop-down list. This value is required and cannot be edited once the campaign is created.

When the campaign is launched, the rule sets defined in the selected code review will be executed on the associated target.

Step 3   Define the campaign's Identifier. This value is required and cannot be edited once the campaign is created.

By default, the code value is automatically defined according to the Campaign Identifier Template set for the selected code review.

Step 4   Select a Target from the drop-down list. This value is required and cannot be edited once the campaign is created.

When the campaign is launched, the code review will be carried out on the selected target application.

Click Finish.

Result   The new campaign is created, is displayed in the list in the  Campaigns search view, and is ready to be launched.

Note

Before a campaign is launched, its Start Date, Duration and Status are empty.

Duplicating a predefined and pre-configured campaign enables you to quickly reuse the code review context, without having to redefine the same fields multiple times. When a campaign is duplicated, the new campaign contains the same information as the original and is immediately ready to be launched. The selected code review and target cannot be edited.

Example

When setting up the context of a code review process, you might need to launch multiple campaigns to make sure the code review process is carried out properly and checks the desired conditions.

You can create one campaign, using the desired code review and target. You can then duplicate the campaign as many times as needed, instead of manually creating all the campaigns.

To duplicate a campaign, either right-click on the item in the  Campaigns search view and select  Duplicate, or select the item and click the  Duplicate icon in the toolbar. The duplicated campaign is displayed in the list in the  Campaigns search view and is ready to be launched.

The duplicated campaign contains the same exact information as the original, except for the Identifier because it must always be unique. The code of the duplicated campaign is defined automatically depending on the code review selected to create the original campaign.

  • If the Campaign Identifier Template defined in the code review contains the variable $i, then the code of the duplicated campaign will reuse the same default code with the variable incremented by one.
  • If the Campaign Identifier Template defined in the code review does not contain the variable $i, then the code of the first duplicated campaign will be "the original campaign's identifier (1)". The code of the second duplicated campaign will be "the original campaign's identifier (2)", and so on.

After manually creating a campaign, follow the subsequent steps to manually launch the campaign and start the code review process.

Important!

A campaign can only be manually launched once. To launch a second campaign created using the same code review, a new campaign must be manually created or duplicated, or a campaign schedule must be used to create new campaigns automatically.

Reference

For more information about scheduling campaigns, refer to Schedules.

Step 1   Locate the campaign in the  Campaigns search view.

Step 2   Either right-click on the item in the view and select  Launch, or select the item in the view and click the  Launch icon in the toolbar.

Result   The campaign is launched and the code review process starts. The Status column is updated with the progress being made. The number of members checked is displayed to show how quickly the code review process is going.

When the code review process is finished and the campaign is completed, an automatic recap email is sent if the Send Recap After Execution box was checked in the code review's editor.

Note

To see the results of any campaign, either manually launched or scheduled, open the campaign's editor.

To open a campaign's result view and review the results of the finished code review process, locate the campaign in the  Campaigns search view, then either:

  • double-click on the item in the view,
  • right-click on the item in the view and select  Open Campaign Results, or
  • select the item in the view and click the  Results icon in the toolbar.

The Campaign results view

Important!

Campaigns cannot be edited. The campaign's results view can only be used to view information about the code review process and the campaign results.

Note

The campaign results are ordered by their security level.

It is possible to open a quality rule's web documentation page from the  Campaign Results view. To do so, you can either double click on the chosen quality rule to open its documentation in a browser, or right-click on the quality rule and select  Open Rule documentation.

Identifier
This field displays the unique campaign's ID defined during the creation of the campaign.
Code Review
This field displays the code review selected during the creation of the campaign. Follow the link to access the code review's editor.
Target
This field displays the target selected during the creation of the target. Follow the link to access the target's editor.

Created by & Executed by: These fields display, respectively, the user who created and the user who executed the campaign.

Start Date & End Date: These fields display, respectively, the day and time when the campaign was launched and when it ended.

Status: This field displays the campaign status.

After the code review process is finished, the campaign status is either changed to OK or to one of the failure levels: NOTICE, WARNING, or FATAL.

  • If the campaign status is OK, it means that none of the quality rules executed failed during the code review process.

  • If the campaign status is one of the failure levels, it means that at least one of the quality rules executed failed during the code review process.

    The failure level given to the quality rule determines the campaign status. If multiple quality rules with multiple failure levels failed during the code review process, the most critical failure level is used to determine the campaign status.

  • If the quality rules failed to return any results, the status is ERROR. The cause of the error can be found in the campaign’s log file.
Example

During a code review process, 5 NOTICE and 2 FATAL quality rules failed. The FATAL failure level is more critical than the NOTICE level, so the campaign overall status will be changed to FATAL.

The Global Execution Time displays the total amount of time it took the campaign to execute.

The Average Time Per Check displays the average time taken to check each source member during the campaign.

The Number of Checked Source Members displays the total number of source members checked during the campaign.

Log: Click the open log tab to view the campaign's logs. The log file opens in the  Log tab.

This section displays detailed information about the code review process, and shows you precisely which quality rules fail and which source members are concerned.

The campaign results details

To be able to navigate the results, a filter is available to display the results by Target name or Status (Error, Fatal, Warning, Notice, OK, Ignored).

Note

By default, only the Error, Fatal and Warning status are checked.

The Quality Rule column displays the complete list of rules included in the campaign. Each quality rule is associated with a Status:

  • OK if the quality rule succeeded,
  • the failure level given to the quality rule (Notice, Warning, or Fatal) if the quality rule failed at least once,
  • Error if the quality rules failed to return any results. The cause of the error can be found in the campaign's log file.
  • Ignored if the source was ignored by the code review process because the quality rules were not applicable (the source type is not supported by the quality rule).

Expand a quality rule's node to display the list of all the source members that were checked during the code review process. For each source member:

  • the Source Path column displays the source member's path,
  • the Metric Value column displays the numeric value deduced from the source member's analysis. If an error occurs during the execution and no value could be deduced, a  warning icon is displayed. Information about the error is given in the tooltip and a full description is available in the logs.
  • the Status column shows whether the quality rule succeeded or failed.

To view a source member's source code in a dedicated view, locate the source member in the result view of the campaign, then either:

  • double-click on the item in the view, or
  • right-click on the item in the view and select  Open Source.

The source member's code view

The lines of code that do not comply with any of the rules in the rule set are underlined. On the left, a status icon gives the failure level of the source code.

To open a rule's documentation associated with non-compliant code, hover the mouse over it and click the link in the hint box to the documentation of the rule.

This section displays detailed information about the campaign logs, and allows you to export the logs in text or JSON format.

The campaign log tab

When a campaign is completed, you can export the campaign to Excel format. In the exported file, the Campaign tab gives the summary of the campaign and its execution details. The Rules tab lists all the rules that were applied during the campaign and the number of cases found. The Sources tab shows all the code review results on the sources.

The campaign Excel export file

To export a campaign, either right-click on the item in the  Campaigns search view and select  Export to Excel, or select the item and click the  Excel Export icon in the toolbar.

Note

To export campaigns to Excel on Linux-based systems, the fontconfig package must be installed on the machine.

When a campaign is completed, an automatic recap email is sent if the Send Recap After Execution box was checked in the code review's editor. In addition, it is possible to manually send that recap email.

The recap email contains the same information as the results displayed in the campaign's editor. The email addresses to which the email is sent are defined in the Emails field in the code review's editor.

To manually send a recap email for a campaign, either right-click on the item in the  Campaigns search view and select  Send Email, or select the item and click the  Send icon in the toolbar.

Warning!

Deleted campaigns cannot be recovered.

The campaign execution results and the campaign logs are discarded. The issues generated at the end of the execution are kept in the  Issues view.

Deleting a campaign that is still in execution will abort the execution. In that case, the issues found so far are not generated.

To delete a campaign, either right-click on it in the  Campaigns search view and select  Delete, or select it and click the  Delete icon in the toolbar. Click OK to confirm or click Cancel to keep the campaign.