This article describes how to call Java classes in the Process Commander application libraries to programmatically export and import Process Commander class instances from and to Process Commander databases.

• The Export command writes the specified class instances from a source PegaRULES database to a .zip file in a binary format or as XML.
• The Import command takes the .zip file as input and writes the exported class instances to a target system PegaRULES database.

  You can specify the class instances by RuleSet name and version, by class name with or without descendants, or by pzInsKey key values.

  The source Process Commander system must be V5.2 or later, and the destination Process Commander system must have the same or a later version than the source system.

The following diagram shows a conceptual view of the components involved in the process:

In this diagram, the two Process Commander systems and a third computer executing the script are distinct. In practice, however, this operation can involve one, two, or three computers, or more if each Process Commander system uses a separate computer to host its PegaRULES database. The operation always involves two prconfig.xml files, one identifying the source PegaRULES database (containing the rules to be migrated), and the second identifying the target PegaRULES database.

Note that the Export and Import calls operate directly on the Process Commander databases, independent of the Process Commander applications. The transfer can even occur when the Process Commander application and its server are not in operation; however, the database servers must be running.

To complete this process:

1. Configure a Java JVM environment with access to the Process Commander engine JAR files and the appropriate database driver files.
2. Copy or create prconfig.xml files that specify the location and database access information for the source and target databases.
3. Call the Export method specifying the RuleSets or classes you want to move, and the .zip file name to use.

   The Export method creates a Process Commander import archive file with the specified components from the source database.

4. Call the Import method specifying the name of the .zip file and other database options.

   The Import method loads the database components in the import archive file into the target database.

Details on these steps are given below.

An example of an Apache Ant script calling these classes is provided below, but you could apply the same method to any scripting language. For example, you can create a Unix shell script to migrate a RuleSet version OurFinance:02-05-15 from a development system (labelled SOURCE in the diagram) to a unit testing system (labelled Target).

Important: This functionality does not duplicate the Product wizard. If you are moving entire Rule-Applications you should use the Import and Export Archive (formerly RulesMove) facility. When calling the Export method, you must specify exactly which RuleSets and/or classes you want to move. Before using these methods, be sure you understand RuleSets and RuleSet archives. See:

• Process Commander Administration and Security Guide, Chapter 4, Administering RuleSets
• Deployment — Concepts and terms
• About Archive tools and related topics
• How to Create a Product .zip file
• A checklist for product migration

Suggested Approach

1. Configure a Java JVM environment with access to the Process Commander engine JAR files and the appropriate database driver files.

Verify JVM Environment

You must have a JRE distribution in place in the command-line system that allows you to make Java calls. Use the JVM version required by the Process Commander system you are accessing. See the PRPC Platform Support Guide for details.

Access to software components

Make sure the following libraries are installed and accessible to your JVM environment:

• Your classpath must contain the path to the WEB-INF/lib directory of a deployed prdbutil.war file. This directory contains the Process Commander engine jar files and the dependent, 3rd party, jars needed to support the export and import functions.
  If you deployed to an expanded server directory, as in Tomcat, you can include the path to the prdbutil application's WEB-INF/lib directory, for example, C:\apache-tomcat\webapps\prdbutil\WEB-INF\lib.
  If you used a binary deployment in your application server, download prdbutil.war from the Pegasystems software distribution for your Process Commander release, expand the WAR file on your command-line system, and include the WEB-INF/lib directory at that location in your classpath.
• Your class path must include the location of the JDBC driver jar files for your database. In the Installation Guide, see "Configuring database support on your application server" for information on the appropriate driver for your database.
• Your class path must include the location of the J2EE servlet API libraries, in particular the javax.servlet.ServletContext.class and javax.servlet.jsp.JspFactory.class. Under Tomcat, these classes are located in servlet-api.jar the common/lib directory. Other application servers or JVM distributions may distribute these classes in servlet.jar or javax-servlet.jar.

2. Copy or create prconfig.xml files specifying the location and access information for the target and source databases.

You must copy or create a prconfig.xml file that provides database connection information for the target system and one for the source system. You reference these configuration files in the script to allow the Process Commander libraries to access the appropriate databases. Copy the prconfig.xml files to the directory that contains the Ant script. Either locate each prconfig.xml file in a separate directory or rename them as appropriate.

Important: PRPC prefers to use a ‘prconfig.xml’ file that is located by the Java variable ‘user.home’ directory. Ensure that when running the command line environment that the ‘user.home’ directory does not contain a prconfig.xml file.

If the source or target system is using Process Commander-managed database connection pooling, which specifies the data connection in the system's prconfig.xml file, you can copy the proconfig.xml file to the command-line system. For example, Tomcat WAR deployments use PRPC connection pooling.

If the source or target system is using the application server's data source to support container-managed database connections, you cannot use the prconfig.xml file from these systems. Instead, copy the prconfig.xml to the command-line system and then edit the prconfig.xml file to add a data connection.

For information about how to edit the prconfig.xml file, see Adding Database Connection Information to prconfig.xml.

3. Call the Export method specifying the RuleSets or classes you want to move and the .zip file name to use.

Call the PRPC library method com.pega.pegarules.engine.database.ExportImpl supplying arguments to specify the RuleSet and/or PRPC classes you want to export, and the name of the .zip file to create.

The syntax of the Export method is as follows:

com.pega.pegarules.engine.database.ExportImpl
-o <output file> [-L] [-b]
[-c <classes>] [-C <classes>] [-x <classes>] [-X <classes>]
[-n <rsn>] [-v <min rsv>] [-V <max rsv>]
[-k <key file>] [-t <template file>]

