Renaming the AR System server by using the rename utility

Use the AR System server Rename utility to rename an AR System server and to ensure that the server name used by the Mid Tier and the AR System server is the same. 

 Perform the following tasks by using the Rename utility:

• Scan the database for the AR System server name
• Replace the AR System server name in the specified forms and fields in the database.

Sequence of server name replacement tasks

Perform the server name replacement tasks in the following order:

1. Start the AR System server
2. Scan the database for the server name.
3. Replace the server name in the database. In a server group environment, perform this operation only on the primary AR System server. 
4. In a server group, restart the primary and secondary AR System server

Rename utility command and options

The AR System server Rename command-line utility (arsrename.bat or arsrename.sh) is available on the BMC Electronic Product Distribution (EPD) site (Support ID required).

Use the following command and its options to run the utility:

Run this utility in scan mode first to produce the output. Review the output and then proceed to run the utility in rename mode using this output.

The following table describes the arsrename command options, which can be used in any order in the command.

Scanning the database for the server name

Use the Rename utility to scan for the AR System server name or a token string in the database (regular forms, character and diary fields). For example, in a multitenant environment, you can use the utility to scan the database forms and fields for occurrences of the onbmc-s string in the AR System server name on the myARServer computer. At the command prompt, enter the following command:

The output of the scan operation is a CSV file (output.csv) that displays the results of the scan as a table consisting of the information shown in the following figure and described in the subsequent table:

Output of the scan operation

Running the scan in Fast mode indicates that only first 5000 entries are scanned as a sample to find presence of the old server name. If it is not found in first 5000 entries, such form is ignored from the output.This helps to scan faster when a form has thousands or millions of entries. However, use this option with caution since it may not replace server name in forms that have huge amount of data and server name missing from first 5000 entries.

Format of the inclusion-exclusion list

You can control the forms that are scanned by creating an inclusion-exclusion text file that contains the list of forms that you want to include in or exclude from the scan and the qualification that you want to set for the scan. The following sample code shows the format of the inclusion-exclusion list:

The following table describes the formats used in this file:

Exclusions from the scan operation

The scan operation ignores the following forms and fields during scanning:

• Archive forms
• Audit forms
• Reserved fields on any regular forms
  • Core fields with field IDs ranging from 1 to 99 (except field ID 8)
  • Distributed Server Option (DSO) fields with field IDs ranging from 300 to 322
  • Dynamic groups with IDs ranging from 60000 to 60999
  • Special fields
    
    • 112  (Access control)
    • 179 (GUID)
    • 160 (Locale)

• Server Statistics form                                
• AR System API Statistics form                                   
• AR System Service Statistics form                               
• AR System Service Statistics Configuration form                
• AR System Version Control: Object Modification Log form         
• AR System Version Control: Object Reservation Label form        
• AP:Detail form
• AP:Question-Comment-Info form
• Application Pending form
• AR System Email Error Logs form
• AR System Email Error Messages form
• AR System Email Messages form
• BPCU-Logs form

Replacing the server name in the database

Use the Rename utility to replace the AR System server name in the database. The replace operation takes a CSV file as an input and either completely or partially replaces the server names, depending upon the values specified in the input CSV file. The input.csv file is available in the AR_SERVER_HOME\artools\etc folder.

The input.csv file contains the information required to replace the server names in a tabular format with the same columns as the output.csv file. Use the input.csv file if you have not done any customizations to get the server name in any base field, overlay, or custom field.

The replace operation replaces only those forms or fields that have a Merge flag set to Y in the input.csv file. To handle special cases, specify Y in the Special (Y/N?) column of the input.csv file.

As an example, use the following command to replace the onbmc-s string with tenant1-onbmc-s:

Purge the server name in the server group metadata tables

Use the utility to clean up old server entries from the server group. Perform this step only on the primary server.

Purge the current server name in the following metadata tables: 

• servgrp_board
• servgrp_config
• servgrp_resources
• servgrp_userlic
• servgrp_ftslic
• servgrp_applic

Example: To use the utility and rename the production server database to any other server database

Before using the arsrename utility, you must manually change the database references in the ar.cfg (ar.conf) file.

1. Stop the test server.
2. Restore the database on the production server to the test server. 
3. Start the test server.

4. Run the arsrename utility with operation mode 1—Scan.

   Arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -f c:\data\output.csv -fsf 1 -fsv 5000 -tokens onbmc-s

5. Run the arsrename utility with operation mode 2—Replace string tokens. 

   arsrename -o 2 -tokens "onbmc-s=tenant1-onbmc-s" 

6. Restart the test server.

7. Run the arsrename utility with operation mode 7—Purge data from server group metadata tables.

   arsrename -x tenant1-onbmc-s -o 7 -u Demo -p "" -t 0

8. Restart the test server.