Finding whether and where fields are used in the system

When you upgrade to BMC Remedy IT Service Management 8.0, several BMC Atrium CMDB attributes in the BMC.CORE:BMC_BaseElement form are migrated to the BMC Remedy ITSM Foundation. The migration process is as follows:

The upgrade imports a new form — AST:Attributes. This form is the new home for the migrated fields.
All the data saved in these fields on the BMC.CORE:BMC_BaseElement form in the production dataset is copied to the corresponding entries in the AST:Attributes form.
The attributes in the BMC.CORE:BMC_BaseElement form are deleted (during the installation Phase 3 or at a later date of your choice).

Although this process is designed to smoothly transition data into the new data model, it might cause issues if customizations were made with the fields that will be deleted in the BMC.CORE:BMC_BaseElement form. These customizations might no longer function as expected after the fields are removed. BMC recommends that you look for any existing customizations that refer to those fields before you upgrade, and plan how to fix or remove these customizations. The following procedures describe how to locate any potential customizations that refer to deprecated fields:

To enable recording object relationships

If you have not already done so, enable recording of object relationships.

In a browser, log on to the BMC Remedy Action Request System (AR System).
Select Applications > BMC Remedy AR System Administration Console.
On the BMC Remedy AR System Administration Console, select System > General > Server Information.
On the Configuration tab, select the Record Object Relationships box, as shown in the following figure.
Click Apply.
Click OK.
Note

You must restart the server for this change to take effect.

To determine whether and where a field is used in the system

Open BMC Remedy Developer Studio.
Log on and connect to your Server.
Open the BMC.CORE:BMC_BaseElement.
On the Search Results tab, select a field.
Right-click the field and select Show Relationships.
In the Relationship tab, the use of the field in various places, such as, active links, filters, other forms (for example, table field references), menus, web services, and Distributed Server Option (DSO) mappings, is displayed. You can see if any custom changes currently depend on this field.

To execute the cimig.jar manually for the pre-checking functionality

Copy the cimig.jar file to the C:\Program Files\Java\jdk1.6.x_xx\bin folder. The cimig.jarfile is in:
- (Microsoft Windows) <Installation folder>\Workflow\phase1\applications\raf\workflow\en
- (UNIX) <Installation folder>/Workflow/phase1/applications/raf/workflow/en/
Copy the following JAR files to the C:\Program Files\Java\jdk1.6.x_xx\jre\lib\extfolder:
1. log4j-1.2.14.jar (OR log4j-1.2.16.jar)
  This jar file is located at C:\Program Files\BMC Software\ARSystem\midtier\WEB-INF\lib. If you do not find the JAR file, download the file from http://logging.apache.org/log4j/1.2/download.html.
2. arapi80_build001.jar
  This JAR file is located at C:\Program Files\BMC Software\ARSystem\Arserver\api\lib.
Open the command prompt, keep the current directory as C:\Program Files\Java\jdk1.6.x_xx\bin.
Execute the command for your installed version as shown in Using the CI Data Migration Utility scan functions. Include the following parameters:
- LogFilePathName
- ARServerName
- TCPPort
- UserName
- Password
- ChunkSize
- exposeForPreChecking

Using the CI Data Migration Utility scan functions

The CI Data Migration Utility is a Java application called cimig.jar, which is available for the BMC Remedy IT Service Management upgrade. To use the scan functions, execute this JAR file from the command line by using the following command: java -jar cimig.jar params

The cimig.jar command line syntax is as follows:
cimig.jar LogFilePathName ARServerName TCPPort UserName Password ChunkSize exposeForPreChecking fndVersion

The following text replaces the syntax shown above:

Version 8.1.00:
cimig.jar LogFilePathName ARServerName TCPPort UserName PasswordChunkSizeexposeForPreChecking fndVersion

Service Pack 1 for version 8.1.00:

1. Copy the cimig.jar, log4j-1.2.14.jar, and arapi80_build001.jar files.
2. Set the following properties using command prompt:
  - ```
  export classpath=<jdk>/bin/cimig.jar:/usr/
  <jdk>jre/lib/ext/arapi81_build001.jar:/usr/
  jdk1.7.0_40/jre/lib/ext/log4j-1.2.14.jar:
  /usr/jdk1.7.0_40/jre/lib/ext/
```
  For example:
```
  export classpath=/usr/jdk1.7.0_40/bin/cimig.jar:/usr/
  jdk1.7.0_40/jre/lib/ext/arapi81_build001.jar:/usr/
  jdk1.7.0_40/jre/lib/ext/log4j-1.2.14.jar:
  /usr/jdk1.7.0_40/jre/lib/ext/
```
- ```
export JAVA_HOME=<jdk>
```
    For example:
```
/usr/jdk1.7.0_40/
```
  - ```
  export PATH=$JAVA_HOME/bin:$PATH
```
- ```
export classpath=$classpath:$JAVA_HOME/lib
```
  - If your default tmp does not have, write permissions, excute the following command in the same session:
