Running a BIX extract from the command-line

In addition to running a BIX extract from within the Designer Studio in Pega 7 Platform, you can directly call the ExtractImpl Java class in the Pega 7 Platform application libraries to define and run an extract process. Specify the data to be extracted and the output format by referencing an Extract rule that you have created in Pega 7 Platform. ExtractImpl can either access the Extract rule in the Pega 7 Platform database or read an XML file containing the XML representation of the rule. BIX in the command-line executes in its own Java Virtual Machine (JVM) instance.

You can add other optional parameters that filter the data by any property, including date ranges, and specify other processing options. For more information, see Setting optional command-line BIX parameters.

Running an Extract rule from the command-line works in the following way:

1. BIX accesses the Pega 7 Platform (source) database using the information defined in the BIX prconfig.xml file.
2. Using the information configured in the bix.xml file and specified in the Extract rule, BIX extracts the specified data from the Pega 7 Platform (source) database.
3. The extracted data is output in the output format specified in the Extract rule.

Note: The output data includes a timestamp and a batch identifier. These help when you want to compare information from different extracts or isolate information from a specific extract.

Configuring the BIX Pega 7 Platform configuration files

To complete the command-line environment, provide information to the Pega 7 Platform system in three configuration files:

• prconfig.xml
• prlogging.xml
• prbootstrap.properties

Additionally, you can create a pegarules.keyring file to support encryption of the database password that must be supplied with the database connection settings in prconfig.xml. Each of these files is described in the following sections.

Configure the prconfig.xml file

Edit the prconfig.xml file provided in the configuration directory of your BIX distribution, adding database connection settings that specify the source Pega 7 Platform database where data is extracted. If you want to use the Database Schema output format, add a second set of database connection settings that specify the target database where the extracted data is written.

Create the source database

The prconfig.xml file contains sample database connection settings for an Oracle database:

<env name=”database/drivers” value=”com.microsoft.jdbc.sqlserver.SQLServerDriver;oracle.jdbc.OracleDriver” />
<env name=”database/databases/PegaRULES/url” value=”jdbc:icrosoft:sqlserver://localhost:1433;SelectMethod=cursor;
SendStringParametersAsUnicode=false;ProgramName=PR ${SystemName}@${NodeName} ${DBName} #${ConnectionID}” />
<env name=”database/databases/PegaRULES/icrosof” value=”a_username” />
<env name=”database/databases/PegaRULES/password" value="a_password" />


Modify this code as needed for your Pega 7 Platform database.

Note: The following steps outline the procedure for specifying typical database connection settings. Consult your DBA to resolve requirements specific to your installation. More information is available in PDN article: How to configure non-J2EE database connections in the prconfig.xml file.

1. In the database/drivers element, change the value to the appropriate driver for your database. For example:
   

   Database driver	Value
   Oracle 9i/10g	oracle.jdbc.OracleDriver
   IBM DB/2 Type 4	com.ibm.db2.jcc.DB2Driver
   SQL Server 2005	com.microsoft.sqlserver.jdbc.SQLServerDriver
   SQL Server 2000	com.microsoft.jdbc.sqlserver.SQLServerDriver

2. In the database/databases/PegaRULES/url element, set the value to the connection URL for your database. Following are examples of the appropriate format for some supported databases:

   Database driver	Value
   Oracle 10g/11g (Native OCI Client)	jdbc:oracle:oci:@your_tns_name
   Oracle 10g/11g (Thin Client)	jdbc:oracle:thin:@myServer:1521:myDatabase
   DB/2 (Universal Driver)	jdbc:db2://serverName:port/dbName
   SQL Server 2005	jdbc:sqlserver://<your_sql_server_host>:1433; SendStringParametersAsUnicode=false; SelectMethod=cursor; ProgramName=${NodeName}:${SystemName}.${ConnectionID}

3. Set the value of database/databases/PegaRULES/userName and database/databases/PegaRULES/password to the user name and password of a user for the Pega 7 Platform database.
4. Set the value of database/databases/PegaDATA/userName and database/databases/PegaDATA/password to the user name and password of a user for the Pega 7 database.

Optional: Define the Target database connection settings

The BIX Database Schema output format writes the extracted data directly to a target database. To support this output, you must provide a second set of database connection settings specifying the target database where the data is to be loaded.

In the BIX prconfig.xml file, copy and paste the database connection settings that you created for the source database.

