Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Overview of BIX extractions in on-premises systems

Updated on April 6, 2022

Pega Business Intelligence Exchange (BIX) extracts application class data from your on-premises Pega Platform environment. For on-premises systems, BIX is available when you purchase and install the BIX application.

After enabling the BIX ruleset for your on-premises application, you can extract application class data manually through the Extract rule, through the Job Scheduler rule, or through the command-line interface. When you run extracts in an on-premises environment, note the following:

  • CSV, XML, manifests, and DDL files are sent to a directory local to your application server.
  • Database extracts require providing your database administrator (DBA) a DDL file required to format external database tables.

Running BIX extractions

Pega Business Intelligence Exchange (BIX) extracts application class data from your on-premises Pega Platform environment. Business Intelligence Exchange (BIX) extracts for on-premises applications are available to run through an Extract rule, Job Scheduler rule, or command-line interface.

  1. Enable BIX on your application. For more information, see Enabling the BIX ruleset.
  2. Create and run an initial extract rule. For more information, see Creating and running an Extract rule.:
  3. Configure the Pega Platform database from which you want to extract data. For more information, see Configuring the source database for BIX command line extractions .
  4. For Database Schema extractions, configure the target database to which you want to extract data. For more information, see Configuring the target database for BIX command line extractions.
  5. Optional: To save information about the command-line extractions in a log file, configure command line BIX logging. For more information, see Configuring BIX logs for command-line extractions in on-premises systems.
  6. To store usernames and passwords in an encrypted form, enable password encryption for command-line BIX extractions. For more information, see Enabling password encryption for BIX command-line extractions in on-premises systems.
  7. Run the command line extraction process. For more information, see Running a BIX command-line extraction in on-premises systems.

BIX parameters and command-line arguments

Pega supports running Business Intelligence Exchange (BIX) from a Pega Platform Job Scheduler rule, or the command-line, in on-premises systems. You can input various parameters to filter what is extracted from your application as described in the following table.

ParameterDescription
-a <username> Rule resolve Rule-Admin-Extract instances based on the user access group.
Note: This option is not available when running an Extract rule with pxExtractDataWithArgs.
-b <number of updates before a batch is issued> Specify the batch size (the number of extracted class instances) for commits to a relational database.

This option only applies to databases with JDBC drivers that support batch updates.

Note: This option is not available when running an Extract rule in the Pega Cloud.
-B Specify how to format extracted Boolean values. The options are:
  • 10
  • YN
  • YesNo
  • yesno
  • TF
  • TrueFalse
  • truefalse
  • YESNO
  • TRUEFALSE
-cInclude children classes.

Use this parameter to extract the data for each sibling class of the class (class group/non-class group) for which the extract is defined.

Note: This option is not available for high-throughput CSV downloads. For more information, see .
-d <start date> Only extract instances with a pxCreateDateTime equal to or greater than <start date>.

<start date> must be in the format “20110823T164017.000”, following the Java pattern “yyyyMMddTHHmmss.SSS”.

Note: Clear the Use Last Updated Time as Start check box on the Filter Criteria tab of the Extract form when you use this parameter, because it does not override the check box setting.
-D <end date> Only extract instances with a pxCreateDateTime equal to or less than <end date>.

<end date> must be in the format “20110823T164017.000”, following the Java pattern “yyyyMMddTHHmmss.SSS”.

Note: Clear the Use Last Updated Time as Start check box on the Filter Criteria tab of the Extract form when you use this parameter, because it does not override the check box setting.
-fForce the extract to stop at the first error that it encounters. This option only works with a batch size greater than 1.

See BIX logging and error handling for information on conditions where encountering an error does not force the extract to stop.

Note: This option is not available when running an Extract rule in the Pega Cloud.
-g <start date> Only extract instances with a pxCommitDateTime equal to or greater than <start date>.

<start date> must be in the format "20110823T164017.000", following the Java pattern "yyyyMMddTHHmmss.SSS" and relative to the local time zone.

Note: Clear the Use Last Update Time as Start check box on the Filter Criteria tab of the Extract form when you use this parameter, because it does not override the check box setting.
-G <end date>Only extract instances with a pxCommitDateTime equal to or less than <end date>.

<end date> must be in the format "20110823T164017.000", following the Java pattern "yyyyMMddTHHmmss.SSS" and relative to the local time zone.