where the command line switches have the following values and meanings:

The following provides examples of the arguments for typical uses of the method:

Export by RuleSet

Export the Foo RuleSet

-o foo_ruleset.zip -C Rule- -n Foo

Export the Foo RuleSet, including versions 01-01-01 through 01-01-05:

-o foo_ruleset.zip -C Rule- -n Foo -v 01-01-01 -V 01-01-05

Export by Records

Export all Operator ID records

-o operators.zip -c Data-Admin-Operator-ID

Export the instances, identified by pzInsKey and specified in the myinstances.txt file

–o myinstances.zip –k myinstances.txt

Note that you can also combine these arguments to define a product specification by specifying a RuleSet and the associated Data- classes. See How to Create a Product .zip file and A checklist for product migration for more information on how to define a product specification.

4. Call the Import method specifying the name of the .zip file and other database options.

Update: When using ImportImpl to import RuleSets and classes, you may receive a NoInitialContextException exception: You can ignore this error, or install a workaround: See Troubleshooting: ImportImpl throws error when importing RuleSets.

Call the library method com.pega.pegarules.engine.database. supplying arguments to specify the name of the .zip file containing the RuleSet and/or Process Commander classes you want to import. You can also specify database options that control how the records are written to the database.

The syntax of the Import method is as follows:

com.pega.pegarules.engine.database.ImportImpl
-a <input file> [-o] [-b] [-f] [-c <count>] [-t <file>] [-s <ruleset name>]

where:

Examples

Import the foo_ruleset.zip archive:

–a foo_ruleset.zip

Import the foo_ruleset.zip archive, do not allow overwrites:

–a foo_ruleset.zip -o

Import the foo_ruleset.zip archive, commit every 10 records:

–a foo_ruleset.zip –c 10

Example Ant Script

This section provides an example Ant script demonstrating the use of the Export and Import methods. You can use this example as an outline for a typical script for importing and exporting PRPC classes, but review it carefully for modifications for your needs and environment.

Example Ant Call (MS-DOS)

The following is a typical command-line sequence for calling the sample script. Note the set commands to specify the correct path to the appropriate JVM and the command-line options to the Java call to set appropriate JVM memory parameters.

set JAVA_HOME=C:\Progra~1\j2sdk1.4.2_06
set PATH=%JAVA_HOME%\bin;%PATH%
set ANT_OPTS=-Xms128m -Xmx384m

cmd /c ant -buildfile export_import.xml <Export|Import>

Example Script Solution

The following script implements the steps outlined above:

• Properties to set the classpaths for the PRPC libraries, the JDBC database drivers, and the servlet API library.
• Properties to specify the location of the source and target prconfig.xml files. In addition, rather than hard-coding the Export and Import arguments in the script, the configuration section also include properties specifying files containing the source and target command-line argument strings.
• Calls to the Export and Import methods using the properties defined in the earlier sections.

<project name="command_line_export_import" default="noop"
basedir=".">
<!-- ===== PRPC CLASSPATH CONFIGURATION ===== -->
<property name="prpc.lib" value="a_path/WEB-INF/lib"/>
<!-- Path to PRPC libs -->
<property name="jdbc.lib" value="a_path/jdbclib"/>
<!-- Path to JDBC libs -->
<property name="servlet.api.lib" value="a_path/servletapilib"/>
<!-- Path to Servlet API libs -->

<!-- ===== PRPC SOURCE CONFIGURATION ===== -->
<property name="source.prconfig.path"
value="a_path/source-prconfig.xml"/>
<!-- Source System prconfig.xml -->
<property name="source.commandline" value="a_command_line_here"/>
<!-- Export Command Line -->

<!-- ===== PRPC TARGET CONFIGURATION ===== -->
<property name="target.prconfig.path" value="a_path/target-prconfig.xml"/>
<!-- Target System prconfig.xml -->
<property name="target.commandline" value="a_command_line_here"/> <!-- Import Command Line -->

<path id="prpc-classpath">
<pathelement path="."/>
<fileset dir="$prpc.lib">
<include name="**/*.jar"/>
</fileset>
<pathelement path="$prpc.lib/../binredist/x86"/>
<pathelement path="$prpc.lib/../binredist/sparc"/>
<fileset dir="$jdbc.lib">
<include name="**/*.jar"/>
</fileset>
<fileset dir="$servlet.api.lib">
<include name="**/*.jar"/>
</fileset>
<pathelement path="$java.class.path"/>
</path>

<target name="Export">
<echo message="Performing Export"/>
<copy file="$source.prconfig.path" tofile="./prconfig.xml" overwrite="true" verbose="true" failonerror="true"/>
<java classname="com.pega.pegarules.engine.database.ExportImpl" fork="true" failonerror="true" append="yes">
<jvmarg value="-Xms128m"/>
<jvmarg value="-Xmx384m"/>
<jvmarg value="-Dpegarules.config=./prconfig.xml"/>
<classpath refid="prpc-classpath"/>
<arg line="$source.commandline"/>
</java>
</target>

<target name="Import">
<echo message="Performing Import"/>
<copy file="$target.prconfig.path" tofile="./prconfig.xml" overwrite="true" verbose="true" failonerror="true">
<java classname="com.pega.pegarules.engine.database.ImportImpl" fork="true" failonerror="true" append="yes">
<jvmarg value="-Xms128m"/>
<jvmarg value="-Xmx384m"/>
<jvmarg value="-Dpegarules.config=./prconfig.xml"/>
<classpath refid="prpc-classpath"/>
<arg line="$target.commandline"/>
</java>
</target>

<target name="noop">
<echo message="Choose Export or Import"/>
</target>
</project>