Verify, repair, upgrade, and restore projects

To work in the current version with projects created in a previous version, you must upgrade your projects to align them with the required configurations of the current version.

Before upgrading, verify and repair your projects to detect and correct errors in your database user schema and data.

In this topic:

• Overview
• Project upgrade path
• Back up projects
• Define an exception file
• Verify projects
• Repair projects
• Restore backed up projects
• Upgrade projects

Overview

Understand the following before you verify, repair, and upgrade projects.

Back up projects	When you run the repair or upgrade process, the system performs changes on your projects to align them with the specifications for the current version. You must back up your projects before you start to repair or upgrade them. The repair process makes changes to the project database schema only. Before running the repair process, you should back up the project database schema on the database server, but you do not need to back up the project data in the file system. Before you run the upgrade process, perform a full backup of your projects that includes the project database schema and the project data.
Define an exception file	If you have made changes to the schema such as the addition of tables or columns, the upgrade process may fail. You can define an exception file for objects that are added manually to the database user schema, and are not defined in the schema configuration file. This instructs the system to ignore these changes during the upgrade process. You must use the same exception file when running the verification, repair, or upgrade process. You can set an exception file for a single project or for all projects in Site Administration.
Verification process	You run the verification process to check the correctness of your database user schema and data. Although your database user schema and data may be correct for your previous version, they may not be consistent with the specifications for the current version. The verification process detects problems in your environment, settings, schema structure, and data integrity that could cause the upgrade to fail. It generates a verification log which informs you of problems that can be repaired by the system and problems that you should manually repair.
Repair process	The repair process fixes most data and schema issues found by the verification process. If the verification process detects problems that can cause data loss, the repair process does not fix these automatically. You need to repair these problems manually. To find out whether a particular issue is handled automatically or manually, refer to the verification log.
Repair/upgrade mode	By default, the repair and upgrade processes run in non-silent mode. When running the processes in non-silent mode, you may be prompted for information when an error occurs. Instead, you can select to run the processes in silent mode. When running the processes in silent mode, the processes are aborted without prompting you for input.
Use verified, repaired, or upgraded projects in a previous version	After a project is verified or repaired, you can still use it with a previous version. After a project is upgraded, you can no longer use the project with a previous version.

Back to top

Project upgrade path

The following table describes the latest versions to which you can directly upgrade projects from previous versions.

From versions	Latest version to support direct upgrade
11.0	12.2
11.5x	12.5
12.0	15.0
12.2	15.5
12.5x	16.0.x
12.6x	17.0.x
15.0.x	24.1
15.5.x	25.1
16.x.x	25.1
17.x.x	25.1
24.1.x	25.1

Back to top

Back up projects

A full backup of a project includes the backup of the project database schema and the backup of the project data.

The repair process makes changes to the project database schema only. Before running the repair process, you should back up the project database schema on the database server. You do not need to back up the project data in the file system.

Before you run the upgrade process, perform a full backup of your projects that includes the project database schema and the project data.

To back up the project database schema on the database server:

Microsoft SQL database	For information on backing up a schema on a Microsoft SQL database, see How to back up and restore MS SQL database.
Oracle database	For information on backing up a schema on an Oracle database, see How to export and import an Oracle database to dump files.

To back up the project data in the file system:

In the file system, ensure that all data, including automated tests scripts and results, and attachments, is saved in the project directory under the repository defined during the installation. Make a copy of this project directory including all subdirectories and files.

Back to top

Define an exception file

You can use the exception file to ignore warnings for extra tables, views, columns, and sequences. You can set an exception file for a single project or for all projects.

You must use the same exception file when running the verification, repair, or upgrade processes.

To define an exception file:

1. Copy the SchemaExceptions.xml file from the installation directory. By default, the file is located in <Installation path>\data\sa\DomsInfo\MaintenanceData.