In each element name, change PegaRULES to the name of the database that you specified as the Output Database Name in the Extract rule. Refer to the following examples:

Repeat the procedure used for the source database connection to set the target database connection settings to the appropriate values.

Note: In addition to specifying the database connection settings, Oracle and UDB databases require some additional configuration. Consult your DBA to resolve requirements specific to your installation. More information is available in PDN article How to configure non-J2EE database connections in the prconfig.xml file.

Split schema setup

For split schema, add the following environment variables:

<env name="database/databases/PegaRULES/defaultSchema" value="rulesSchema_Name"/>

<env name="database/databases/PegaDATA/defaultSchema" value="dataSchema_Name" />

Note: For more information, see Configuring prbootstrap.properties – Split schema setup.

Other optional settings

You can add the following settings to the end of the prconfig.xml file to address certain issues that may occur:

• Optimize XML output – Set to true by default to facilitate extracting a large number of class instances to XML:
  <env name= “compatibility/BIXUseOptimizedClipboardXML” value= “true” />
• Disable forward chaining – Enable or disable forward chaining calculations of properties when loading the clipboard for BIX extract:
  <env name= “compatibility/BIXUseOptimizedClipboardXML” value= “true”>
  The default setting is TRUE.
• Disable backward chaining – Enable or disable backward chaining of properties when loading the clipboard for BIX extracts:
  <env name=”compatibility/BIXdisableForwardChaining” value = “true” />
  The default setting is TRUE.
• Record inclusion – To ensure that records added to the database while the extract is running get included in the extract, add this property:
  <env name=”bix/useHistoryClasses” value=”true” />

Configure the prlogging.xml file

prlogging.xml is a log4j configuration file that enables two log files for the extraction process, PegaBIX and PegaBIX-ALERT. By default, the log files are written to the directory where the extraction process is started. Ensure that you set logging levels appropriately, because turning up logging levels to DEBUG or ALERT can lead to performance issues, including slower extracts or full log files.

You can modify the FileNamePattern for the PegaBIX and PegaBIX-ALERT logs to change the location to which they are output.

Configure prbootstrap.properties

Pega 7 Platform stores engine code in the database as a CodeSet. Edit the prbootstrap.properties file provided in the configuration directory of your BIX distribution to add database connection settings that specify the Pega 7 Platform database holding the engine code.

Specify the database connection settings using the naming convention:
          <unique-identifier>,<dbtype>.<property>

In this sequence:

• <unique-identifier> is a distinct value that together with <dbtype> identifies a specific data source.
• <dbtype> refers to a set of common properties associated with a given database type. There are four values that may be used:
  • oracle
  • db2
  • mssql
  • derby
• <property> is one of the key values needed to access the data source.

Example prbootstrap.properties configuration

To connect to an Oracle database:

com.pega.pegarules.bootstrap.engineclasses.dbcpsource=example.oracle
com.pega.pegarules.bootstrap.assembledclasses.dbcpsource=example.oracle
example.oracle.url=jdbc:oracle:thin:@localhost:1521:codebase
example.oracle.username=user
example.oracle.password=pass
oracle.jdbc.class=oracle.jdbc.OracleDriver

Specify any additional properties needed to connect to the database using the connectionProperties entry and provide a semicolon-separated list of values. For example:

example.oracle.connectionProperties=oracle.jdbc.V8Compatible=true

Note: Set the system property com.pega.pegarules.bootstrap.ignorejndi to TRUE when using Pega-managed connections. This tells Pega 7 Platform to ignore the JNDI data source information in the file and to instead use the Pega-managed connection settings.

In Pega 7, you can replace the following two lines:

com.pega.pegarules.bootstrap.engineclasses.dbcpsource=example.oracle

com.pega.pegarules.bootstrap.assembledclasses.dbcpsource=example.oracle

with this single entry:

com.pega.pegarules.bootstrap.allclasses.dbcpsource=example.oracle

Split schema setup

For a split schema setup, add the following properties:

com.pega.pegarules.bootstrap.allclasses.schema=" rulesSchema_Name "

com.pega.pegarules.bootstrap.datatables.schema=" dataSchema_Name "

Enable password encryption

BIX lets you pass in a Pega 7 Platform username and password to rule-resolve the Rule-Admin-Extract rule to run. If you want to enable security for the database username and password, you can implement JCE "keyring" encryption by creating a pegarules.keyring file.

