Migrating customizations using Workflow Migration Utility

Scenario: Migrating customized  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  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  3 — Validate   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  with   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. For information about reconciling objects, see Analyzing-the-manual-reconciliation-effort-by-using-the-reconciliation-report. Important: If an issue occurs while obtaining the reconciliation report, perform the steps described in the Troubleshooting issues when generating the reconciliation report section.
   -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 true 
• 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.

Troubleshooting issues when generating the reconciliation report

Symptom

The following error occurs:

Scope

When your run the workflow migration utility with the -stp 12 parameter to generate the reconciliation report.

Workaround

1. Open command prompt.

2. Run the following command:

   Command syntax

   java
   -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
   -jar migratecustomizations-99.0.00-SNAPSHOT.jar
   -hsrc <Source_Server_Name>
   -usrc <User_Name>
   -pwdsrc <Password>
   -psrc <Port_NO>
   -hdest <Dest_Server_Name>
   -udest  <User_Name>
   -pwddest  <Password>
   -pdest <Port_Number>  
   -o  <Report_Folder_Path>
   -op migrate
   -stp 12
   -sngl true

   Example

   java
   -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
   -jar migratecustomizations-99.0.00-SNAPSHOT.jar
   -hsrc source_server
   -usrc user1
   -pwdsrc pwd@1
   -psrc 8080
   -hdest dest_server
   -udest  user1
   -pwddest   pwd@1  
   -pdest 8080
   -o  <Report_Folder_Path>
   -op migrate  
   -stp 12
   -sngl true

3. (Optional) Set the environment variables if you observe the following error:

   Error

   - SEVERE: class org.apache.xerces.parsers.XIncludeAwareParserConfiguration
   cannot be cast to class org.apache.xerces.xni.parser.XMLParserConfiguration
   (org.apache.xerces.parsers.XIncludeAwareParserConfiguration is in unnamed
   module of loader org.eclipse.osgi.internal.loader.EquinoxClassLoader
   @44f187c3; org.apache.xerces.xni.parser.XMLParserConfiguration is in
   unnamed module of loader 'app')
   
   

   • 
     
     • For Windows operating system:
       1. Edit the system environment variables
       2. Select Environment Variable.
       3. Click New system variable.
       4. Add the -Djavax.xml.parsers.SAXParserFactory variable with value
          com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl.

     • For Linux operating system:
       At the command prompt, run the following command. 

       Command syntax

       export JAVA_TOOL_OPTIONS=
       "-Djavax.xml.parsers.SAXParserFactory
       =com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl"
4. If you have fixed the environment variables, re-run the workflow migration utility with the -stp 12 parameter.