Import your existing projects into a new projects root

Validate includes a simple GUI that you can use to import projects from an existing projects_root to your new installation. This allows you to migrate your data on a project-by-project basis without using the command line.

Before you decide to import your projects, make sure that your current installation supports this feature.

Typically, this process involves the following steps:

  1. Backing up your existing projects_root (just to be safe).
  2. Installing the new Validate Server (either on a new machine or using a different port number) and starting the server.
  3. Validating your database.
  4. Opening the portal, and using the GUI to import existing projects to the new installation.
  5. After testing your new installation, uninstalling the existing server and removing the old projects_root and/or the backup projects_root.

Before you begin

The import process involves running your existing Validate installation (and projects_root) and your new Validate 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 Validate servers on the same machine without specifying unique port numbers. If you plan on installing the new Validate 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 Validate license. See Licensing for more information.

Also, you cannot run two License Servers on one host. You need to run one License Server and point both Validate installations to that License Server. See Licensing with multiple projects_root directories for more information.

Both the Validate 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 Validate 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 Validate, 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 Validate version Then import is supported to the following version
2024.2 latest Validate 2024.3 latest
2024.1 latest Validate 2024.3 latest
2023.4 latest Validate 2024.3 latest
2023.3 latest Validate 2024.3 latest
2023.2 latest Validate 2024.3 latest
2023.1 latest Validate 2024.3 latest
2022.4 latest Validate 2024.3 latest
2022.3 latest Validate 2024.3 latest
2022.2 latest Validate 2024.3 latest

Interoperability between releases

To take advantage of the latest improvements in Validate, we always recommend you upgrade your Server, Build, and Desktop Analysis plug-ins to the latest version of the product. Validate Server and Build Tools are compatible with the Desktop Analysis plug-ins within each major release.

Validate also provides the ability to load builds from the previous major version of Validate into the current version of Validate. For example, this means you can load builds from any version of Validate 2022 into Validate 2024.3 without having to import or migrate data.

If your current Validate server version does not meet the version requirements for importing projects, upgrade your existing version of Validate to a supported service release or version. Next, install the latest version of Validate. After you've installed the latest version of Validate, you can use it to connect to your existing Validate server and import your projects. Follow the steps described below to import your projects.

Install the Validate Server package

Install the Validate Server package. For instructions, see Installing Validate.

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 Validate, start the servers. Each projects_root running on a given machine must use different ports for its database and web/app servers than every other projects_root running on the same machine.

You can specify the unique hostname and port number combination during the installation or later, by using:

kwservice set-service-property <service-type> <property (host, port)> <value>

Validate your database (mandatory)

Using the 2023.1-2024.2 versions of the dbvalidate cleanup tool can result in data loss. If you run a database validation prior to upgrading and there are errors displayed, please open a support ticket.

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 Validate Server, so ensure that it is running.

Run the following command, for example:

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/validate/server/class/dbvalidate.jar --projects-root /local/tools/validate/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 2024 kw_central database (version: 95) validation started
<detected errors appear here>
Wed Jun 01 07:54:28 CDT 2024 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.

Log in to Validate

After starting the servers, Validate is accessible from a browser using the URL of the Validate server hostname and the Validate server port chosen during the install (for example, server21:8080). By default, the person who installed Validate is set as the Validate administrator, and is given the Projects root admin role. Initially, the Basic Authentication access control method is used, so no password is needed to log in. For example, if the user account used during the installation was ‘jsmith’, to log in to Validate with the administrator role, use the credentials:
username: jsmith
password: <empty>
For more details on security and authentication methods, see Security and permissions.

Import your projects and server settings

Since using the 2023.1-2024.2 versions of the dbvalidate cleanup tool can result in data loss, it is not recommended to run dbvalidate or dbvalidate cleanup. When upgrading from a previous version, it is suggested that you migrate using the documented procedure. If an issue arises after the upgrade, please raise a support ticket.

With the new Validate Server installed and the portal up and running, you can import server settings and projects from your existing Validate 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.

When importing server settings from a source Server A to target Server B, the following also applies:
  • 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.
In cases where a project contains custom settings, you must re-import your server settings after performing a project import.

Note that 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

  1. In the portal, click Validate and log in to the product as the Projects root admin user.
  2. 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.

  3. In the Validate server connection dialog, specify the log in and connection information for your existing Klocwork installation (the installation from which you want to import). These include:
    • The URL of the existing server, for example: http://server21:8082
    • If using basic, NIS or LDAP access control:
      • your user name. You must have Projects root admin rights in order connect to the server and import your projects.
      • your password (if required)
    • If using SAML or OIDC access control (release 2024.2 or newer):
      • an application token created in the source project. See Authentication using application tokens for more information.
  4. 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.

  5. Click List Projects to see a list of projects in your existing projects_root.
  6. In the Choose projects to import dialog, select the project(s) that you want to import to your new projects_root.

    Starting in release 2024.1, you can import projects repeatedly and import source projects with identical or similar names to those already on the target server. To facilitate this, you must specify a new name for the target project.

  7. 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.

  8. 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.
  9. 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_Validate_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 Validate 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 Validate Server.
  • sourceAdmin is the user id of the source Validate 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.

Starting in release 2024.1, you can import projects repeatedly and import source projects with identical or similar names to those already on the target server. To facilitate this, you must specify a new name for the target project by using the parameter newProjectName.

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.

Test your upgrade

Ensure that you can see your projects and builds in Validate.

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 Validate servers, taking care to specify the existing server port number for your new installation.

Before your first integration build analysis using Validate

New releases of Validate 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 Validate 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 Validate 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.