Import your existing projects into a new projects root
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 Validate 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 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 |
|---|---|
| 2023.4 latest | Validate 2024.1 latest |
| 2023.3 latest | Validate 2024.1 latest |
| 2023.2 latest | Validate 2024.1 latest |
| 2023.1 latest | Validate 2024.1 latest |
| 2022.4 latest | Validate 2024.1 latest |
| 2022.3 latest | Validate 2024.1 latest |
| 2022.2 latest | Validate 2024.1 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.1without 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 installation of Validate 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.
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 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 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 Validate
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 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.
- 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.
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
- In the portal, click Validate 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 Validate server connection dialog, specify the log in and connection information for your existing Validate 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.
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.
-
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_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.