2. Create the exception file, for example, my_exceptions.xml, and define the exceptions as follows:

   • For an extra table:

     Copy code

     <TableMissing>
              <object pattern="MY_Table" type="extra"/> 
     </TableMissing>Copy Code

   • For an extra view:

     Copy code

     <ViewMissing>
              <object pattern="MY_VIEW" type="extra"/> 
     </ViewMissing>Copy Code

   • For an extra column:

     Copy code

     <ColumnMissing>
              <object pattern="MY_COLUMN" type="extra"/> 
     </ColumnMissing>Copy Code

   • For an extra sequence:

     Copy code

     <SequenceMissing>
              <object pattern="MY_SEQUENCE" type="extra"/> 
     </SequenceMissing>Copy Code

3. To set an exception file for a single project:

   1. Open Site Administration > Projects tab.

   2. From the projects list, select a project.

   3. In the Details tab, Project Database section, Exception File field, enter the location of your exception file.

4. To set an exception file for all projects, add the UPGRADE_EXCEPTION_FILE parameter and define the exception file location.

   For details about configuring site parameters, see Set configuration parameters.

Back to top

Verify projects

You can run the verification process at the individual project level, or at the domain level to verify multiple or all projects in the domain.

Permission:

To verify a project, you should be site admin.

Verification process:

• Check the correctness of the database user schema and data in a project.

• Detect problems in your environment, settings, schema structure, and data integrity that could cause the upgrade to fail.

• Generate a verification report which alerts you to problems that can be repaired by OpenText Application Quality Management and problems that you should manually repair.

To verify an individual project:

1. Open Site Administration > Projects tab.

2. From the projects list, select the target project, and click Maintain Project > Verify Project.

3. Click Verify Project to start the verification process.

   If the project is still active, you are prompted to deactivate it first.

   If an error occurs while running the process, a message box opens. Click the Abort or Retry accordingly.

   To abort the verification process, click Abort and click Yes in the confirmation dialog box.

   To pause the verification process, click Pause. To continue, click Resume.

4. Wait until the verification process completes.

   When the verification process completes, the verification log is saved in the following directory:

   <Repository Path>\sa\DomsInfo\MaintenanceData\out\<Domain Name>\<Project Name>.

   To export the verification log to a text file, click Export Log.

   To clear the verification log, click Clear Log.

5. Analyze the verification log. The log indicates the problems that can be repaired by the system and the problems that you need to repair manually.

To verify multiple or all projects in a domain:

1. Open Site Administration > Projects tab.

2. From the projects list, select the target domain, and click Maintain Domain > Verify Domain.

3. Select the target projects or click the checkbox in the Project Name column to select all projects.

4. Click Verify Projects.

   If any of the selected projects are still active, you are prompted to deactivate them first.

   If an error occurs while running the process, a message box opens. Click the Abort or Retry accordingly.

   To abort the verification process, click Abort and click Yes in the confirmation dialog box.

   To pause the verification process, click Pause. To continue, click Resume.

5. Wait until the verification process completes.

   When the verification process completes, the verification log is saved in the following directory:

   <Repository Path>\sa\DomsInfo\MaintenanceData\out\<Domain Name>\<Project Name>.

   To export the verification log to a text file, click Export Log.

   To clear the verification log, click Clear Log.

6. Analyze the verification log. The log indicates the problems that can be repaired by the system and the problems that you need to repair manually.

Back to top

Repair projects

You can run the repair process at the individual project level, or at the domain level to repair multiple or all projects in the domain.

Repair overview

The repair process fixes most data and schema issues found by the verification process. If the verification process finds problems that can cause data loss, the repair process does not fix these automatically. You need to repair these problems manually.

To find out whether a particular issue is handled automatically or manually, refer to the verification report.

By default, the repair process runs in non-silent mode. When running the process in non-silent mode, you may be prompted for input when an error occurs. Instead, you can choose to run the process in silent mode. When an error occurs, the process is aborted without prompting you for input.

