This chapter describes the utilities available to assist with the migration of BPM 10gR3 projects to BPM 12c.
This chapter includes the following sections:
Oracle BPM 12c includes two utilities to facilitate migration.
These are:
BPM migration utility
BPM OU migration script
The BPM migration utility is an ant script that migrates BPM processes, screenflows and business catalog artifacts from 10gR3 to 12c. It creates a BPM 12c export project file that you can import into 12c. It also creates a migration log that you can use to troubleshoot problems that occurred during the migration process.
The BPM OU Migration Script is an ant script that migrates organization information such as roles and calendar rules from a BPM 10gR3 environment to BPM 12c.
The BPM migration utility is supported on a number of platforms.
Supported platforms include:
Oracle Enterprise Linux 5.8 (64 bit)
Oracle Enterprise Linux 6.4 (64 bit)
Windows 7 Professional (64 bit)
Windows 8.1 Enterprise (64 bit)
The BPM 10gR3 source environment must include a number of packages to run the BPM migration utility and the BPM OU migration script.
The packages required to be present in your 10gR3 environment include:
Java SE Development Kit
http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html
Use a JDK version supported by your target BPM 12c. See the Oracle Fusion Middleware Supported System Configurations information at http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html. Download the appropriate certification matrix spreadsheet for your product. Use the matrix to confirm the version(s) of JDK supported for your BPM 12c target based on processor, OS version, and Fusion Middleware products.
See Installing SOA Suite and Business Process Management Suite Quick Start for Developers for additional information.
Apache Ant (TM) version 1.8.4
http://archive.apache.org/dist/ant/binaries/apache-ant-1.8.4-bin.zip
Oracle Business Process Management Suite 10gR3
JDeveloper 12c with Oracle BPM Studio 12c plug-ins. Obtain these components using the BPM Suite Quick Start Installer. See http://www.oracle.com/technetwork/middleware/bpm/downloads/index.html
To view, edit, deploy and run the migrated project you must have an environment with Oracle Business Process Management Suite 12c installed. For information on how to install Oracle BPM Suite, see Installing and Configuring Oracle SOA Suite and Business Process Management
Before running the BPM migration utility, you must ensure that your projects and environment are properly prepared.
Latest BPM 10gR3 version - the project to be migrated must be validated using BPM 10gR3 (10.3.3) with the latest hotfix applied (build 101298 at this writing)
No compilation errors - the project to be migrated must be free of compilation errors
Project dependencies - all dependent projects (that is, projects that work together and have Project Preferences > Dependency > Use Project Dependency checked) must be located under the same folder.
Decompressed filenames - some decompression tools render decompressed filenames incorrectly by using invalid characters. Always use BPM Studio 10gR3 to expand imported project .exp files. The migrator project location parameter must point to the project root folder created by BPM Studio 10gR3. For example C:\OracleBPM\SampleProject.
Non-English characters - replace foreign language characters that might render as invalid characters (such as ’è’ being rendered as ’?’) with English language replacements (such as ’e’). Non-English characters within BPM file metadata is acceptable.
BPM 5.5 and 5.7 file metadata - The BPM migration tool does not support BPM 5.x metadata within certain files (such as .xpdl and .xsdl files). The Ant console output or the migration report indicates the names of these files. To update the file metadata, edit the affected file using BPM Studio 10gR3, make an immaterial change to the activity (for example, move it slightly), and save the project.
An example migration report error message from invalid file metadata is:
SEVERE: path/to/process_name.xpdl is a legacy file format and cannot be processed. Only 10.3 format is supported. In order to migrate it please edit and save the file (Process, Screenflow or Procedure) using Studio 10.3, export the project and re-run the migration.
Enumerations - Enumerations specified within introspected jars must be specified using a specific Ant parameter when you run the BPM migration utility. For example:
ant -lib myenum.jar mgrate10-12...
Plumtree - if Plumtree components are used in a script, use the ant -lib parameter to provide the location of the distributed edk jar (fuego.edk-10.3.3.jar). For example:
ant -lib route/to/fuego.edk-10.3.3.jar migrate10-12...
Web services - ensure that called Web services (.wsdl files) within a Web service are reachable
Schemas - ensure that xml schemas (.xsd files) called within a schema file are reachable
This section describes the command line options for the BPM migration utility.
The BPM migration utility command line has the following syntax:
ant migrate10-12 -DprojectLocation=<source> -Ddestination=<target> [-Doption=-L<log_level>] [-DcustomXMLmappingDirs=<mappingdirs>]
where
source - specifies the location of the BPM 10gR3 project to migrate
target - the destination for the migrated project and report files
log_level - detail level for logged messages. Messages from the specified level and higher are logged. If you do not specify a log level, the default level is -L2, which logs messages from L2, L3, L4 and L5.
Log levels are:
-L1: Detailed info messages
-L2: Info messages
-L3: Warning messages
-L4: Severe issues messages
-L5: Fatal error message
mappingdirs - a list of directories containing custom XML mappings to use when migrating Business Process Language scripts, separated by ’:’. For example, dir1:dir2:dirn.
An example command line invocation is:
ant migrate10-12 -DprojectLocation=/user/migrationTests/input/samples/ExpenseReimbursement -Ddestination=/user/migrationTests/output/samples/export1
To obtain more detailed output, use the ant -d and -v command line parameters and a higher log level:
ant -d -v migrate10-12 -DprojectLocation=/user/migrationTests/input/samples/ExpenseReimbursement -Ddestination=/user/migrationTests/output/samples/export2 -Doption=-L1
If you run the BPM migration utility with incorrect command-line arguments it prints a usage statement to the terminal. This statement describes what the usage statement should contain and the conventions you must use. For example:
ant migrate10-12 -DprojectLocation=source -Ddestination=target (-Doption="options") (-DcustomXMLmappingDirs=customXmlDirs)
For information using ant parameters to generate migration statistics, see Generating Migration Statistics for Components in Scripts.
You can generate migration statistics for components used in scripts.
To generate migration statistics for components used in scripts, add the parameter -Doracle.bpm.migration10to12.statistics=true to the ANT_OPTS environment variable before running the BPM migration utility.
This parameter causes a CSV file named <project_name>_mapperStats.csv to be created in the BPM migration utility output path.
This file contains the following columns:
Source
Possible values: predefined component, user defined component
Component
Specifies the full name of the component
Component Type
Specifies the technology used
Member Type
Possible values: type, method, attribute (read/write)
Quantity
Indicates the relative usage of the component
Use the BPM migration utility migrates projects from BPM 10gR3 version to BPM 12c.
See BPM Migration Utility Supported Platforms and Migration Environment Pre-Requisites for environment and pre-requisite information.
See Preparing for the BPM Migration Utility for steps to take prior to running the BPM migration utility.
To run the BPM migration utility
The BPM migration utility creates an exported BPM project that you can open with Oracle Business Process Management 12c.
For more information on how to open projects, see Developing Business Processes with Oracle Business Process Management Studio.
For a detailed description of how the BPM migration utility migrates each of the elements of the BPM project, see the following:
For more information on how to view the migration report, see Accessing the BPM Migration Utility Output.
The BPM migration utility creates several files in the target directory when it executes.
If the project myproject is migrated to the target directory migrateoutput, the following files are created:
myproject.exp - BPM 12c format migrated project file
myproject.xml - migration report data
report.xsl - migration report format schema
myproject_mapperStats.csv - (optional) comma separated statistics file
myproject_projectStats.csv - (optional) comma separated statistics file
See BPM Migration Utility Options and Generating Migration Statistics for Components in Scripts for details on BPM migration utility parameters.
The BPM migration utility generates a migration report that describes the results of the migration process and indicates the migration status of each of the artifacts in the source BPM project. Use the report to know where you must make additional manual changes to complete the migration.
To view the migration report:
Use the BPM Organizational Unit (OU) migration script to migrate artifacts from BPM 10gR3 to BPM 12c.
Artifacts migrated by the OU migration script include:
Organizational Units
Calendar Rules
Holiday Rules
Application Roles
Parametric Roles
Business Parameters
Before running the BPM OU migration script, you must perform some preparatory tasks.
Working folder - create a working folder to use when running the script.
Copy directory.xml to working folder - navigate to Oracle/Middleware/<Oracle_Home>/soa/plugins/migration/bpm and copy directory.xml. Place a copy of this file in your working folder.
directory.xml configured - you must edit directory.xml to specify server and connection information as follows:
edit the <serverURL>t3://localhost:7001</serverURL> line, replacing localhost with the IP address of your SOA/BPM 12c server, and the port number 7001 with the port number of your SOA/BPM 12c server.
edit the <admin> attribute to specify the 10gR3 WebLogic server Admin account username
edit the <adminPass> attribute to specify your 10gR3 WebLogic server Admin account password
Unzip organizationmigration file to working folder - navigate to $BPM_HOME/ou-migration and unzip oracle.bpm.bpm-services.organizationmigration.jar to your working folder.
BPM 10gR3 components running - the BPM 10g Directory Service database (Fuego Directory Interface (FDI)) and LDAP server must be running
BPM 12c running - the BPM 12c environment must be running
12c_Config.xml configured - you must edit 12c_Config.xml (located in Oracle/Middleware/<Oracle_Home>/soa/plugins/migration/bpm) to specify server and connection information as follows:
edit the <serverURL>t3://localhost:7001</serverURL> line, replacing localhost with the IP address of your SOA/BPM 12c server, and the port number 7001 with the port number of your SOA/BPM 12c server.
edit the <adminUserLogin> attribute to specify the 12c WebLogic server Admin account username
edit the <adminUserPassword> attribute to specify the 12c WebLogic server Admin account password
LDAP connectivity - configure your SOA/BPM 12c environment to be able to connect to the BPM 10gR3 LDAP server.
This section describes the command line options for the BPM Organizational Unit (OU) migration script.
The BPM OU migration script command line has the following syntax:
ant -f ant-organization-migrator.xml -Dfmwhome=<path_to_fmwhome> -Dalbpm.directory.file=<path_to_10g_directory_xml> -Dconfig.file=<path_to_12c_configfile_xml> -Dfuegojarpath=<path_to_10g_fuego> -Dentity.type=<entity> [-Dversion=<target_jar_version>
where
path_to_fmwhome - specifies the path to the BPM 12c fmwhome directory
path_to_10g_directory_xml - specifies the location of the BPM 10gR3 directory.xml file. This can be a working folder where you have placed a copy of the file.
path_to_12c_configfile_xml - specifies the location of the BPM 12c 12c_configfile.xml file. This file must be edited to specify your BPM 12c server and login information. See Preparing for the BPM OU Migration Script.
path_to_10g_fuego - the path to the BPM 10gR3 fuegopapi.client-10.3.3.jar file. This file is typically located under Oracle/Middleware/<Oracle_Home>/soa/plugins/jdeveloper/bpm/libraries.
entity - specify the organizational elements to be migrated. Possible values are calendar, orgunit, approle, parametricrole and all. If this parameter is left blank, then the value all is used.
target_jar_version - optional. Specify the target 12c version, for example 12.1.3. The default if unspecified is 12.1.3.
An example command line invocation to migrate only calendar rules is:
ant -f ant-organization-migrator.xml -Dfmwhome=/oracle/fmwhome -Dalbpm.directory.file=/mytempworkingfolder -Dconfig.file=/oracle/product/middleware/oracle_home/soa/plugins/migration/bpm -Dfuegojarpath=OraBPMStudioHome/client/papi/lib -Dentity.type=calendar
If you run the BPM migration utility with incorrect command-line arguments it prints a usage statement to the terminal. This statement describes what the usage statement should contain and the conventions you must use.
Use the Organizational Unit (OU) migration script to migrate organizational unit artifacts from BPM 10gR3 to BPM 12c.
See About the BPM OU Migration Script and BPM Migration Environment Pre-Requisites for environment and pre-requisite information.
See Preparing for the BPM OU Migration Script for steps to take prior to running the OU migration script.
To run the OU migration script:
For a detailed description of OU migration script parameters and options, see BPM OU Migration Script Options
The OU migration script migrates and creates the organizational unit elements in the target BPM 12c environment.
An XML migration report named migr_report.xml is created at the location from which you invoked the OU migration script. This report indicates which elements are migrated successfully and which are not, along with the reason for the failure to migrate.