Preserved files and folders when upgrading Cognos Analytics

You can install a new version of IBM® Cognos® Analytics over your current, running version of the product without overwriting configuration settings from the previous version.

Files to be preserved by default during an upgrade are listed in the install_location\configuration\preserve\.ca_base_preserve.txt file. Do not edit this file.

If you want to remove or preserve other files or directories when upgrading Cognos Analytics, edit the install_location\configuration\preserve\preserve.txt.template file. Instructions about using preserve.txt.template are included in the file itself. Then, rename the preserve.txt.template file to preserve.txt.

Tip: Hard or soft links that are created by customers within the Cognos Analytics file structure are not supported.

Files and folders preserved by default

By default, the following folders and files, as specified in the install_location\configuration\preserve\.ca_base_preserve.txt file, are preserved in the installation directory when upgrading Cognos Analytics:

################################################################
#
# IBM Confidential
#
# IBM Cognos Products: Preserve Files by the Install
#
# (C) Copyright IBM Corp. 2017, 2021
#
#
# DO NOT EDIT THIS FILE.
#
# Please use the file <installdir>/configuration/preserve/preserve.txt
# to list files/folders to be preserved during an upgrade installation.
#
################################################################

#exclude section must be done first
exclude:deployment/Samples_for_Install.zip
exclude:deployment/Templates.zip
exclude:webcontent/bi/images/cahome_icons.svg
exclude:webcontent/bi/images/authoring_icons.svg
exclude:webcontent/bi/images/admin_icons.svg
exclude:webcontent/bi/images/JupyterNotebook.svg

# Various folders
configuration/certs
configuration/csk
configuration/data
configuration/caSerial
configuration/preserve/preserve.txt
data/cmstorage
data/search
deployment
drivers
ldapschema
informix
war/AuditExt
webcontent/bi/images
webapps/p2pd/WEB-INF/AAA/lib
templates/ps/async/system.xml

# Miscellaneous files.
uninstall/cognos_ex.ldif
uninstall/logs/pre_upgrade.log
webapps/p2pd/WEB-INF/web.xml
wlp/usr/servers/cognosserver/bootstrap.properties
wlp/usr/servers/cognosserver/jvm.options
wlp/usr/servers/cognosserver/server.xml
wlp/usr/servers/dataset-service/bootstrap.properties
wlp/usr/servers/dataset-service/jvm.options
wlp/usr/servers/dataset-service/server.xml
wlpdropins/AuditExt.war
cgi-bin/web.config

# Configuration files
configuration/cogconfig.prefs
configuration/cogconfig_reg.txt
configuration/coglocale.xml
configuration/cogstartup.xml
configuration/c11AuditExtension.keystore
configuration/dispatcher.properties
configuration/install_gatewayurl.xml
configuration/installData.properties
configuration/ipfclientconfig.xml
configuration/configuration/caSerial
configuration/xqe.config.custom.xml
configuration/xqe.diagnosticlogging.xml
configuration/local-server.xml
configuration/Series7Namespaces.xml
configuration/Launch IBM Cognos Analytics.url
configuration/cjap_directory.json

# webcontent files
webcontent/web.config
webcontent/bi/web.config

Attention:

If you are running version 12.0.0, 12.0.1, or 12.0.2, the file .ca_base_preserve.text is missing some references to other files. You must fix this issue. However, you cannot edit the file .ca_base_preserve.txt. Instead, you create (or modify if it exists) a file named preserve.text.

Follow these steps:

Go to the folder install_location/configuration/preserve.
In a text editor, do one of the following:
- Open the file preserve.txt, if it already exists.
  or
- Open the file preserve.txt.template.

Add the following lines:

#TM1 files
templates/ps/portal/variables_TM1.xml
templates/ps/portal/variables_plan.xml
templates/ps/portal/icon_active_application.gif
webcontent/planning.html
webcontent/PMHub.html
webcontent/tm1/web/tm1web.html

#CA files
templates/ps/system.xml
templates/ps/portal/system.xml

Save the file as preserve.txt.

For more information, see The file .ca_base_preserve.txt is missing references to some files (existing issue).

You might need to manually migrate these files and folders under the following circumstances:

You are installing the new version in a new directory.
You are uninstalling the current version, and then installing the new version.
Uninstalling the current version completely deletes the install_location directory.

Preserving other files and folders in Cognos Analytics 11.2.1

In addition to the files and folders that are preserved by default, you can preserve other files in the Cognos Analytics installation directory when upgrading the product to a new version.

Use the install_location\configuration\preserve\preserve.txt.template file to specify the files that you want to preserve. For example, if you want to preserve the samples deployment install_location\deployment\IBM_Cognos_Mobile_Samples.zip, add deployment\IBM_Cognos_Mobile_Samples.zip to the list of preserved files in the preserve.txt.template file. Then, rename preserve.txt.template to preserve.txt.

When you upgrade Cognos Analytics, you can choose to preserve or overwrite the files that are specified in the preserve.txt file. Depending on your decision, the installation proceeds in one of the following ways:

You choose to preserve files.
New versions of files that are specified in the preserve.txt file are copied to the install_location\configuration\preserved-by-manifest\manifest_version directory. The .new extension is added to each file in this directory. For example, install_location\configuration\preserved-by-manifest\11.2.1-2108230833\IBM_Cognos_Mobile_Samples.zip.new.
You choose to not preserve files.
Old versions of files that are specified in the preserve.txt file are copied to the install_location\configuration\preserved-by-manifest\manifest_version directory. The .old extension is added to each file in this directory. For example, install_location\configuration\preserved-by-manifest\11.2.1-2108230833\IBM_Cognos_Mobile_Samples.zip.old.

Preserving other files and folders in Cognos Analytics 11.2.0

In addition to the files and folders that are preserved by default, you can preserve other files in the Cognos Analytics installation directory when upgrading the product to a new version.

When Cognos Analytics is upgraded, the files that you chose to preserve are not overwritten. If the new product version contains new versions of the preserved files, the new file versions are saved to the same directory under the name filename_manifestversion.new. Using the samples example, the install_location\deployment directory would contain the following files after the upgrade:

IBM_Cognos_Mobile_Samples.zip
This is the preserved samples deployment.
IBM_Cognos_Mobile_Samples.zip_manifestversion.new
This is the new, Cognos Analytics 11.2 version of the samples deployment.

For example, if the installer uses the manifest casrv-manifest-11.2.0-2104060200-linuxi38664h.json, the file name is IBM_Cognos_Mobile_Samples.zip_11.2.0_2104060200.new.