Upgrade projects

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

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

Overview

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

Back up projects

When you run the repair or upgrade process, ALM performs changes on your projects to align them with the specifications for the current version of ALM. 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 ALM 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 ALM version, they may not be consistent with the specifications for the current version of ALM.

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 ALM 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, ALM may pause and prompt you for information when an error occurs. Instead, you can select to run the processes in silent mode. When running the processes in silent mode, ALM aborts the processes 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 ALM version.

After a project is upgraded, you can no longer use the project with a previous ALM version.

Back to top

Upgrade versions

The following table lists the latest ALM versions that support direct upgrade from previous ALM 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.x.x 24.1
16.x.x 24.1
17.x.x 24.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 of ALM. 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.

To define an exception file:

  1. Copy the SchemaExceptions.xml file from the ALM installation directory. By default, the file is located in <ALM 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>

    • For an extra view:

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

    • For an extra column:

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

    • For an extra sequence:

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

  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.

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:

    <ALM 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 ALM 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:

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

Prerequisites:

  • Back up your projects.

  • Repair the problems that cannot be fixed by ALM, 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

Upgrade projects

After a project is verified and repaired, you can proceed to upgrade it to the current ALM 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.

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

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

  4. 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 ALM 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>];

  4. On the ALM 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 ALM 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

See also: