Close popover

Table of Contents

Troubleshooting BIX for on-premises environments

This content applies only to On-Premises Services environments.

Common issues

Recognize the common symptoms and errors of Business Intelligence Exchange (BIX) for on-premise environments. Understand the explanations (root causes) of these symptoms and how to resolve or prevent problems.

Ensure that you have specified the configuration settings correctly.

If you are running BIX for on-premise environments, you can run BIX extracts from the command line. Properly configured settings in the prbootstrap.xml and prconfig.xml files are required. in these files when booting the Pega engine using these file settings. For more information, see 

You can run BIX for on-premise environments using the command line or using an agent.

You can also run extracts manually from the Extract rule.

Customized agent does not run, runs on the wrong node, and other 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 (DDL) for SQL databases

Java SQLException for schema generation

System time zone ignored

Customized agent does not run, runs on the wrong node, and other issues

Symptoms

A customized agent that uses the activity pxExtractDataWithArgs to run a BIX extract for a specific class can trigger the following symptoms:

  • The agent does not run or runs at the wrong time.
  • Agent is run on the wrong node.
  • Selected class or rule does not exist.

The Extract rule <ClassName>!<RuleName> does not exist. Please check the classname and the extract rule name.

  • Command-line parameter string supplied to activity is invalid.

Invalid pyArgs specified

Explanation

There will be a dedicated node for batch processes like BIX that will not participate in load balancing for the cluster. The agent should always run on that node.

Solution

To resolve custom agent problems, in the Admin Studio, verify the following information:

  • Agent status and last run information
  • Node and respective Agent information
  • The Class name and the Extract rule name
  • A valid command-line parameter provided to the activity pxExtractDataWithArgs

Query Timeout Exception

Symptom

An Extract Rule fails with a Query Timeout Exception.

Explanation

An Extract Rule fails with a QueryTimeout Exception when the rule is run against a database table with a significantly higher number of records than usual.

Solution

To resolve Query Timeout Exceptions, increase the timeout by setting the DASS:

DASS NAME: BIX/selectQueryTimeout

RULESET : Pega-RULES

Generated CSV Extract or Manifest file cannot be parsed

Symptom

A generated CSV Extract or CSV Manifest file could not be parsed by a downstream process. For example, a File Listener is using a parse delimiter rule.

Explanation

CSV parsing failures can occur when the Parse Delimiter rule in Pega is used to interpret the CSV extract. Because the default delimiter used to generate the extract is “, ” (read as comma space) , the space might not be properly interpreted.

Solution

To resolve CSV parsing failures, set the delimiter “,” explicitly using the command line option -l.

See the Help topics:

Running the command-line extraction process

Optional command-line BIX parameters

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

Symptom

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

Explanation

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 the error described above during the extraction process when attempting to generate a manifest file in the schema.

Solution

In the prconfig.xml file, add the following setting to change the default schema from dbo to the name of your schema into which Pega Platform extracts the manifest file:

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

Replace <TargetDBName> 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.

Java SQLException for schema generation

Symptom

Schema generation for the target database table fails with a Java SQLException.

Error: “java.sql.SQLException: A PRPC-supported database platform was not found:”

Explanation

When extracting to a database, the destination database must be supported by the Pega Platform version that you are using. The Pega Platform does not support MySQL:

Pega Infinity Platform Support Guide

Pega 7 Platform Support Guide

Solution

To prevent database errors such as SQLExceptions, do not attempt to extract data to a database application that the Pega platform does not support. Always refer to the Pega Platform Support Resources.

System time zone ignored

Symptom

BIX extraction does not consider the system time zone when the Extraction command line options -u / -U or -d/-D are used.

Explanation

While passing the value for -u /-U command line option, you forgot to include the tIme zone information. The time zone is the locale that is set on the thread or the default locale of “en_US” and the timezone of “EST”.

Solution

To prevent time zone issues with your extracted data, remember to include time zone information in your command line options for -u /-U. For example, 20110823T164017.000 GMT.

See Optional command-line BIX parameters.

Specifying configuration settings for BIX in on-premises environments

Ensure that you have specified the configuration settings correctly.

  • Use the individual prconfig.xml files for each Pega Platform server.
  • Use Data-Admin-System-Settings (DASS) instances for each cluster.

 

Configuration settings for BIX in on-premises environments

Setting Location

Setting Name

Description

Default Value

prconfig      

prconfig

Compatibility/BIXUseOptimizedClipboardXML

Configuring optional prconfig.xml settings

Optimizes the clipboard to facilitate extracting a large number of class instances to XML

true

prconfig

Compatibility/BIXdisableForwardChaining

Configuring optional prconfig.xml settings

Disables forward-chaining calculations of properties when loading the clipboard for BIX extract

true

prconfig

Compatibility/BIXDisableBackwardChaining

Configuring optional prconfig.xml settings

Disables backward chaining of properties when loading the clipboard for BIX extracts

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

 

Example:

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

Removes the specified columns from the generated CSV output file.

 

“”

prconfig

bix/useHighThroughputDownloadForCSV

Business Intelligence Exchange (BIX) 8.1 User Guide, the sections Configuring optional prconfig.xml settings and BIX performance recommendations.

Enables high-throughput data downloads for BIX extracts from a BLOB- less class table in a Postgres database for CSV type output.

true

prconfig

bix/getClearTextWhileExtraction

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

DASS

BIX/generateXSDForAllProperties

 

Ruleset: Pega-RULES

 

Generating an XSD file for XML output

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

false

DASS

BIX/selectQueryTimeout

 

Ruleset: Pega-RULES

Specifies the time in seconds before the query to fetch records from the source database times out. The default value is 30 seconds.

30s

DASS

BIX/setCommandLineDelimiterForCSVManifestFile

 

Ruleset: Pega-RULES

 

Optional command-line parameters for BIX

 

Running the command-line extraction process

 

Extract rules - Completing the File Specification tab

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

false


Related Content

Have a question? Get answers now.

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