The Upgrade Process › Filestore and Search Index Location Changes

Filestore and Search Index Location Changes

Two significant changes to the 13.x and 14.1 upgrade process directly affect the filestore feature. The changes require you to act during the upgrade process to ensure that the filestore feature operates correctly after the upgrade.

Note: The actions are necessary only if your files are not stored in the database. If files are stored in the database, no action is required.

You can determine if your files are stored in the database using the Clarity System Administration (CSA) application. Log in to the application and navigate to the Documents and Search link under the Properties tab, then review the Store Files in Database property.

Important! If the database is not the filestore repository, action is required. Failure to follow the recommended steps can lead to permanent loss of the filestore contents.

The following changes were made to the upgrade process in Version 13:

• The upgrade process always installs to an empty destination folder. During the upgrade, files and folders that exist in the target installation folder are moved to a new location before the new files are installed. If the filestore folder is located in the runtime folder, it is moved with the other content (not recommended). If the filestore is located outside the runtime folder (the recommended configuration), the filestore location is not moved or copied from the backup location.
• The filestore and search index folder structures were altered to accommodate architectural changes in Version 13. This change requires action for all Version 13 and 14.1 upgrades, whether the filestore was located in the installation folder or not.

Your action depends on the following factors:

• Where the filestore was before the upgrade
• The target installation folder that is selected during the upgrade

The correction must be made immediately after the upgrade completes, before any files are added to the filestore. Any files added to the filestore before the correction is made must be manually preserved using the following steps:

1. Use CA Clarity PPM to retrieve the newly checked-in documents and save them to a temporary location on the file system.
2. Perform the steps for the appropriate use case (A, B, or C) presented in the following Upgrade Action.
3. To check the saved documents back into the CA Clarity PPM filestore, use CA Clarity PPM.
4. Execute the following commands from the <runtime>/bin folder:

   ‘admin search recreate-index-files’
   ‘admin search recreate-index-data’
   

Upgrade Action: Complete the filestore and search index correction procedure.

Before you start, create a backup of the filestore so that recovery is possible in the event of an unexpected problem. Your document store could be used before this procedure can be completed. If so, the newly included documents must be added back to the filestore after you complete the correction procedure.

The following use cases illustrate the actions to take. To determine the correct course of action, use the filestore location and target installation folder.

Use Case A

• Filestore location: The filestore was located in the CA Clarity PPM runtime folder before the upgrade.
• Target installation folder: The existing (preupgrade) CA Clarity PPM runtime folder was selected as the target installation folder.

Before the upgrade process ran, the file or index folder was in the <runtime> folder. The upgrade process moved the file or folder to a folder named <runtime>_prev based on the chosen upgrade or installation option. The move resulted in the file or index folder being located in the <runtime>_prev folder. The file or index folder must be moved from the <runtime>_prev folder to another location because any subsequent upgrade attempt deletes this folder.

Perform these steps for this use case:

1. If before the upgrade the filestore location was <runtime>/filestore, copy or move the folders under <runtime>_prev/filestore to a new path:

   <new directory>/filestore/clarity
   

   Where <new directory> is located outside of the upgrade resulting <runtime> directory. Having the location outside of the runtime folder follows best practices. Placing the folder outside the CA Clarity PPM installation directory also ensures that this process is not repeated when CA Clarity PPM is upgraded.

   Log in to the CSA application, navigate to the Documents and Search link under the Properties tab, and update the Filestore Directory location. For example, if the filestore path is <old clarity install directory>/filestore, modify the path to <new directory>/filestore.

   Note: Do not append ‘clarity’ to the path in the CSA. The CA Clarity PPM architecture adds this update internally.

2. If before the upgrade the search index directory location was <runtime>/searchindex, copy or move the folders under <runtime>_prev/searchindex to a new path:

   <new directory>/ searchindex /clarity 
   

   Where <new directory> is located outside of the upgrade resulting <runtime> directory. Having the location outside of the runtime folder follows best practices.

   Log in to the CSA application and navigate to the Documents and Search link under the Properties tab and update the Index Directory location. For example, if the filestore path is <old clarity install directory>/searchindex, modify the path to <new directory>/searchindex.

   Note: Do not append ‘clarity’ to the path in the CSA. The CA Clarity PPM architecture adds this update internally.

3. Execute the following command from the <runtime>/bin folder:

   ‘admin search recreate-index-files’
   ‘admin search recreate-index-data’
   

Use Case B

• Filestore location: The filestore was located in the runtime folder before the upgrade.
• Target installation folder: A new, empty folder was selected as the target install folder.

Before the upgrade process ran, the file or index folder was located in the <runtime> folder. The upgrade process produced a different folder named <new runtime>. This process was based on the upgrade or installation option to select a different folder for the upgrade result than the current one. This choice has resulted in the file or index folder being located in the <runtime> folder.

Perform these steps for this use case:

1. If before the upgrade the filestore location was <runtime>/filestore, copy or move the folders under <runtime>/filestore to a new path:

   <new directory>/filestore/clarity
   

   Where <new directory> is located outside of the upgrade resulting <runtime> directory. Having the location outside of the runtime folder follows best practices. Locating the folder outside the installation directory ensures that this process is not repeated in the future when CA Clarity PPM is upgraded.

   Log in to the CSA application and navigate to the Documents and Search link under the Properties tab and update the Filestore Directory location. For example, if the filestore path is <old clarity install directory>/filestore, modify the path to <new directory>/filestore.

   Note: Do not append ‘clarity’ to the path in the CSA. The CA Clarity PPM architecture adds this update internally.

2. If before the upgrade the search index directory location was <runtime>/searchindex, copy or move the folders under <runtime>/searchindex to a new path:

    <new directory>/ searchindex /clarity 
   

   Where <new directory> is located outside the upgrade resulting <runtime> directory. Having the location outside the runtime folder follows best practices.

   Log in to the CSA application, navigate to the Documents and Search link under the Properties tab, and update the Index Directory location. For example, if the filestore path is <old clarity install directory>/searchindex, modify the path to <new directory>/searchindex.

   Note: Do not append ‘clarity’ to the path in the CSA. The CA Clarity PPM architecture adds this update internally.

3. Execute the following command from the <runtime>/bin folder:

   ‘admin search recreate-index-files’
   ‘admin search recreate-index-data’
   

Use Case C

• Filestore location: The filestore was located outside the runtime folder before the upgrade.
• Target installation folder: The target installation folder is not relevant to this use case. These steps must be performed for all upgrades with an external filestore.

The file or index folder is not located in the <runtime> folder.

Perform these steps for this use case:

1. If the previous filestore folder path is now located in <some folder>/filestore, copy or move the folders under <some folder>/filestore to a new path:

   <some folder>/filestore/clarity
   

2. If the previous search index folder path is now located in <some folder>/searchindex, copy or move the folders under <some folder>/seachindex to a new path:

   <some folder>/seachindex/clarity
   

3. Execute the following command from the <runtime>/bin folder:

   ‘admin search recreate-index-files’
   ‘admin search recreate-index-data’
   

No modification to the Filestore Directory or Index Directory properties is needed. You can view these properties from the Properties tab, Documents and Search subtab in the CSA application.

Note: Do not append ‘clarity’ to the path in the CSA. The CA Clarity PPM architecture adds this update internally.