Keeping user preferences when moving the underlying Rational Synergy database to another server in Rational Change

Technote (FAQ)


How do you preserve the user preferences for IBM Rational Change when you change the database path?


All user preferences defined in Rational Change are stored in the IBM Rational Directory Server (RDS). These are stored using the database path as a reference. When you change the database path you must change the database path stored in RDS or the user looses their preferences.


NOTE: When the path to the database remains unchanged on the new host , then you don't need to perform any action.

WARNING: Before proceeding with this procedure, please take note of the following scenario:

  1. Database is upgraded and accessible to Change users

  2. Database path has changed.

  3. PreferenceNameSubstitutionForAllUsers has not been run yet.

  4. One or many users create some preferences (reports or queries) in the the new database.

  5. Thereafter, if PreferenceNameSubstitutionForAllUsers is run, the following will happen:

    1. Preferences referring to the old database path will not be converted to the new database path.

    2. Those preferences referring to the old database path are deleted.

  6. To avoid this situation, run PreferenceNameSubstitutionForAllUsers before users have access to the new database path and have created any preferences.

If the path to the database changes, then you need to update the identifier for the group of settings inside RDS. This is done using a Perl script that will call the PreferenceNameSubstitutionForAllUsers function.

This script is also used in Technote 1383359: How to migrate user ids and preferences from Change 4.7 to Change 5.1

IMPORTANT NOTE: Be aware that the function to establish a connection has changed in Change 5.2.

The updated script for Change 5.2 or 5.3 would be :


All source code and/or binaries attached to this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

    my $csapi = new ChangeSynergy::csapi();
    http://server:port/change ");my $aUser = $csapi->Login("admin", "adminpassword", "Admin","\\\\server\\myOLDdatabasepath");
       $tmpData = $csapi->
    PreferenceNameSubstitutionForAllUsers ($aUser,"\\\\server\\myOLDdatabasepath", "\\\\server\\myNEWdatabasepath");
       print $tmpData->getResponseData();

    if ($@)
      print $@;

Notes :
  • admin is Rational Change's admin account. You might be using another one.
  • adminpassword: password for user "admin"
  • Admin refers to a role. You must leave it this way.

Document information

More support for:

Rational Change

Software version:

5.2,,,, 5.3, 5.3.1

Operating system(s):

AIX, Linux, Solaris, Windows

Reference #:


Modified date:


Translate my page

Content navigation