Migrating customized objects to a new target system

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.

1. 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 

   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 — Reconcile objects
   -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

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.
• If the utility generates any errors or warnings, we recommend fixing those errors. 

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. Also, you can rerun the utility from the step it has failed.