Moving your AR object customizations to a new target system

Use any of the following methods to migrate the AR system form and workflow customizations:

• Workflow Migration utility—Use the Workflow Migration utility to migrate customizations from any noncontainer source version. The utility migrates data by comparing the source AR System schema and the target AR System schema. It provides end-to-end automation of migration and reconciliation of AR System objects. 
  We recommend that you take a database backup as a restore point before running this utility. 
• Developer Studio—Use the Developer Studio to migrate specific AR System customizations from 9.x and later versions.
  
• Deployment Management console—Use the Deployment Management console to migrate customizations from 18.05 and later versions.
  Create a deployment package to migrate custom and overlay AR objects from source to the target systems.
• Packing lists—Use the packing lists to migrate custom and overlay AR objects from 18.05 and later versions.

Before you begin

Convert the overlays to granular overlays so that you minimize the number of overlays to reconcile.

For example, convert the following overlays:

• Overlay fields that are set to overwrite property with no field changes.
• Overlay objects property that are set to additive property with no object changes.
• Any discrepancy between overlay and base object.

See To convert overlays to granular overlays.

To convert overlays to granular overlays

Make sure that the latest customizations in your production environment are available in the development environment. In your development environment, perform the following steps to convert the overlays to granular overlays:

1. Open Developer Studio in the Best Practice Customization mode.
   
2. Open the object list and select the overlay object for which you need to convert overlays.
3. From the object's context menu, select Analyze Overlay > Object Granularity Level. 
   
   A report, similar to the following image, is displayed in the Analyzer Results tab: 
   
4. On the Analyzer Results tab, select all the objects, right click on the selection, and then select Fix Object Granularity Level.
   
   
5. Repeat steps 2 to 4 until you see zero results in the Analyzer Results tab. 
6. On the Filtering Options tab, select all overlay objects, right click, select Analyze Overlay, and then select Unmodified Fields in View.
   
   
   A report, similar to the following image, is displayed in the Analyzer Results tab: 
   
7. On the Analyzer Results tab, select all the results, right click, and then select Fix All Fields in All Views.
   
   
8. Repeat steps 6 to 7 until you see zero results in the Analyzer Results tab. 

To migrate customizations by using the Workflow Migration utility

Workflow Migration utility migrates the AR System object customizations and overlays, groups and roles data, and the synchronization of newly added classes or attributes to Asset forms. The utility provides end-to-end automation of entire migration and auto-reconciliation of AR System objects. The Workflow Migration utility creates a working directory. The working directory contains several folders such as CMDB, Customizations, and Recon. In these folders, you can find the xml, definitions, and arx files. Use the files to verify the migration. 

1. Run the Workflow Migration utility.
   See Migrating customized objects to a new target system in BMC Helix Innovation Suite documentation.

2. In the working directory of the Workflow Migration utility, in the Logs folder, in the MigarteCustomizations.log file, review the logs for any errors.
   The following image shows an example working directory:
   
   
3. If you find any errors in the MigarteCustomizations.log file, fix the errors, and then migrate the failed objects by using the Workflow Migration utility.
4. Review the count of objects migrated from the source to target system by checking the log files.
    For example, the groups.log file contains the count of groups that are migrated from the source to target system. The groups.arx file contains the groups.
   
5. Reconcile overlays by performing the automatic and three-way reconciliation.

To migrate customizations by using Developer Studio

Use Developer Studio to export and import AR System objects, where you can export to file system with extension .def and transfer file to destination and import.

Migrating customizations by using Developer Studio involves these two procedures:

1. Identify and export overlays and custom workflows to a definition file.
2. Import overlays and customer workflow from a definition file.

To export forms and workflows

1. Open Developer Studio and connect to the source system.
   Make sure you are using Best Practice Customization Mode.
2. Open the list of forms in your source system and sort by customization type.
   All custom and overlay objects are displayed at the top of the list.
3. Select all the overlay forms. Right-click and select Export To File.
   
4. In the Export dialog box, enter the name of the file you want to export.
   The selected overlay objects are saved to this file.
5. Repeat the steps 3 and 4 to create multiple files for each form type.
   First export all the custom and overlay regular forms. Then, export the join forms, display forms, and view forms respectively. 
6. Open the list of workflow objects in your source system and sort by customization type.
7. Select all the workflow objects. Then, right-click and select Export To File.
   
8. On the Export dialog box, enter the name of the file to which you want to export the objects, and click Export.
   
   
   
9. Repeat steps 5 to 7 for active links, filters, active link guides, filter guides, applications, web services, and menus.
   If you mention same file name for export, the options to overwrite or append are displayed. Select the Append option to export all the workflow objects to a single file. 
   

To import overlays and custom workflows from a definition file

1. Open Developer Studio and connect to target system.
   Make sure you are using Best Practice Development Mode.
2. Select File > Import.
3. In the dialog box, select Object Definitions, and click Next.
4. Select the server you want to import into and click Next.
5. Open the import definition file, and click Next to view the list of objects available for import.
   
   For forms with overlays, the underlying base form and the overlay are available in the definition file. The overlay is indicated with a " o" suffix. For example, an overlay of "AAS:Activity appears in the definition file  "AAS:Activity o".
   You must remove all instances of the base form or workflow from the list of objects when importing an overlay, else the base form is updated with the older version form definition.