Prerequisites:

• Back up your projects.

• Repair the problems that cannot be fixed by the system, as indicated in your verification log. See Verify projects.

• To repair a project, you should be site admin.

To repair an individual project:

1. Open Site Administration > Projects tab.

2. From the projects list, select the target project, and click Maintain Project > Repair Project.

3. To run the repair process without any user interaction, select Run in Silent Mode.

4. To start the repair process, click Repair Project.

   If the project is still active, you are prompted to deactivate it first.

   If an error occurs while running the process, a message box opens. Click the Abort or Retry accordingly.

   To abort the repair process, click Abort and click Yes in the confirmation dialog box.

   To pause the repair process, click Pause. To continue, click Resume.

5. Wait until the repair process completes.

   To export the repair log to a text file, click Export Log.

   To clear the repair log, click Clear Log.

To repair multiple or all projects in a domain:

1. Open Site Administration > Projects tab.

2. From the projects list, select the target domain, and click Maintain Domain > Repair Domain.

3. Configure the repair settings.

   Repair Mode	Select the following options: Run in silent mode. Runs the process without any user interaction. Continue to next project if failed. Proceeds to the next project if the repair process fails. This is the default option.
   After the Repair	Select one of the following options: Leave all projects deactivated. Leaves all projects deactivated after the repair process completes. Activate only currently active projects. Reactivates previously-activated projects after the repair process completes. This is the default option. Activate all projects. Activates all projects after the repair process completes.

4. Select the target projects or click the checkbox in the Project Name column to select all projects.

5. Click Repair Projects.

   If any of the selected projects are still active, you are prompted to deactivate them first.

   If an error occurs while running the process, a message box opens. Click the Abort or Retry accordingly.

   To abort the repair process, click Abort and click Yes in the confirmation dialog box.

   To pause the repair process, click Pause. To continue, click Resume.

6. Wait until the repair process completes.

   To export the repair log to a text file, click Export Log.

   To clear the repair log, click Clear Log.

Back to top

Restore backed up projects

If the repair or upgrade process fails, you must restore the backed up projects before trying the process again. A project you restore can be used only in the version from which it was backed up.

To restore a project from a Microsoft SQL database server:

1. From the SQL Server Enterprise Manager, navigate to the database and select Tools > Restore Database.

2. Navigate to the backup file, and follow the restore procedure to complete the data restore process.

3. To align the td user on the new database server, run the following SQL commands on every restored schema (site administration, lab_project, and each project schema):

   Copy code

   EXEC sp_change_users_login 'Report'
   EXEC sp_change_users_login 'Update_One', 'td', 'td'
   EXEC sp_changedbowner 'td_admin'Copy Code

   Note: td_admin is the database administration user with the appropriate required database privileges.

4. In Site Administration, restore access to the project. If you are restoring your project from a different directory, or if you renamed your schema, you must update the dbid.xml file accordingly. For details, see Restore access to a project.

5. If the backup was performed while the project was active, realign the project repository. For details, see Realign a repository.

To restore a project from an Oracle database server:

1. Copy the backup file to the Oracle server machine.

2. Using the SQL*Plus utility, log in to the Oracle server using the system account.

3. Create a user for the project. Make sure you create it with the same name as the project name (or the Oracle user name) when the project was exported.

   Use these SQL statements:

   Copy code

   CREATE USER [<project name>] IDENTIFIED BY tdtdtd DEFAULT TABLESPACE TD_data TEMPORARY TABLESPACE TD_TEMP;
   
   GRANT CONNECT,RESOURCE TO [<project name>];Copy Code

4. On the installation DVD, locate the \Utilities\Databases\Scripts directory. Open the qc_project_db___oracle.sql file and follow the instructions.

5. Using the command line, type imp to run the import utility.

6. Follow the prompt, and log in to the Oracle server using the system account. Make sure you import all the dump files.

   After all tables have been successfully imported, a confirmation message displays.

