Skip to main content


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

Troubleshooting BIX for on-premises environments

Updated on April 6, 2022

When you run a Business Intelligence Exchange (BIX) extraction process from a Pega Platform Extract rule, a Pega Platform Job Scheduler rule, or the command-line, learn to recognize the most common errors in the extraction process in on-premises environments. Refer to the following tables to troubleshoot the root causes and resolve or prevent problems with extractions.

Common issues

When experiencing an issue with a BIX extraction process in an on-premises environment, verify that you have performed the following tasks:

Do not use agents to automate the BIX extraction process. For Pega Platform 8.4 and later, Job Scheduler rules replace agents for automating BIX extraction processes. Clients with agents running BIX extractions should replace the agents with a Job Scheduler rule. For more information, see Replacing an agent with a job scheduler rule and Using the Job Scheduler rule to extract data with BIX.

You can find a record of errors in the BIX extraction processes in the BIX log files. For more information about BIX logging, see BIX logging. For information on common BIX errors, refer to the following sections in this article:

Query timeout exception

Symptom ExplanationSolution
An extraction process fails with a query timeout exception error.Query timeout exception errors can occur when the rule runs against a database table with a significantly larger amount of records than in the previous extract.Increase the query timeout value in the dynamic system settings (DSS).
  • DSS name: BIX/selectQueryTimeout
  • Ruleset: Pega-RULES

For more information about editing a DSS value, see Editing a dynamic system setting.

Generated CSV extract or manifest file cannot be parsed

SymptomExplanationSolution
When you run a command-line extraction, Pega Platform cannot parse a generated CSV extract or CSV manifest file through a downstream process, such as a file listener using a parse delimiter rule.CSV parsing failures can occur when the parse delimiter in Pega Platform interprets the CSV extract and misinterprets the file usage of commas.Add the -l parameter when running the command-line extraction.

For more information, see the following topics.

BIX extraction process does not generate a manifest file containing data description language for SQL databases

SymptomExplanationSolution
An extraction process that uses database schema as the extract file format, that has enabled a manifest (DDL) file to extract to a target database, produces the following error in the log files:

Error: 2020-06-02 19:23:24,783 [ PegaRULES-Batch-4] [ STANDARD] [ ] [ CLM:01.01.27] (ernal.bix.BIXManifestWriterDDL) ERROR G01292608

The Extract rule for SQL database extractions uses dbo as the default schema name. Pega Platform does not provide the option to change the default schema name for SQL extractions in a target database. If your target SQL database schema does not use dbo as the schema name, Pega Platform produces this error when attempting to generate a manifest file in the schema.In the prconfig.xml file, add the following setting to change the default schema name from dbo to the name of your schema into which Pega Platform extracts the manifest file:

<env name="database/databases/<DBName>/defaultSchema" value="<SchemaName>"/>

  • Replace <DBName> with the name of the target database

    in which you want Pega Platform

    to generate the manifest file.

  • Replace <SchemaName> with the name of the schema

    to which Pega Platform generates

    the manifest file in the target database.
For more information, see

Configuring the target database for BIX command-line extractions in on-premises systems.

Java SQLException for schema generation

SymptomExplanationSolution
Schema generation for the target database fails with a Java SQLException, and produces the following error in the log files:

Error: "java.sql.SqlException: A PRPC-supported database platform was not found:

When using a database schema as an output, Pega Platform must support the database version that you are using. Do not extract data to a database that Pega Platform does not support.

For more information about supported databases, see the Pega Platform Support Guide.

System time zone ignored

SymptomExplanationSolution
When you run a command-line extraction or an extraction using the Job Scheduler rule, the BIX extraction process does not consider the time zone when you use the following parameters: -u <start date>, -U <end date>, -d <start date> and -D <end date>.The time zone information must also be passed with the parameters -u <start date>, -U <end date>, -d <start date> and -D <end date>. The time zone must reflect the thread from which the extraction process runs.Include time zone information in parameters for -u <start date>, -U <end date>, -d <start date> and -D <end date>.

For more information, see BIX parameters and command-line arguments

Specifying configuration settings for BIX in an on-premises environment

Ensure that you have specified the following BIX configuration settings to your meet your extraction process requirements:

Configuration settings for BIX in on-premises environments

LocationSetting nameDescriptionDefault value
prconfigCompatibility/BIXUseOptimizedClipboardXMLOptimizes the clipboard to facilitate extracting a large number of class instances to XML.

For more information, see Configuring optional prconfig.xml settings in on-premises systems.

true
prconfigCompatibility/BIXdisableForwardChainingDisables forward-chaining calculations of properties when loading the clipboard for the extraction process.

For more information, see Configuring optional prconfig.xml settings in on-premises systems.

true
prconfigCompatibility/BIXDisableBackwardChainingDisables backward-chaining calculations of properties when loading the clipboard for BIX extract.

For more information, see Configuring optional prconfig.xml settings in on-premises systems.

true
prconfigbix/retainOriginalFileNameForCSVKeeps the original file name for the CSV output. The default value (false) replaces the hyphen (‘- ‘) in the original file name with an underscore (‘_’).false
prconfigbix/removeAdditionalColumnsInCSVRemoves the specified columns from CSV extract files.

For example, <env name="bix/removeAdditionalColumnsInCSV" value="pxExtractIdentifier,pxExtractDateTime"/>

<null>
prconfigbix/useHighThroughputDownloadForCSVEnables high-throughput data downloads for BIX extracts from a BLOB- less class table in a Postgres database for CSV type output.

true *

See Optimizing BIX data extraction performance for conditions.

prconfigbix/getClearTextWhileExtraction

Ruleset: Pega-RULES

Displays encrypted data that is stored in the BLOB as clear text when the data is extracted. The default value (false) disallows clear text and keeps data encrypted.false
DSS BIX/generateXSDForAllProperties

Ruleset: Pega-RULES

Generates XSD when you select GetAllProperties for the XML type output. The default value (false) disallows the generation of XSD for GetAllProperties.

For more information, see Extraction directories by environment.

false
DSS BIX/selectQueryTimeout

Ruleset: Pega-RULES

Specifies the time in seconds before the query to fetch records from the source database times out.30s
DSSBIX/setCommandLineDelimiterForCSVManifestFile

Ruleset: Pega-RULES

By default, the command line option -l is applicable to the CSV output file only. Change the default value of this DSS to true to override the default setting and enable this option for the CSV Manifest as well.

For more information, see the following topics:

false
  • Previous topic Running a BIX command-line extraction using ANT build files in on-premises systems
  • Next topic BIX logging

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