Import your existing projects into a new projects root
MISRA checkers are now included in your installation; Do not run kwdeploy sync on the 'misra.checkers.zip' package. If the 'misra.checkers.zip' package is in the plugins folder of your projects root, remove it before running kwdeploy sync.
Before you decide to import your projects, make sure that your current installation supports this feature.
Typically, this process involves the following steps:
- backing up your existing projects_root (just to be safe)
- installing the new Klocwork Server (either on a new machine or using a different port number) and starting the server.
- validating your database
- opening the portal, and using the GUI to import existing projects to the new installation
- after testing your new installation, uninstalling the existing server and removing the old projects_root
Before you begin
The import process involves running your existing Klocwork installation (and projects_root) and your new Klocwork installation (with clean projects_root) concurrently. Once you've installed the new server, you must import any projects from the existing projects_root into the clean projects_root.
Remember that you cannot run two Klocwork servers on the same machine without specifying unique port numbers. If you plan on installing the new Klocwork installation on the same machine, it's a good idea to stop and restart your existing server using a different port number. This will allow you to maintain the existing port number for your new installation.
If you are moving to a new major release of the software, ensure that you have a compatible license, as each major release requires a new Klocwork license. See Licensing for more information.
Also Reprise License Manager prevents more than one instance of the vendor daemon from running on each machine, which means that you cannot run two License Servers on one host. In this scenario, you need to run one License Server and point both Klocwork installations to that License Server. See Licensing with multiple projects_root directories for more information.
Both the Klocwork and Database servers require fully qualified domain names or IP addresses assigned in order to be accessible from the target server host during the import process. Don't use localhost.
You must have Projects root admin access in order to perform the import operation.
Supported upgrade paths to versions of Klocwork that support project import
Find your current version in the chart below and follow the appropriate upgrade path. Once you've upgraded to the correct version of Klocwork, you can import your existing projects from there.
The chart below is accurate for the latest current release. Perforce is also here to help! If you need to move from an older release, you can contact Static Code Analysis Professional Services to discuss assistance via a services engagement.
| If you're using Klocwork version | Then import is supported to the following version |
|---|---|
| 2023.2 latest | Klocwork 2023.3 latest |
| 2023.1 latest | Klocwork 2023.3 latest |
| 2022.4 latest | Klocwork 2023.3 latest |
| 2022.3 latest | Klocwork 2023.3 latest |
| 2022.2 latest | Klocwork 2023.3 latest |
| 2022.1 latest | Klocwork 2023.3 latest |
| 2021.4 latest |
Klocwork 2023.1 latest --> 2023.3 latest |
| 2021.3 latest | Klocwork 2023.1 latest --> 2023.3 latest |
| 2021.2 latest | Klocwork 2023.1 latest --> 2023.3 latest |
| 2021.1 latest | Klocwork 2023.1 latest --> 2023.3 latest |
Interoperability between releases
To take advantage of the latest improvements in Klocwork, we always recommend you upgrade your Server, Build, and Desktop Analysis plug-ins to the latest version of the product. Klocwork Server and Build Tools are compatible with the Desktop Analysis plug-ins within each major release.
Klocwork also provides the ability to load builds from the previous major version of Klocwork into the current version of Klocwork. For example, this means you can load Klocwork builds from any version of Klocwork 2022 into Klocwork 2023.3 without having to import or migrate data. For more information, see Cross-version support for builds.
If your current Klocwork server version does not meet the version requirements for importing projects, upgrade your existing version of Klocwork to a supported service release or version. Next, install the latest version of Klocwork. After you've installed the latest version of Klocwork, you can use it to connect to your existing Klocwork server and import your projects. Follow the steps described below to import your projects.
Install the Klocwork Server package
Install the Klocwork Server package. For instructions, see Installing Klocwork.
Be sure to copy your license file to <projects_root>/licenses.
See Licensing for information about options.
Start the server
Once you've installed the new version of Klocwork, start the servers. Each installation of Klocwork requires you to specify a unique hostname and port number combination.
You can specify the unique hostname and port number combination either at startup, or during the installation process. See, Managing the Klocwork Servers for more information.
Validate your database (mandatory)
dbvalidate is a tool that checks the consistency of data in your database. Running this tool is mandatory, so that any errors in your database can be corrected before you migrate or import. Use the version of the dbvalidate tool that matches your installed version of software (that is, the version that matches your projects_root directory).
The Database Server from your old installation must be running to validate the database. The Database Server is listed as a separate service from the Klocwork Server, so ensure that it is running.
java -jar <server_install>/class/dbvalidate.jar --projects-root <projects_root>
where
- <server_install> is your installation directory
- <projects_root> specifies the location of the old projects root you want to validate
Example
java -jar /local/tools/klocwork/server/class/dbvalidate.jar --projects-root /local/tools/klocwork/server/projects_root
The dbvalidate tool will report any errors between the "validation started" and "validation finished" lines:
Wed Jun 01 07:53:58 CDT 2020 kw_central database (version: 95) validation started <detected errors appear here> Wed Jun 01 07:54:28 CDT 2018 Database validation finished.
- If Errors are displayed, please open a support ticket so that we can correct the error prior to import or migration.
- If no errors are displayed, your database was successfully validated.
You can also run dbvalidate with the --rebuildIndex=true option; This enables you to re-create the lucene index for the specified project, which often allows you to decrease the size of the index.
Important: Make sure you back up your lucene index folder before running dbvalidate with the --rebuildIndex=true option.
For example, you can run the following:
java -cp dbvalidate.jar com.klocwork.dbvalidate.Cleanup231 --projects-root <projects_root_folder> --project <project_name> --rebuildIndex=true
Log in to Klocwork Static Code Analysis
username: jsmith password: <empty>For more details on security and authentication methods, see Security and permissions.
Import your projects and server settings
With the new Klocwork Server installed and the portal up and running, you can import server settings and projects from your existing Klocwork installation.
When you import server settings from the existing source server, all global permission settings are imported along with the permission settings for only those projects that exist on the destination server. In other words, if you import Server A's settings to Server B, then you import a project from Server A to Server B, any permission settings that are specific to project A will not be carried over to Server B. To carry forward project A's project-specific permission settings, you must re-import the server settings after performing the import operation.
- Authentication settings from source Server A overwrite the authentication settings on target Server B.
- For roles that exist on both servers, the role permissions for source Server A overwrite the role permissions on target Server B.
- Roles and their associated permissions that only existed on the source Server A are copied to the target Server B.
- Roles that only exist on target Server B are not modified; their permissions stay the same.
Important: In cases where a project contains custom settings, you must re-import your server settings after performing a project import.
When importing a projects_root that contains a large number of issues and builds, your new projects_root may increase in size.
Importing your existing projects
- In the Klocwork portal, click Klocwork Static Code Analysis and log in to the product as the Projects root admin user.
- Click the Projects tab.
If this is your first time using the installation, click the Import settings or projects button.
If you've already created a project or imported a project, click the Import button.
- In the Klocwork server connection dialog, specify the log in and connection information for your existing Klocwork installation (the installation from which you want to import). Specify:
- the URL of the existing server, for example: http://server21:8082
- your user name. You must have Projects root admin rights in order connect to the server and import your projects.
- your password (if required)
- Click Import server configuration to import the existing server's configuration settings. This includes authentication configuration settings, permissions, custom metrics, reports definitions, and e-mail subscription settings.
If you import authentication settings, the system may log you out as your credentials may no longer be valid. If this happens, log in using the Admin credentials you just imported.
- Click List Projects to see a list of projects in your existing projects_root.
- In the Choose projects to import dialog, select the project(s) that you want to import to your new projects_root.
-
Click Import. The Import status dialog will display the status of the project import, while an import status message will appear at the top of the Projects tab. Any project that imported successfully will appear in your projects list.
During the import process, while projects are actively being imported, issue information in the Projects view may not accurately reflect the data in the source project. Information in the Projects view will be updated as soon as the import operation has completed. Check the import status indicator for progress information.
- Click Import server configuration again to import any project-specific configuration settings. This is a mandatory step, since any project-specific configuration settings will be lost if you do not re-import the server settings.
- For each imported project, click Permissions and check that the permissions are correct for each project.
It is important to verify the permissions for each project since at import time. You should repeat this process after each import operation, and you must be careful to re-import the server settings for each source server that you import from.
If you previously modified the memory allocation file located at <old_Klocwork_install>/config/java_wrappers_memory.conf, verify that you still need those modifications and make the same changes to java_wrappers_memory.conf in the new installation.
Use the Web API to import your projects
You can use the Klocwork Web API to import your projects on the command line. The Web API requires Web API access permissions. By default, the Project admin role and the Projects root admin roles have access to the Web API. The following example shows a curl script to import a given project:
curl --data "action=import_project&user=myself&project=my_project&sourceURL= http://oldserver:8080&sourceAdmin=user&sourcePassword=pwd" http://localhost.mycompany.com:8080/review/api
where:
- project is the name of the project you want to import.
- sourceURL is the URL of the existing, source Klocwork Server.
- sourceAdmin is the user id of the source Klocwork Server administrator (must have Projects root admin access).
- sourcePassword is the administrator's password.
To return a list of all projects in the source projects_root folder, run the following command:
curl --data "action=projects&user=myself&" http://localhost.mycompany.com:8080/review/api
You can also use the Web API to import your server configuration settings:
curl --data "action=import_server_configuration&user=myself&sourceURL= http://oldserver:8080&sourceAdmin=user&sourcePassword=pwd" http://localhost.mycompany.com:8080/review/api
Typically these operations are scripted using a language such as Python. See the Klocwork Web API cookbook for examples of scripted curl calls using Python.
Import taxonomy file(s)
If you imported a custom taxonomy in a previous release, you need to re-import the new taxonomy file to pick up changes. See What's new for a list of changes to the taxonomies.
Import your code reviews
You can import your existing code reviews into your new projects root.
To import your existing Klocwork Inspect code reviews:
Before importing code review data, you must have the equivalent project in your local projects root. Importing code review data will overwrite any existing code review data in the current projects_root folder.
- In the Klocwork Product Portal, click Code Review.
- Click Settings, then in the left pane, click Import.
- Click Import code reviews, then specify the URL of the source Klocwork server, the user ID of the Klocwork administrator for the source projects root, and the password (if required).
- Select the projects that you want to import, then click Import .
To import your existing Klocwork Code Review:
Klocwork Code Review does not organize code reviews by project. When you import existing code reviews from your Code Review server, you must specify the code reviews by tag.
- In the Klocwork Product Portal, click Code Review.
- Click Settings, then in the left pane, click Import.
- Click Import code reviews, then specify the URL of the source Klocwork Code Review server, the user ID of the Klocwork administrator for the source projects root, and the password (if required).
- Select the local project into which you want to import the code reviews.
- In the left pane, select the tags that you want to import.
- Click Assign to assign the tags to the selected project.
- Click Import to import the code reviews.
Test your upgrade
Ensure that you can see your projects and builds in Klocwork Static Code Analysis.
If you installed a new license file, ensure that it was installed correctly by checking that the number of licenses is correct.
Go live with your new installation
Once you're satisfied that your new installation is valid, and that your existing projects were imported correctly, it's time to go live with your new installation.
If you've chosen a new and unique port number for your new installation, then you can go ahead and communicate that information to your users.
If you'd like to reuse your existing port number (so that users don't have to update their local settings) then you'll need to stop and restart all of your Klocwork servers, taking care to specify the existing server port number for your new installation.
Upgrade all Desktop Analysis plug-ins
To take advantage of the latest improvements in Klocwork, we always recommend you upgrade your Desktop Analysis plug-ins to the latest version of the product.
Your users can reinstall their Klocwork Desktop Analysis plug-ins themselves by downloading the appropriate plug-ins from the Klocwork portal once it is up and running. See Downloading and deploying the desktop analysis plug-ins for instructions on how to download and deploy the plug-ins to the server.
When upgrading to the Klocwork extension for Visual Studio, any analysis results data generated from the previous version of the plug-in will be removed. Therefore, any local defect citation information not already synchronized with the server will be lost. You can re-analyze your solution(s) to get the analysis results with the new plug-in.
Before your first integration build analysis using Klocwork
New releases of Klocwork normally have changes to the checker configuration to keep up with current events and respond to customer requests. These changes may mean that your checker configuration from the previous release isn't the same in the new release.
Make sure that you have the right checkers enabled to match your old configuration. See What's New for a list of updated checkers, then make any changes to your checker configuration. After you're satisfied with your configuration, re-generate your build specification to capture the latest changes and perform your integration build analysis on unmodified source code.
If you've already run your first Klocwork analysis and you're missing some issues or status changes, delete that build, reconfigure your checkers, and run a new analysis.
We recommend running your final pre-upgrade integration build analysis and your first Klocwork analysis on identical source code, and then comparing the two builds. This allows you to assess changes in the analysis engine. For details on improved, added, and removed checkers in this version, see What's New.
