Migrating customized objects to a new target system

The following flowchart illustrates the steps in the migration process:

Scenario: Migrating customized BMC Helix CMDB and ITSM objects to a new out-of-the-box target system

Before you begin

If you have created any object in the Base Development mode, convert it to a custom overlay object before running the Workflow Migration utility.

To move customized BMC Helix ITSM objects to the target environment

1. On the BMC Electronic Product Distribution (EPD) site, from Products, select BMC Helix Innovation Suite OnPrem.

2. Select the latest version.
   The following screenshot shows the version.
   
3. From the Product tab, select Workflow Migration utility <version>.
   The following screenshot shows the Workflow Migration utility:
   
4. Click Download.
   Download the Windows or Linux file as per your requirement.
5. Save the Workflow Migration utility on your local server that you use for migrating objects and where you have other clients such as  Developer Studio installed.
6. Unzip the file.
   The Workflow Migration utility creates the following folders. You must store all these files in the same location:
   • CDMChecker
   • ReconReportUtility
   • The utility jar file migratecustomizations-21.30.00-SNAPSHOT.jar.
7. Open the command prompt.
8. Change to the directory where the Workflow Migration utility is saved.
9. Run the following utility at the command prompt:
   Syntax

   java
   -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
   -jar migratecustomizations-21.30.00-SNAPSHOT.jar
   -hsrc
   -usrc  
   -pwdsrc  
   -psrc  
   -hdest
   -udest  
   -pwddest
   -pdest  
   -o  
   -op
   -stp
   -sngl 

   Example

   java
   -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
   -jar migratecustomizations-21.30.00-SNAPSHOT.jar
   -hsrc sourceServer
   -usrc tester
   -pwdsrc tester
   -psrc 0
   -hdest targetServer
   -udest tester
   -pwddest tester
   -pdest 0
   -o WorkingDirectory
   -op migrate
   -stp 0
   -sngl true 

   Important

   If you use Java version 17 and the Workflow Migration utility generates any errors during the migration process, make sure to include the following parameter before the parser in the command:
   java -illegal-access=warn --add-opens=java.base/java.lang=ALL-UNNAMED
   Example:
   Java
   -illegal-access=warn ~-~-add-opens=java.base/java.lang=ALL-UNNAMED
   -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl (%%) 

   The following table shows the details of the parameters used in the command:

   Parameter	Description
   -Djavax.xml.parsers.SAXParserFactory	Instruction to load the correct parser.
   -jar migratecustomizations-21.30.00-SNAPSHOT.jar	Workflow Migration utility JAR file name.
   -hsrc	The source server from where you are migrating objects.
   -usrc	Admin user login name on the source server.
   -pwdsrc	Admin user password on the source server.
   -psrc	The source server TCP port.
   -hdest	The target server where you want to migrate objects.
   -udest	Admin user login name on the destination server.
   -pwddest	Admin user password on the target server.
   -pdest	The target server TCP port.
   -o	Output directory. The Workflow Migration utility uses this directory to store migration artifacts and logs. You must provide a fully qualified path. Best practice: We recommend using the working directory at the same location where the CDMChecker, ReconReportUtility, and the Workflow Migration utility JAR files are stored.
   -op	Perform the migrate operation.
   -stp	This optional parameter indicates the step from where the utility run starts. The valid values are as follows: 0 — Default value 1 — Migrate groups and roles 2 — Migrate BMC Helix CMDB 3 — Validate  BMC Helix CMDB 4 — Migrate missing base mode objects 5 — Export overlaid objects 6 — Migrate overlaid regular forms 7 — Migrate unions 8 — Sync the user interface in order to sync BMC Helix CMDB with BMC Helix ITSM: Asset Management  9 — Migrate Join form, vendor forms, and workflow overlays 10 — Migrate automatically generated objects 11 — Validate if all overlay objects are migrated 12 — Run the Reconciliation utility to reconcile objects. For more information, see Analyzing-the-manual-reconciliation-effort-by-using-the-reconciliation-report and Reconciling-customized-Developer-Studio-form-views.
   -sngl	Use this optional parameter when you want to run one step, defined in the -stp parameter. Valid values: True — Run the Workflow Migration utility in a single-step mode. False — Do not run the Workflow Migration utility in a single-step mode Important: When you set this parameter to True and define the step number with the -stp parameter, the utility runs the specified step and exits.

    

Object migration is successful when the Workflow Migration utility run completes without any errors.

Best practices for migrating all customized objects

Follow these best practices when running the Workflow Migration utility to migrate all customized objects:

• To migrate all customized objects, run the Workflow Migration utility with the following parameters:

  Example of running the workflow migration utility to migrate all customized objects

  java
  -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
  -jar migratecustomizations-21.30.00-SNAPSHOT.jar
  -hsrc sourceServer
  -usrc tester
  -pwdsrc tester
  -psrc 0
  -hdest targetServer
  -udest tester
  -pwddest tester
  -pdest 0
  -o WorkingDirectory
  -op migrate   
• The Workflow Migration utility creates a log directory that captures logs. The logs are stored in the folder where you have stored the Workflow Migration utility. Therefore, do not change the working directory where the Workflow Migration utility is stored.
• Check the log files for detailed error messages if the utility generates any errors or warnings during migration. Common issues include conflicting field names, missing fields, and corrupted forms. The log files provide information about the root cause of the errors and the steps to fix them. 

Best practices for migrating one object at a time

Follow these best practices when running the Workflow Migration utility to migrate one object at a time.

• Use the -stp parameter to migrate one object at a time.
  See the example below:​​​​

  Example of migrating one object at a time

  java
  -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
  -jar migratecustomizations-21.30.00-SNAPSHOT.jar
  -hsrc sourceServer
  -usrc tester
  -pwdsrc tester
  -psrc 0
  -hdest targetServer
  -udest tester
  -pwddest tester
  -pdest 0
  -o WorkingDirectory
  -op migrate
  -stp 1
  -sngl false 

• ​​Do not skip the sequence while running the utility.
• If the utility generates any errors or warnings, we recommend fixing those errors by reviewing the log files stored in your working directory.
• You can rerun the utility from the failed step. However, we recommend not to rerun step 1, to migrate groups and roles.