You can use keyring encryption to encrypt the username and password. To do this, run the KeyringImpl Java class, which accepts three parameters and generates the keyring file. The parameters are:

1. The path where the pegarules.keyring file is generated (including the filename)
2. The path to the prconfig.xml file
3. The path to the BIX distribution directory

To encrypt BIX passwords in the same file, pass an additional argument named "bix". Running the KeyringImpl Java file with this additional parameter prompts the user for the BIX username and password. The file encrypts the information that you enter.

Note: The runPega batch script assumes that the prconfig.xml provided as an argument to the Keyringimpl class is the same as the prconfig.xml file in the prweb/web-inf/classes folder. If the prconfig.xml file is in a different location, use the Java command directly as instructed in the PDN article How to encrypt database passwords using a JCE Keyring file.

Preparing a target database

Before extracting data to the target database, you must create a schema to match the extracted data. You can use BIX to generate an SQL file that creates the appropriate schema.

Call the ExtractImpl class with the parameter -X <Path><FileName> to generate a DDL for the target database. Run the SQL script against the target database using your database tools.

Note: To use the -X parameter, the output format of the Rule-Admin-Extract rule that you specify must be Database schema. The user must also have Write access to the directory. If the output format is XML or CSV, an error message displays:

Cannot generate database schema when output type is set to CSV/XML.

Running the command-line extract process

In a properly configured environment, from the command-line or in a script, make a Java call to com.pega.pegarules.data.internal.access.ExtractImpl, supplying arguments to specify:

• JVM memory options – Ensure that your JVM is allocated with enough memory for the operation by setting:
  • The initial Java heap size to 512m (-Xms512m)
  • The maximum heap size to at least 768m (-Xmx768m)
• System properties - Provide the location of the Pega 7 Platform configuration files prconfig.xml, prlogging.xml, and if used, pegarules.keyring. For example:
  • -Dpegarules.config=config/prconfig.xml
  • -Dpegarules.logging.configuration=config/prlogging.xml
  • -Dpegarules.keyring=config/pegarules.keyring
• An Extract rule definition - Provide either:
  • The -i switch and the name (pzInsName) of the Extract rule in the source Pega 7 Platform database.
  • The -I switch and the path and filename of the XML file that contains the XML representation of the Extract rule.
• Optional parameters - Specify ranges of the data to be extracted and other processing configuration. For example, you can:
  • Filter the data by key or date range
  • Specify the number of statements to issue before committing to the target database, or number of records to process before a batch commit,
  • Provide a Pega 7 Platform username and password to allow rule resolution of the Extract rule in the Pega 7 Platform database.

Note: To use the last option listed under "Optional parameters," call the main program com.pega.pegarules.pub.PegaRULES, and provide the username and password to ExtractImpl as the first argument. The resulting statement might look like this:

java -Dpegarules.config="./config/prconfig.xml" -Dpegarules.logging.configuration="./config/prlogging.xml" com.pega.pegarules.pub.PegaRULES com.pega.pegarules.data.internal.access.ExtractImpl -a $USERNAME$ -p $PASSWD$ -i PegaSample!SampleBIX_CSV

You can either:

• Specify the number of threads to run if you are running more than one Extract simultaneously
• Add a unique identifier for the current extract process

See Setting optional command-line BIX parameters for details on all available parameters.

The engine Java classes invoked by BIX are stored in the database and not in the file system. The ExtractImpl class cannot be directly run using the Java interpreter. Instead, run the PegaRULES class and pass the ExtractImpl class as an argument. The PegaRULES class is part of the prbootstrap.jar library.

Example extract on a DB2 system

To run the extract “PegaSample!SampleBIX” on a DB2 system:

java –Xms512m –Xmx768m –classpath
".;lib\prbootstrap.jar;lib\prdbcp.jar;lib\db2jcc_v95.jar;lib\jsr94-1.0.jar;%CLASSPATH%" -Dcom.pega.pegarules.bootstrap.properties.url=config\prbootstrap.properties -Dpegarules.config=config\prconfig.xml -Dpegarules.logging.configuration=config\prlogging.xml -Dcom.pega.pegarules.bootstrap.ignorejndi=true com.pega.pegarules.pub.PegaRULES com.pega.pegarules.data.internal.access.ExtractImpl -i PegaSample!SampleBIX

In this instance, you provide the appropriate path and JDBC driver name.

Related terms

Related information

Open topic with navigation