```
 
```
```
export _JAVA_OPTIONS= -Djava.io.tmpdir=< path with write permissions >
```
3. In the same command prompt session, set the current directory to <jdk/jre>/bin.
4. In the same command prompt session, run the following command:
```
java -classpath $classpath com.bmc.itsm.raf.attribmigration.
CIAttribDataMigration 
-lf LogFilePathName -x ARServerName -t TCPPort -u UserName 
-p Password -a AuthString -s ChunkSize -check 
exposeForPreChecking 
-rv fndVersion 
```
```
 
```
  For example:
```
 
```
```
java -classpath $classpath com.bmc.itsm.raf.attribmigration.
CIAttribDataMigration  
-lf /usr/jdk1.7.0_40/jre/lib/ext/DMU.txt 
-x vl-abc-rem-qa -t 0 -u Demo -p "" 
-s 1000 -check 1  -rv "7.6.04.020000"
```
  where -lf , -x, -t, -u, -p, -a, -s, -check, and -rv are the options that identify each parameter to the utility. The addition of these options enables you to provide parameter values in any order.
  
  Note
  
  As of Service Pack 1 for version 8.1.00, if you enter the command incorrectly, the utility automatically displays information to help you to correct the syntax.
  The meaning of each parameter in the command line is as follows:
  - LogFilePathName – Fully qualified log file name. If a log file cannot be created, then the default log file CIDataMig.log is created in the current directory.
  - ARServerName — BMC Remedy AR System Server name
  - TCPPort — BMC Remedy AR System Server port number. If no port number should be used, use "0" as the port number.
  - UserName — User logon ID
  - Password — User password. If the password is blank, use "" .
  - ChunkSize — Optional chunk size for copying data. The default is 1000.
  - exposeForPreChecking — Use one of the following values:
    - 2 — Indicates that only the pre-checking is wanted, data is not to be copied. (This can be used before or after copying the data.)
    - 3 — Indicates that the user only wants to scan for invalid field mappings
    - 4 — Indicates that user wants to fix the custom self join structure
  - fndVersion — BMC Remedy ITSM Foundation version
  - AuthString — (Requires Service Pack 1 for version 8.1.00) The authorization string that you configured while setting up the BMC Remedy AR System Server.

Return codes

The utility returns the following return codes:

0 — Operational success
1 — Operational failure
2 — Operational success, but found Custom Object References to the ITSM attributes being removed from BMC.CORE:BMC_BaseElement form
3 — Invalid field mappings in self join forms were found, and must be fixed.
4 — Invalid field mappings were found, along with data copy exceptions, and other operational failures.
Note
As of Service Pack 1 for version 8.1.00, the utility uses the following terms while logging invalid field mappings (return codes 3 and 4):
- Source Field ID — Field ID on the original form.
- Database Field ID — FIeld ID on the join form

During the upgrade

Phase 1 — The upgrade installer will send a parameter to suppress scan functionality and will run the functions to prepare and copy the data. For example, the installer uses the value 1 for exposeForPreChecking input parameter.

In phase 1 the utility prepares and copies the data but it does not scan for custom objects (upstream custom joins or references to custom workflow). The return code after phase 1 of the upgrade is either 0 (operational success), or 1 (operational failure), because this phase only copies the data without scanning for the custom object references.

For phase 3 the default option for Attribute deletion will be "No".

Note

Before running the utility manually to scan custom object references, you must first enable "Record Object Relationship" in the AR System Server, and re-start the AR System Server service. When running the utility manually, if the utility finds any references for the custom objects then the return code is 2.

For more information, see To enable recording object relationships.

Log file information

The utility first logs information about how the data is going to be copied as follows:

Scanning and then copying the data.
Copying the data without scanning for custom object references.
Scanning for the custom object references without copying the data according to what parameter value is passed in for the utility; the default being 1 (copying the data without scanning for the custom object references). The remaining information is about the parameters used in executing the utility, the flow of the utility, information about the references found in the manual run, the record count that is copied, finally the return(exit) code.
CIDataMig.log is the log file generated from running cimig.jar. By default, the log file can be found in the BMCRemedyITSMSuite Logs folder.

Depending on the BMC Remedy IT Service Management version being upgraded, some forms might not be listed as present in the server in the section for Checking the BMC Remedy IT Service Management fieldMappings. This is acceptable, because the forms do not exist in the starting version. The added forms are:

Forms added to BMC Remedy IT Service Management 7.5.x:
- AST:ConcreteCollection
- AST:ResourceAllocationSettingData
- AST:ResourcePool
- AST:Transaction
- AST:VirtualSystemSettingData
Form added to BMC Remedy IT Service Management 7.6.04:
- AST:ServiceOfferingInstance
  Note
  - As of Service Pack 1 for version 8.1.00, the utility will give a new generic error message:
    Exception during the Asset Attributes operations! (A Null in the message indicates that there is probably a null pointer exception)
  - If the log file is not created due to an error, the utility saves the error messages in the bmcremedyitsmsuite_install_log.txt file, which is located in the %Temp% folder. An example of such an error message is provided below:
    
    Cannot initialize log file C:\CIDataMig.log
    ERROR: Couldn't get lock for C:\CIDataMig.log