7. In Site Administration, restore access to the project. If you are restoring your project from a different directory, or if you renamed your schema, you must update the dbid.xml file accordingly. For details, see Restore access to a project.

8. If the backup was performed while the project was active, realign the project repository. For details, see Realign a repository.

To restore a repository from the file system:

1. Copy the backed up repository to the repository.

2. In Site Administration, restore access to the project. If you are restoring your project from a different directory, or if you renamed your schema, you must update the dbid.xml file accordingly. For details, see Restore access to a project.

3. If the backup was performed while the project was active, realign the project repository. For details, see Realign a repository.

Back to top

Upgrade projects

After a project from an earlier version is available from the project list, you can proceed to upgrade it to the current version.

You can run the upgrade process at the individual project level, or at the domain level to upgrade multiple or all projects in the domain.

Upgrade overview

By default, the upgrade process runs in non-silent mode. When running the process in non-silent mode, you may be prompted for input when an error occurs. Instead, you can choose to run the process in silent mode. When running the process in silent mode, the process is aborted without prompting you for input.

After the project has been upgraded, you can no longer use the project with a previous version.

Make sure of the following before the upgrade:

• During the upgrade process, the project directory must be accessible. For example, if your project directory is located on a file server, ensure that the server is running and accessible.

• During the upgrade process, no database maintenance jobs can be run. Running database maintenance jobs can cause the upgrade to fail and can corrupt projects.

• l If a project has extensions enabled, the availability of these extensions on the new server must be verified before upgrading. If any extension is not available on the new server, the upgrade fails.

• You must first upgrade a template project before upgrading any of its linked projects. If the template project and its linked projects are in different databases, ensure that the template project’s database is accessible when updating any linked projects.

• Version Control: Version control enabled projects cannot be upgraded while there are checked out entities. All entities must be checked in to the corresponding version.

Permission:

To upgrade a project, you should be site admin.

To upgrade an individual project:

1. Open Site Administration > Projects tab.

2. From the projects list, select the target project, and click Maintain Project > Upgrade Project.

3. To run the upgrade process without any user interaction, select Run in Silent Mode.

4. To start the upgrade process, click Upgrade Project.

   If the project is still active, you are prompted to deactivate it first.

   If an error occurs while running the process, a message box opens. Click the Abort or Retry accordingly.

   To abort the upgrade process, click Abort and click Yes in the confirmation dialog box.

   To pause the upgrade process, click Pause. To continue, click Resume.

5. Wait until the upgrade process completes.

   To export the repair log to a text file, click Export Log.

   To clear the repair log, click Clear Log.

To upgrade multiple or all projects in a domain:

1. Open Site Administration > Projects tab.

2. From the projects list, select the target domain, and click Maintain Domain > Upgrade Domain.

3. Configure the upgrade settings.

   Repair Mode	Select the following options: Run in silent mode. Runs the process without any user interaction. Continue to next project if failed. Proceeds to the next project if the repair process fails. This is the default option.
   After the Repair	Select one of the following options: Leave all projects deactivated. Leaves all projects deactivated after the upgrade process completes. Activate only currently active projects. Reactivates previously-activated projects after the upgrade process completes. This is the default option. Activate all projects. Activates all projects after the upgrade process completes.

4. Select the target projects or click the checkbox in the Project Name column to select all projects.

5. Click Upgrade Projects.

   If any of the selected projects are still active, you are prompted to deactivate them first.

   If an error occurs while running the process, a message box opens. Click the Abort or Retry accordingly.

   To abort the upgrade process, click Abort and click Yes in the confirmation dialog box.

   To pause the upgrade process, click Pause. To continue, click Resume.

6. Wait until the upgrade process completes.

   To export the upgrade log to a text file, click Export Log.

   To clear the upgrade log, click Clear Log.

Back to top

See also:

• Upgrade projects using ALM Robot
• Manage project repository
• Understand project structure