Running a BIX command-line extraction in on-premises systems
After you configure your source database environment, you can run the Business Intelligence Exchange (BIX) command-line extraction process.
This content only applies to on-premises systems and is not supported in Pega Cloud environments.
Complete the following tasks:- Create an Extract rule. For more information, see Creating and running an Extract rule.
- Obtain the Extract rule label.
- Obtain the directory for the
prconfig.xml
,prbootstrap.properties
, andprlog4j2.xml
files. For more information, see Configuring the source database for BIX command-line extractions in on-premises systems. - Obtain the PegaRules username and password created during the source database configuration.
- If you enabled password encryption, obtain the file path for
pegarules.keyring
. For more information, see Enabling password encryption for BIX command-line extractions in on-premises systems. - Obtain the names of JAR files in the
lib
directory for the Pega Platform source database.
- In the command line, begin a Java call by specify your initial and maximum JVM memory
with the Xms and Xmx parameters.
- Set the initial Java heap size to 512m (-Xms512m).
- Set the maximum heap size to at least 768m (-Xmx768m).
For example: java -Xms512m –Xmx768m
- Reference the file path for the BIX
prconfig.xml
,prbootstrap.properties
, and (if used)prlog4j2.xml
files by using the following parameters:- For the
prconfig.xml
file, enter -Dpegarules.config=<prconfig_filepath>. - For the
prbootstrap.properties
file, enter -Dcom.pega.pegarules.bootstrap.properties.url=<bootstrap.properties_filepath>. - Optional: For the
prlog4j2.xml
file, enter -Dpegarules.logging.configuration=<prlog4j2_filepath>.
For example: -Dpegarules.config=./config/prconfig.xml -Dpegarules.logging.configuration=config/prlog4j2.xml -Dcom.pega.pegarules.bootstrap.properties.url=config/prbootstrap.properties
- For the
- If you enabled password encryption, add the file path for the
pegarules.keyring
file.For more information, see Enabling password encryption for BIX command-line extractions in on-premises systems. - Disable Java Naming and Directory Interface (JNDI) databases to extract from the
configured source Java Database Connectivity JDBC URL database by using the following
parameter:
-Dcom.pega.pegarules.bootstrap.ignorejndi=true
- Specify the location of .JAR files that are used in the BIX source database library
(
lib
) directory by setting the classpath with the parameter -classpath.Include quotes (" ") around the classpath value.For example: -classpath ".;lib\prbootstrap.jar;lib\prdbcp.jar;lib\db2jcc_v95.jar;lib\jsr94-1.0.jar;$CLASSPATH$"
- Optional: To use a username and password with the
-a
and-p
parameters for the extract files according to your source database configuration, call com.pega.pegarules.pub.PegaRULESNote: If you enabled password encryption for BIX command-line extractions, you do not need to call PegaRules with the username and password elements. For details, see Enabling password encryption for BIX command-line extractions in on-premises systems. For example: com.pega.pegarules.pub.PegaRULES com.pega.pegarules.data.internal.access.ExtractImpl -a $USERNAME$ -p $PASSWD$
- Call the Extract Java class
com.pega.pegarules.data.internal.access.ExtractImpl and specify an
Extract rule label with the
-i
parameter.For example: com.pega.pegarules.pub.PegaRULES com.pega.pegarules.data.internal.access.ExtractImpl -a $USERNAME$ -p $PASSWD$ -i SampleBIX_CSV
- Enter the node type and node type and node settings for the extract process.
For example: -DNodeType=BIX -DNodeSettings="Pega-IntegrationEngine/disableEpochDateTime=false;Pega-IntegrationEngine/disableEpochDate=false;Pega-RulesEngine/EnableAttributeBasedSecurity=false"
- Optional: To customize your configuration, include additional command-line extraction parameters. For more information, see BIX parameters and command-line arguments.
For example: You can add the following functionality with additional BIX parameters: - Filter the data by date range.
- Specify the number of records to process before a batch commit.
- Include child classes in the extract files.
- Optional: To use an external XML file for the extraction process, perform the following actions:
Note: This step requires running an instance of Pega Platform - In the navigation pane of Dev Studio, click , and then select the Extract rule to run.
- On the rule form, click .
- Copy the resulting page and save the content as an XML file.
- Begin the command-line extraction method as in step 1.
- When you call
com.pega.pegarules.data.internal.access.ExtractImpl to specify an
Extract rule label, provide the file path in which you created the XML file and the
XML file name with the parameter and arguments
-I <filepath> <DDL filename>
.
For example: com.pega.pegarules.pub.PegaRULES com.pega.pegarules.data.internal.access.ExtractImpl -I ./XMLpath External_XML
- Perform the command-line extraction by running the Java method.
Note: For Database Schema extractions, ensure that your DBA formats the target database by using the DDL file. For more information, see Generating a DDL file for command-line Database Schema extractions. For example: A complete command-line extraction method: java –Xmx768m java -Dpegarules.config=./config/prconfig.xml -Dpegarules.logging.configuration=config/prlog4j2.xml -Dcom.pega.pegarules.bootstrap.properties.url=config/prbootstrap.properties -Dcom.pega.pegarules.bootstrap.ignorejndi=true -classpath ".;lib\prbootstrap.jar;lib\prdbcp.jar;lib\db2jcc_v95.jar;lib\jsr94-1.0.jar;$CLASSPATH$" com.pega.pegarules.pub.PegaRULES com.pega.pegarules.data.internal.access.ExtractImpl -a $USERNAME$ -p $PASSWD$ -i SampleBIX_CSV -DNodeType=BIX -DNodeSettings="Pega-IntegrationEngine/disableEpochDateTime=false;Pega-IntegrationEngine/disableEpochDate=false;Pega-RulesEngine/EnableAttributeBasedSecurity=false"
- Generating a DDL file for command-line Database Schema extractions
For Database Schema extractions, generate a DDL file to share with your database administrator (DBA) so that they can format the external database table for extractions.
Previous topic Enabling password encryption for BIX command-line extractions in on-premises systems Next topic Generating a DDL file for command-line Database Schema extractions