Troubleshooting BIX for on-premises environments
-
- Last UpdatedOct 11, 2022
- 5 minute read
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
- Verify that you have specified the configuration settings correctly. For more information, see Specifying configuration settings for BIX in an on-premises environment.
- Ensure that you properly configure the elements in prbootstrap.xml and prconfig.xml when you run a command-line extract. For more information, see Running a BIX command-line extraction in on-premises systems.
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 | Explanation | Solution |
---|---|---|
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).
For more information about editing a DSS value, see Editing a dynamic system setting. |
Generated CSV extract or manifest file cannot be parsed
Symptom | Explanation | Solution |
---|---|---|
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
Symptom | Explanation | Solution |
---|---|---|
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>"/>
Configuring the target database for BIX command-line extractions in on-premises systems. |
Java SQLException for schema generation
Symptom | Explanation | Solution |
---|---|---|
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
Symptom | Explanation | Solution |
---|---|---|
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
Location | Setting name | Description | Default value |
---|---|---|---|
prconfig | Compatibility/BIXUseOptimizedClipboardXML | Optimizes 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 |
prconfig | Compatibility/BIXdisableForwardChaining | Disables 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 |
prconfig | Compatibility/BIXDisableBackwardChaining | Disables 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 |
prconfig | bix/retainOriginalFileNameForCSV | Keeps the original file name for the CSV output. The default value (false) replaces the hyphen (‘- ‘) in the original file name with an underscore (‘_’). | false |
prconfig | bix/removeAdditionalColumnsInCSV | Removes the specified columns from CSV extract files. For example, <env name="bix/removeAdditionalColumnsInCSV" value="pxExtractIdentifier,pxExtractDateTime"/> |
<null> |
prconfig | bix/useHighThroughputDownloadForCSV | Enables 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. |
prconfig | bix/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. | 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 |
DSS | BIX/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 |
On this page
- Common issues
- Query timeout exception
- Generated CSV extract or manifest file cannot be parsed
- BIX extraction process does not generate a manifest file containing data
description language for SQL databases
- Java SQLException for schema generation
- System time zone ignored
- Specifying configuration settings for BIX in an on-premises
environment
Related content
- Configuring an FTP listener to access BIX data extracts in Pega Cloud environments
After a Business Intelligence Exchange (BIX) extraction process in a Pega Cloud environment, obtain the BIX extract files from your Pega Cloud File Storage repository. You can use an FTP listener rule to push the extract files to your enterprise SFTP server.
- 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.
- Using the Job Scheduler rule to extract data with BIX
After you enable the built-in Business Intelligence Exchange (BIX) ruleset on Pega Platform and create a Extract rule, you can schedule Business Intelligence Exchange (BIX) extractions using Pega Platform Job Scheduler rule.
- Running a BIX command-line extraction in on-premises systems
After creating a Business Intelligence Exchange (BIX) Extract rule in Pega Platform, you can directly call the ExtractImpl Java class from the Pega Platform distribution directories to run an BIX extraction process from the command line. Running a BIX extraction process from the command line allows for running an extraction process without requiring the use of Pega Platform to run the process.