Extending delta data migration to include customizations

You can add custom forms to the Delta Data Migration package and migrate the data in these custom forms. You can migrate the data manually or with the Customer Form Instruction Generation tool.

You can also update a field mapping file to correct customer-defined fields in the BMC Remedy reserved range.

Manually adding custom forms to package

1. Open the Custom_Form_Instructions.xml instruction file in the <MigratorInstallDirectory>\DeltaDataMigration\Packages\Custom directory.
   The file contains information that is similar to the instructions XML example.

2. Provide your custom form name and the unique field IDs (unique index field IDs) in their respective tags.
   Follow the same process for all of the forms that you want to add.
   
   Custom_Form_Instructions.xml file: 

   <?xml version="1.0" encoding="UTF-8"?>
   <instructions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Migration Instructions.xsd">
   	<!-- This Example shows how you can migrate or compare data between one or more forms where a query or all data can be included.-->
   	<instruction enabled="true" name="Custom_Form_Instructions">
   		<data-instructions>
   			<!--	
   			<data enabled="true" source-form="" destination-form="" type="data" mode="search" merge-option="update" ignore-required-fields="true" ignore-pattern-matching="true" count="0" disable-related-workflow="true">
   				<qualification>PASS_QUALIFICATION</qualification>
   				<unique-fields>
   					<field id="1"/>					
   			</unique-fields>
   				<ports enabled="true" list="LIST_PORT" fast="FAST_PORT"/>
   			</data>
   		-->
   		</data-instructions>
   	</instruction>
   </instructions>

   Example of Custom_Form_Instructions.xml file after adding custom forms: 

   <?xml version="1.0" encoding="UTF-8"?>
   <instructions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Migration Instructions.xsd">
   	<instruction enabled="true" name="Custom_Form_Instructions">
   		<data-instructions>
   			<data enabled="true" source-form="HPD:Help Desk" destination-form="HPD:Help Desk" type="data" mode="search" merge-option="update" ignore-required-fields="true" ignore-pattern-matching="true" count="0" disable-related-workflow="true" ignore-request-id="false">
   				<qualification>PASS_QUALIFICATION</qualification>
   				<unique-fields>
   					<field id="1000000161" />
   					<field id="179" />
   				</unique-fields>
   				<ports enabled="true" list="LIST_PORT" fast="FAST_PORT" />
   			</data> 
   		</data-instructions>
   	</instruction>
   </instructions>

3. Open the Custom_Form_Package.xml package file in the <MigratorInstallDirectory>\DeltaDataMigration\Packages\Custom folder.

4. Provide the instruction XML file names in the package XML file:

   <instructions file="Custom_Form_Instructions.xml type="all" command="migrate" enabled="true">
   <instruction name="Custom_Form_Instructions"> </instructions>

5. Save the instruction and package XML files.
   You are now ready to run the migrate and compare scripts for the custom package. The new package will run in parallel in a separate command window in the same way as the Delta Data Migration out-of-the-box package files.

Adding custom forms to package by using the Customer Form Instruction Generation tool

If you do not have the list of your custom (non-BMC) regular forms, run the following batch files as outlined in the procedure for adding custom forms to a package by using the Custom Form Instruction Generation tool.

• The migratorFindCustomForms.bat utility — Finds all of your custom forms on the AR System server that are not recognized as BMC Software forms. The utility generates a CSV file that includes a list of all custom form names with their unique indexes.
• The migratorCSV2Instructions.bat utility — Uses the generated CSV file as the input, and creates a Custom_Form_Instructions.xml file for the custom forms in the CSV file.

To add custom forms to the package by using a Customer Form Instruction Generation tool

1. Navigate to <MigratorInstallDirectory>\Migrator\migrator\DeltaDataMigration\Utilities\migratorUtilities folder.

2. Run the migratorFindCustomForms utility by using the following syntax:

   migratorFindCustomForms.bat -s <sourceARServerName> -u <adminUserID> -p <adminPassword> -P <ARServerPort>

   
   For example:

   migratorFindCustomForms.bat -s test.bmc.com -u Demo -p "" -P 2020

3. Open the Customforms.csv output file in a text editor or spreadsheet application.
4. If a form is included in the list but should not be migrated, remove the entire line.
   Do not include forms that are used for testing or to keep temporary data. If you are not sure, it is better to include the form in the migration. Migrating a form multiple times is permitted.

   Note

   You can save the names of forms to be excluded in a separate file, and then use that file the next time you run migratorFindCustomForms.

5. Save the changes you made to the Customforms.csv file.

6. Run the migratorCSV2Instructions utility by using the following syntax:

   migratorCSV2Instructions.bat -i Customforms.csv

   
   For example:

   migratorCSV2Instructions.bat -i Customforms.csv

   This utility generates an instruction file that BMC Remedy Migrator reads and uses for the migration.

7. Verify that the output file is Custom_Form_Instructions.xml.
8. Open the Custom_Form_Instructions.xml file, and ensure that the name inside of the xml file has the same name "Custom_Form_Instructions."
9. Copy the Custom_Form_Instructions.xml files to the Packages\Custom directory. (You can overwrite the same file in the directory.)
   The custom package is now ready to be used. On the Delta Data Migration Tool user interface, when you select Custom, this custom package is selected, and the migration for the custom forms is executed.

Updating a field mapping file if you ran ARCHGID utility before or during an upgrade

If you used the BMC Remedy AR System ARCHGID utility to to fix customer-defined fields in the BMC Remedy reserved range and a Field ID was updated, you must add the source and destination field mapping information in a field mapping .arm file.

The ARCHGID utility is not supported. For information about this utility, see  https://communities.bmc.com/communities/docs/DOC-19172 .

To create or update an .arm file and update the reference in the instruction XML file

1. In the packages folder, open the custom package folder.
2. Open the instruction file for which you will update form mapping information
   If you have more than one instruction file, open the file that contains the form for which delta data mapping is available.
3. Create a mapping (.arm) file and map the custom source field ID to the destination field ID (which has a new ID after you run the ARCHGID utility).
   The following figure shows an example of a mapping file:
   
4. Add the mapping file name to the form reference in the instruction file, as shown in the following example:
   

Where to go from here