6. If you encounter issues while importing only overlays (without associated base objects), perform the following steps:
   1. Export the base objects as a backup.
      
   2. Import both overlays and base objects.
      The latest version of base objects is replaced with the old version of base.

   3. Import the base objects exported in step a.
      

      Important

      The exported definition files include both overlays and base objects. Import only overlays and not the base objects so that the out-of-the-box base objects of the new BMC Helix ITSM version are not overwritten.

      For any import errors, use one of the following options:

      • Manually create the overlay in the new BMC Helix ITSM version.
        We recommend that you use this option.
      • Export and save the base object, and then reimport it to the new BMC Helix ITSM version after the overlay is successfully imported.
7. After you have configured the set of workflow to be imported, click Import.
   Do not overwrite any definitions in the target system unless you are attempting an import again.
8. Repeat steps 2 to 7 for each of your definition files to import rest of the objects such as filters, active links, guides, and menus.
   

To migrate customizations by using Deployment Management console

1. Log in to the AR System Deployment Management Console.
   See Accessing the AR System Deployment Management console in BMC Helix Innovation Suite documentation.

2. Define a package.
   Make sure that you specify the content type and add the definition files.
   See Defining a package in BMC Helix Innovation Suite documentation.
   The following image shows an example:
   
   

3. Build the package.
   See Building and deploying packages in BMC Helix Innovation Suite documentation.
   The following image shows an example:
   

4. Export the package from the source to target system.
   See Importing and exporting a package in BMC Helix Innovation Suite documentation.

5. Reconcile overlays by performing the automatic and three-way reconciliation.
   

To migrate customizations by using the packing lists

1. Log in to Developer Studio.
2. Perform the following steps to create a separate packing list for the following overlay objects:
   1. Create a packing list for regular forms.
   2. Create a packing list for all other forms.
   3. Create a packing list for workflow objects such as filters and active links.
3. Create separate packing lists for custom objects such as forms and workflows.

4. Export the packing lists.
   For information about creating and exporting packing lists, see Creating and managing packing lists in BMC Helix Innovation Suite documentation.

Example of creating a packing list for form overlays

1. Log in to Developer Studio.
2. Create a package with name Pack_Forms_Overlay, add all the overlay regular forms to the packing list, and save the packing list.
   
3. Open the Deployment Management console.
4. Create a deployment package, specify the Content type value as Add Packing List, the Include Object Type value as Overlay Only, and the Packing List Name value as Pack_Forms_Overlay.
   
5. In the Operations menu, click Build.
   After the build is complete successfully, the build status changes to Ready for Export.
6. In the Transfer Package menu, click Export.
   The ExportOverlaysonly_1.1.zip file is downloaded.
   

Automatic reconciliation

Use the Autorecon utility to perform automatic reconciliation. The Autorecon utility automatically reconciles nonconflicting AR object overlay changes. The utility generates the following output files:

• Report.csv file—This file contains the list of AR objects that need to be manually reconciled.
  The following image shows a sample report:
  
  
• Manual_Recon_List_<AR System server name>.xml file—Use this file while performing three-way reconciliation process of the AR objects.

Example of reconciliation through the Autorecon utility
In your current environment, you modify field properties by creating overlay on the field z1D_Service_newBase. In this base version, the Default Value and Pattern attributes are empty. You create an overlay and populate Default value test as shown in the following image:

In the latest version, out-of-the-box field properties that are modified in the base, Pattern = $UPPER$ and Default Value = SERVICE as shown in the following image:

The Autorecon utility fixes the nonconflicting attributes automatically and generates a report for these attributes. After you run autorecon utility, the Pattern attribute change is cascaded to overlay field. However, the Default value attribute base object has the value SERVICE and Overlay has value test. As you already modified the attribute Default Value in the overlay, autorecon utility does not cascade the base attribute properties due to a conflict as shown in the following image:

This difference is noted in the report.

You can run the Autorecon utility by using the following ways:

For information about how to run the Autorecon utility, see Analyzing the manual reconciliation effort by using the reconciliation report in BMC Helix Innovation Suite documentation.

Three-way reconciliation

Three-way reconciliation includes comparing the source version overlay with the target version overlay and base layer objects. 

Use the following files to perform the three-way reconciliation:

• If you have performed the automatic reconciliation by using the autorecon utility, use the report generated by the autorecon utility.
  
• If you have performed the automatic reconciliation by using the Workflow Migration utility, use the XML file located at <working directory>\Recon.
  The autorecon utility generates XML files for each object type such as forms and filters. Example file name: Forms_Manual_Recon_List_<Server Name>.xml
  

To perform the three-way reconciliation, see Comparing and reconciling objects in BMC Helix Innovation Suite documentation.

To analyze the reconciliation report

1. Unzip the Manual Recon Report.zip file.
2. From the unzipped files, open the Manual_Recon_List_*.xml file. 

3. Update the definition file (DEF) path to match the local file system path. 
   

   Important

   The XML file includes the path of the Jenkins environment.
   

4. Copy the XML file to the  Developer Studio workspace. 
5. Relaunch the Developer Studio and switch to the Best Practice Customization mode. 
6. In the AR System Navigator, expand  Recon Application. 
   The following image shows the Objects to Reconcile section: 
   
   
7. Click Objects to Reconcile.
   A report with the list of objects that need manual reconciliation is displayed. The following image shows a sample report:
   
8. After your analysis is complete, perform a manual object reconciliation of the objects. 
   To perform the reconciliation, double-click on each object and perform the manual reconciliation.

Where to go from here

Migrating-Remedy-on-premises-to-BMC-Helix-Service-Management-on-premises