Skip to main content


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

Troubleshooting BIX in Pega Cloud environments

Updated on April 6, 2022

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

Common issues

When you want to diagnose an issue with a BIX extraction process in a Pega Cloud environment, first verify that you have specified the BIX configuration settings correctly. For more information, see Specifying configuration settings for BIX in a Pega Cloud environment.

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:

An extraction process using filter conditions or parameters with the Job Scheduler causes several errors

The following solutions apply when you run the extraction process using filter conditions or parameters through the Job Scheduler to retrieve class instances. The data extraction writes the requested data from the BLOBs of the class instances to a set of files in a temporary folder, compresses the files, and then copies the ZIP file to the folder location specified in the Pega-RULES!BIX/sharedpath dynamic system setting (DSS).

SymptomExplanationSolution
An extraction process fails and produces the following error in the log files:

:onPegaCloud is needed to run the extract on cloud instance

The Pega-RULES!onPegaCloud DSS is not set to true. Set the DSS setting for onPegaCloud to true.
  • DSS setting: onPegaCloud
  • Ruleset: Pega-RULES
For more information about editing a DSS value, see Editing a dynamic system setting.
The run-time environment is not correctly identified as Pega Cloud.Set BIX/sharedpath to a folder location with read-write access for Pega Platform.
An extraction process does not fail, but it does not extract the data based on the configured Extract rule.The filter conditions in the Extract rule are incorrect, and the incorrect set of instances is selected.Correct the Filter conditions of the Extract rule.

For more information about filter criteria, see Creating and running an Extract: Filter Criteria.

An extraction process fails.

For CSV extraction, the error logged is: Error while adding csv data

For XML extraction, the error logged is:

Could not write object" for xml extraction

For Manifest files, the error logged is: Could not write manifest summary

For an IOException, the error logged is: No space left on device

There is not enough space in the temporary folder used when generating files.Increase the space allotted to the folder that is used to store temporary files.
An extraction process fails and produces the following error in the log files:

Error creating zip file

For an IOException, the error logged is: No space left on device

There is not enough space in the folder used to save the compressed file.Increase the space allotted to the folder that is used to store the compressed file.
An extraction process fails and produces the following error in the log files:

Error creating zip file (with the relevant stack trace).

A problem occurred during compression.File a service request with Pega Cloud services that contains the logged stack trace.
An extraction process fails and produces the following error in the log files:

Unable to process <Extract classname> (with the relevant stack trace).

BIX generates an error during its run for some other reason, for example, after running out of memory.File a service request with Pega Cloud services that contains the logged stack trace.

Transfer fails when File Listener invokes FTP data instance for new compressed files that are transported to target FTP location

The following solutions apply when you use a File Listener to access your extract files. File Listeners determine when a new compressed file has been written to the folder location and invoke the FTP data instance in order to transfer the file. Transfer of the file to the target FTP site can then fail for several reasons.

Symptom ExplanationSolution
The file transfer fails and the file remains in the shared path location: <sharedpath>/work_BIXFTP listener.

The error logged is: FTP connection failed.

A defect in the file listener causes the compressed file to remain in the folder without Pega Platform invoking the FTP data instance.Verify the correct configuration of the FTP listener rule. For more information, see Configuring an FTP listener to access BIX data extracts in Pega Cloud environments.
The file transfer fails and the file remains in the location of

<sharedpath>/work_BIXFTPListener/completed.

The file uses an .err extension.

The error logged is: FTP connection failed. Logon failure: unknown username or bad password

The Environment tab of the FTP Server data instance BIXFTPServer is not correctly configured to access the customer’s FTP site, and the transfer does not take place.Verify the correct configuration of the Environment tab of the FTP Server data instance. For more information, see step 3.b of Configuring an FTP listener to access BIX data extracts in Pega Cloud environments.
The file transfer fails and the file remains in the location of:<sharedpath>.

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

The Authentication Profile data instance BIXFTPAuthProfile is not correctly configured with the login credentials of the FTP Server.Verify the correct configuration of the Authentication profile. For more information, see step 3.c of Configuring an FTP listener to access BIX data extracts in Pega Cloud environments.
The File Listener cannot poll for the ZIP file, and the file remains in the location of <sharedpath>.The Service Package data instance BIXFTPServicePackage is not correctly configured with the operator access group.Verify the correct configuration of the Service Access Group. For more information, see step 4.b of Configuring an FTP listener to access BIX data extracts in Pega Cloud environments.
The file transfer fails and the file remains in the location of <sharedpath>/work_BIXFTPListener/completed with .err extension.

The error logged is: FTP connection failed.

  • The File Listener BIXFTPListener has not been enabled by clearing the Block Startup check box.
  • VPN tunnel to client is not set up.
  • Client FTP site is unavailable.
  • Network outage occurs during transfer.
Verify that you have cleared the Block Startup option. For more information, see step 5.b of Configuring an FTP listener to access BIX data extracts in Pega Cloud environments. For other issues, check the network connections between you and your Pega Cloud environment.
File transfer is not processed by the BIXFTPListener after trying to transfer files to client SFTP location.

Error logged: Error: Failed check sum validation for <Filename>.zip

This error usually indicates that the ZIP file content has been modified or tampered with since the time it was generated in the Pega Cloud environment. This usually does not happen in a production environment.Turn off checksum validation that detects that the file has been modified through the associated dynamic system setting.

  • DSS name: BIX/ignoreValidation
  • Ruleset: Pega-RULES
  • Value: true

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

The file transfer fails with no error in the BIX logs.Pega Platform places BIX logs in temporary file location.Verify your BIX logs to identify the temporary location of all the extracted files on the Pega Cloud instance. File a service request for Pega Cloud services to retrieve the files.
Pega Platform creates an .ERR file instead of a .ZIP after file transfer.Make a request to Pega Cloud services to recover the file by modifying .ERR to .ZIP.

Extraction process fails with query timeout exception

Symptom ExplanationSolution
An extraction process fails with a query timeout exception error.A query timeout exception error 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 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 an extraction process using a Job Scheduler with additional parameters, Pega Platform cannot parse the 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 extraction process through the Job Scheduler.

For more information, see the following topics.

Java SQLException for schema generation

SymptomExplanationSolution
Schema generation for the target database fails with a Java Exculpation, 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 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 a Pega Cloud environment

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

Configuration settings for BIX in a Pega Cloud environment

LocationSetting nameDescriptionDefault value
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
DSSBIX/sharedPath

Ruleset: Pega-RULES

Specifies the location of the shared path where files are copied. Applicable only when BIX/useCustomersSFTP DSS is set to true.file://pegacloudrepository:/bix
DSSBIX/useCustomersSFTP

Ruleset: Pega-RULES

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

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

For more information, see Configuring the Pega Cloud SFTP service to access BIX extract files.

false
DSSBIX/relativeDestinationPathOnCloud

Ruleset: Pega-RULES

Specifies the location in the Pega Cloud Services File Storage repository to send extract files.<Customer_Rootpath>/bix
DSSBIXFTPRelativeRemotePath

Ruleset: Pega-RULES

Specifies the relative path on the client SFTP site to send extract files.
DSSBIX/ignoreValidation

Ruleset: Pega-RULES

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

The default value (false) enables checksum validation.

For more information, see step 8 of Creating and running an Extract rule.

false
  • Previous topic Configuring an activity to access BIX extract files
  • Next topic Overview of BIX extractions in on-premises environments

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