Applies to Pega Platform versions 7.1.9 through 8.3.1 for Pega Cloud environments only
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: Business Intelligence Exchange for Pega Cloud applications
Customized agent does not run, runs on the wrong node, and other issues
Generated CSV Extract or Manifest file cannot be parsed
Java SQLException for schema generation
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.
|
Symptom (Error) |
Explanation |
Solution |
|---|---|---|
|
Extract fails Pega log file: onPegaCloud is needed to run the extract on cloud instance
|
|
|
|
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.
|
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 BIX parameters and command-line arguments.
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
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 BIX parameters and command-line arguments.
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.
|
Setting Location |
Setting Name |
Description |
Default Value |
|---|---|---|---|
|
prconfig |
Compatibility/BIXUseOptimizedClipboardXML |
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 |
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 |
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 Configuring the Pega Cloud SFTP service to access BIX extract files
|
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
|
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 |
Ruleset: Pega-RULES |
Specifies the relative path on the customer’s SFTP site where the extracted data files are sent. |
“” |
|
DASS |
BIX/ignoreValidation Ruleset: Pega-RULES |
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 |
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 |