Oracle SOA Human Workflow Metadata Test2Production Migration
By Venugopal Mangipudi on Jan 23, 2014
Use Case: The OBPM Developers/Administrators have created the Flex Fields (Both Public and Protected) in the Oracle BPM Workspace and need a way to migrate the same to the Test, Pre-Prod and Prod environments (and avoid using the cumbersome process of creating the Labels and Task Mappings again in each environment).
T2P Migration Steps:
For the above use case of migrating the Human Task Metadata to another SOA environment, there is Oracle Official Documentation that describes the procedure to use hwfMigrator tool. The documentation is really helpful and describes all the steps in detail and should be the starting point to understand the steps. I would restrict this blog entry to the high level steps that need to be performed to migrate the metadata (specifically flex fields as the tool provides a way to migrate Views and User Rules also).
- Prerequisites: The following are the pre-requisites to run the migration tool
- Set the JAVA_HOME to your JDK Location
- The Source SOA Environment should be having the Flex Field Labels and Flex Field Mappings and the SOA Server should be Up and Running. (To learn how to create FlexFields, you can refer to the article where the author has provided a nice description and tutorial)
- The Target SOA environment should be prepared by deploying BPM/SOA Projects that will be used by the FlexField Task Mappings. This is a very important step as the scripts will fail to import the metadata in case the applications that are deployed in the Source and Target Servers do not match.
- Create a Local Folder in your file system (I am using Windows 7 OS) and copy ant-t2p-worklist.xml from ORACLE_HOME/bin to the Local Folder.
- BEA_HOME is the path to the SOA Installation (For example D:\Oracle\Middleware\SOAHome11117) and ORACLE_HOME would be %BEA_HOME%\Oracle_SOA1 (So in my case D:\Oracle\Middleware\SOAHome11117\Oracle_SOA1).
- The ant-t2p-worklist.xml that comes packaged with the SOA Installation seems to be wrong because when I ran the Ant scripts I was getting errors that were showing up (because some of the SOA Library references in the file are being referred from the wrong location). I modified the file and am using the following ant-t2p-worklist.xml file to get the script to work.
- Steps for Migration
At a high level, to run the targets in the ant-t2p-worklist.xml we need to provide a migration.properties file (in the below steps I am providing the links for the migration.properties for each of the action) that will have the properties that are needed to determine the action that the build file needs to execute. In general, first the operation EXPORT is used to export the workflow metadata (flexfields, views and rules) from the Source SOA environment. After the Export is successful and the 2 XML artifacts are generated (which hold the metadata that got exported and also the mapping file), the metadata can be imported into the Target SOA environment using the IMPORT operation.
To migrate the Flexfields, it is mandatory to do an Import of the Labels first and then the Task Mappings.
- Export of ALL Flexfield Labels:
- Export of ALL Flexfield Taskpayload Mapping:
- Import of ALL Flexfield Labels:
To export the FlexField Labels, create a migration.properties file as follows:
operationType = EXPORT
objectType = TASK_PAYLOAD_FLEX_FIELD_MAPPING
name = ALL
user = cdickens
grantPermission = true
migrateAttributeLabel = true
override = true
skip = true
migrateToActiveVersion = true
The Official Documentation provides a migration.properties file that will fail when we run the ant script (it will give an ArrayOutOfBoundsException), because it has group entry (group =). I tried multiple combinations on the migration.properties file, that was provided, and finally after removing the group entry, the ant task execution was successful!
To run the ant task, point to the ant executable that exists in the SOA Environment (%BEA_HOME%\modules\org.apache.ant_1.7.1\bin ).
Once the migration.properties is ready you can run the following command to export all the Flex Field Labels:
D:\Oracle\Middleware\SOAHome11117\modules\org.apache.ant_1.7.1\bin\ant -f ant-t2p-worklist.xml
The last two arguments can be named as per your practice. These 2 files get generated once the ant task runs successfully and will be used in the IMPORT operation. The link to the Files that that were used to generate the Export artifacts can be found here.
The steps to export the taskpayload mappings is the same as the one used for the export of Labels. The difference would be in the migration.properties. The migrateAtributeLabel would be false. The link to the Files that that were used to generate the Export artifacts can be found here.
The steps to import the taskpayload mappings is the same as the one used for the export of Labels. The difference would be in the migration.properties. The migrateAtributeLabel would be true and operationType would be IMPORT. The link to the Files that that were used to generate the Export artifacts can be found here.
- Import of ALL Flexfield Taskpayload Mapping:
The steps to import the taskpayload mappings is the same as the one used for the export of Labels. The difference would be in the migration.properties. The migrateAtributeLabel would be false and operationType would be IMPORT. The link to the Files that that were used to generate the Export artifacts can be found here.
Once the import is done, the FlexField Labels and Task Payload Mappings should be available in the Target SOA Environment. Hope this explanation was helpful!!!