Table of Contents

Troubleshooting BIX for Cloud environments

This content applies only to Cloud 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 Cloud environments, you run BIX extracts using an agent. (You cannot run BIX for Cloud environments using the command line.)

You can also run extracts manually from the Extract rule.

Reference: Running BIX in the Pega Cloud

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

Extract rule for the BIX Cloud environment using customized command-line parameters, Extract filter conditions, and file compression triggers several errors

Transfer fails when File Listener invokes FTP data instance for new compressed file being transported to the customer's FTP site

Query Timeout Exception

Generated CSV Extract or Manifest file cannot be parsed

Extract fails to be processed by BIXFTPListener while it tries to transfer the files to customer SFTP location

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 do 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

 

Extract rule for the BIX Cloud environment using customized command-line parameters, Extract filter conditions, and file compression triggers several errors

Here is the scenario: You run the Extract rule using customized by the command-line parameters to retrieve class instances identified by the filter conditions of the Extract rule. The data extraction writes the requested data from the BLOBs of the class instances to a set of files in a temporary folder, compresses them, and copies the ZIP file to the folder location specified in the DASS Pega-RULES!BIX/sharedpath.

Custom command-line scenario with filters and compression

Symptom (Error)

Explanation

Solution

Extract fails

Pega log file:

onPegaCloud is needed to run the extract on cloud instance

 

  • DASS Pega-RULES!onPegaCloud not set to true
  • Run-time environment not correctly identified as Pega Cloud
  • Set Pega-RULES!onPegaCloud to true.
  • Specify the correct RTE for Pega Cloud.

Extract fails

BIX log file:

Error creating zip file:<filepath>.zip (The system cannot find the path specified)

DASS Pega-RULES!BIX/sharedpath not set to a valid folder location to which Pega Platform has read-write access

Set Pega-RULES!BIX/sharedpath to folder location with read-write access for Pega Platform.

Extract does not fail, but it extracts the data based on the configured Extract rule.

Filter conditions in the Extract rule are incorrect, and the wrong set of instances is selected.

Correct the Filter conditions of the Extract rule.

Extract fails

For CSV extraction

Error while adding csv data

For XML extraction

Could not write object" for xml extraction

 

For Manifest files

Could not write manifest summary

 

IOException

No space left on device

Not enough space in temporary folder for generated files

Increase the space allotment for temporary files.

Extract fails

Error creating zip file

IOException

No space left on device

Not enough space in folder for compressed file

Increase the space allotment for folder storing compressed file.

Extract fails

Error creating zip file

with the relevant stack trace

Problem occurs during compression.

 

Extract fails

Unable to process <Extract classname>

with the relevant stack trace

BIX generates an error during its run for some other reason, for example, out of memory.

 

 

Transfer fails when File Listener invokes FTP data instance for new compressed file being transported to the target FTP site

Here is the scenario: A file listener determines when a new compressed file has been written to the folder location and invokes the FTP data instance. But transfer of the file to the target FTP site fails for several reasons.

Transfer fails File Listener FTP data instance for compressed file

Symptom (Error)

Explanation

Transfer fails

FTP connection failed

The file can be found at the location <sharedpath>/work_BIXFTPListener.

Defect in file listener causes the compressed file to remain in the folder without the FTP data instance being invoked.

Transfer fails

FTP connection failed. Logon failure: unknown username or bad password

The file can be found at the location <sharedpath>/work_BIXFTPListener/completed with the .err extension.

The Environment tab of the FTP Server data instance BIXFTPServer is not correctly configured to access the customer’s FTP site, and transfer does not take place.

Transfer fails

InvalidConfigurationException: No such Rule-Application instance <Access group's application name>

The file can be found at the location <sharedpath>.

The Authentication Profile data instance BIXFTPAuthProfile is not correctly configured with the login credentials of the FTP Server.

The File Listener cannot poll for the ZIP file, and the file remains at the location <sharedpath>.

The Service Package data instance BIXFTPServicePackage is not correctly configured with the operator’s access group.

Transfer fails

FTP connection failed

The file can be found at the location <sharedpath>/work_BIXFTPListener/completed with the .err extension.

The File Listener BIXFTPListener has not been enabled by clearing the Block Startup check box.

Transfer fails

FTP connection failed

The file can be found at the location <sharedpath>/work_BIXFTPListener/completed with the .err extension.

VPN tunnel to client is not set up.

Transfer fails

FTP connection failed

The file can be found at the location <sharedpath>/work_BIXFTPListener/completed with the .err extension.

Client’s FTP site is unavailable.

Transfer fails

FTP connection failed

The file can be found at the location <sharedpath>/work_BIXFTPListener/completed with the .err extension.

Network outage occurs during transfer.

 

Solution

If there is no error in the BIX logs, indicating that file generation was successful, but that file transfer failed, take the following actions:

  • Check the BIX logs to identify the temp location of all the extracted files on the cloud instance and request the cloud administrator to retrieve them.
  • Request the cloud administrator to recover the ZIP file from the subdirectory <source location>/work_BIXExtractListener/completed by modifying the <filename>.err to <filename>.zip.

Query Timeout Exception

Symptom

An Extract Rule fails with a Query Timeout Exception.

Explanation

An Extract Rule fails with a Query Timeout 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

Extract fails to be processed by BIXFTPListener while it tries to transfer the files to client’s SFTP location

Symptom

BIX log shows the error:  Error: Failed check sum validation for <FileName>.zip

Explanation

This error usually indicates that the ZIP file content has been modified or tampered with since the time it is generated in the EC2 instance. This usually does not happen in a production environment.

Solution

If there is a need to turn off checksum validation to detect that file has been modified, then set the DASS BIX/ignoreValidation to true. See Specifying configuration settings for BIX in On-Premise environments.

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 you extract data 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 Cloud 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 Cloud environments

Setting Location

Setting Name

Description

Default Value

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/sharedPath

Ruleset: Pega-RULES

Specifies the location of the shared path where files are copied. Applicable only when BIX/useCustomersSFTP DASS is set to true

/usr/local/tomcat/work/BIXExtracts

DASS

BIX/useCustomersSFTP

Ruleset: Pega-RULES

Obtaining BIX extract files from the Pega SFTP server

Specifies the client’s SSH File Transfer Protocol (SFTP) site for data transfer.

The default value (false) overrides this to use the Pega Cloud SFTP data transfer site.

false

DASS

BIX/relativeDestinationPathOnCloud 

Ruleset: Pega-RULES

Defining SFTP-related data instances

If extracted data is specified for storage in the Pega Cloud® Services File Storage repository, the default storage location is <Customer_Rootpath>/bix.

Change this value by specifying the path relative to the default storage location.

“”

DASS

BIXFTPRelativeRemotePath

Ruleset: Pega-RULES

Defining SFTP-related data instances

Specifies the relative path on the customer’s SFTP site where the extracted data files are sent.

“”

DASS

BIX/ignoreValidation

Ruleset: Pega-RULES

Extract rules - Completing the File Specification tab

Specifies ignoring checksum validation when the File Listener processes the extract files from the path represented by the BIX/SharedPath DASS.

The default value (false) enables checksum validation.

 

When completing the File Specification tab of the Extract rule, the Database Schema Manifest, in the field Include check total property, you can select an extract property to use as a "checksum" for the extract.

false

DASS

BIX/setCommandLineDelimiterForCSVManifestFile

Ruleset: Pega-RULES

Optional command-line BIX parameters

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

 

 
Suggest Edit

100% found this useful


Related Content

Have a question? Get answers now.

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