Note: Clear the Use Last Update Time as Start check box on the Filter Criteria tab of the Extract form when you use this parameter, because it does not override the check box setting.
-i <InstanceName>Specify the pxInsName of the Rule-Admin-Extract or a comma-delimited list of Rule-Admin-Extract instances.
Note: This option is not available when running an Extract rule with pxExtractDataWithArgs.
-I <path and filename>Use an Extract rule specified in an external file in XML format. See Using a stand-alone command-line BIX extract process.
Note: If an extract has any filter that uses unexposed property references that are passed in by the external file, then extraction fails with the following exception: “Please enter or select a property that is exposed as a column in the database.”

This option is not available when running an Extract rule with pxExtractDataWithArgs.

-J Specify the time zone that you want to convert DateTime properties to when extracting to XML or CSV output. You can specify the time zone in the following formats:
  • Time zone with an ID: For example, to specify America/Los_Angeles. Specify this time zone as "-J""America/Los_Angeles"
  • Three letter time zone: For example, to specify India Standard Time, use "-J" "IST"
  • UTC+/-dd:dd: Specify UTC plus or minus hours and minutes. For example, "-J" "UTC+5:30"

If not specified, the default is GMT.

-k <Identifier>Add a unique identifier for this run. Use alphanumeric characters or underscores only with no spaces.
Note: This option is not available when running an Extract rule in the Pega Cloud.
-l <delimiter>Specify a user-defined character as the delimiter separating extracted data.
Note: The following characters are not available for use as delimiters, as they signify other things to BIX:
  • Double-quote (“)
  • Asterisk (*)
  • Hyphen (-)

BIX also does not support multi-line delimiters. If the delimiter length is greater than 1, then BIX reports an error.

-nRetrieves class instances that satisfy the filter conditions with an Extract rule from the Pega Platform production database without sorting them by how recent they are. This improves performance, but makes it impossible to perform a partial re-extraction following any errors.
-oOverrides the default setting that combines filter conditions specified on pxCreateDateTime and pxUpdateDateTime using the AND Boolean operator and instead combines them using the OR Boolean operator.
-p <password> Rule resolve Rule-Admin-Extract instances based on the user access group.
Note: This option is not available when running an Extract rule with pxExtractDataWithArgs.
-POverrides the output directories specified on the File Specification tab in the Extract rule form.

When specified, all output files are directed to this location.

Note: This option is not available when running an Extract rule with pxExtractDataWithArgs.
-s <number>No longer supported.
-t <threads>No longer supported.
-u <start date>Only extract instances with a pxUpdateDateTime equal to or greater than <start date>.

<start date> must be in the format “20110823T164017.000”, following the Java pattern “yyyyMMddTHHmmss.SSS”. You can also optionally include the time zone, for example, "20110823T164017.000 GMT". If you do not include the time zone, the time zone is the locale that is set on the thread or the default locale of "en_US" and time zone of "EST".

Note: Clear the Use Last Updated Time as Start check box on the Filter Criteria tab of the Extract form when you use this parameter because it does not override the check box setting.
-U <end date>Only extract instances with a pxUpdateDateTime equal to or less than <end date>.

<end date> must be in the format “20110823T164017.000”, following the Java pattern “yyyyMMddTHHmmss.SSS”. You can also optionally include the time zone, for example, "20110823T164017.000 GMT". If you do not include the time zone, the time zone is the locale that is set on the thread or the default locale of "en_US" and time zone of "EST".

Note: Clear the Use Last Updated Time as Start check box on the Filter Criteria tab of the Extract form when you use this parameter because it does not override the check box setting.
-xInclude header and footer information for XML or CSV output.
Note: This option is not available for high-throughput CSV downloads. For more information, see .
-X <Path><FileName>Generate only a set schema file for the export. No data is exported.

To use the -X parameter, the output format of the Rule-Admin-Extract rule that you specify must be Database schema. If the output format is XML or CSV, a PRRuntimeException is generated.

Note: This option is not available when running an Extract rule in the Pega Cloud.
-z <start key> Only extract instances with a pzInsKey equal to or greater than <start key>.
Note: The comparison is character by character with the pzInsKey and is not an integer comparison with the work object's ID.
-Z <end key> Only extract instances with a pzInsKey equal to or less than <end key>.
Note: The comparison is character by character with the pzInsKey and is not an integer comparison with the work object's ID.

The pzInsKey values of class instances whose extraction resulted in errors are logged automatically. You do not need to set a flag to enable this behavior.

Note: When running a BIX extract from command-line on UNIX using the -u, -U, -d, or -D parameters, you need to set the timezone using a JVM argument, such as: -Duser.timezone="America/New York". For more information, see Pega Community article Formatting time in BIX.

  • Previous topic Troubleshooting BIX in Pega Cloud environments
  • Next topic Running a BIX command-line extraction in on-premises systems

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us