BIX error handling

Errors normally cause the BIX application to terminate, however, the application may continue to run following certain exceptions:

  • An invalid class definition for a single class described in a set of XML files
  • An invalid property definition
  • An invalid property transformation to the specified data type

BatchUpdateException error

Committing an extract batch of class instances to a relational database may be interrupted because of issues with the data, syntax errors, a database constraint violation, or some other issue raised by the database.

Different databases respond differently to batch update exceptions. Generally, the database throws a BatchUpdateException error, which BIX records in the PegaBIX log file.

When an error occurs, BIX behaves differently depending on the database platform that it is working with: Oracle, MS-SQL, Db2 LUW, or Db2 for z/OS servers.

Troubleshooting BatchUpdateException for databases other than Oracle

The server continues processing the operations in a batch even if one of the operations caused a database error. The database returns an exception that contains the exact information of the record in error. This information can be used to pinpoint the failure to the pzInskey of the record involved.

In this scenario, BIX supports two modes of execution:

  • Continue processing records even when there are failures (the default mode)
  • Stop processing when the first error is encountered

In default mode, all successful inserts are committed and the pzInsKeys of the failing entries are listed in the log file.

To rectify the work object and rerun the extract, specify the same value for pzInskey in the –z and –Z options.

Note: When the –f option is in effect, the extraction process terminates after the first error is encountered. All successful batch inserts up to that point are committed. The batch that caused the failure is rolled back completely.

Troubleshooting BatchUPdateException for Oracle

Oracle stops processing the remaining operations in the batch if it encounters an error. The exception returned by the database does not point to the exact operation that caused the exception. For that reason, all of the pzInsKeys of the records in the batch are included in the BIX error log. The records from the batch that were successfully committed are not indicated because the Oracle driver does not provide that information.

In this scenario, BIX supports two modes of execution:

  • Continue processing the records even when there are failures (the default mode)
  • Fail on first error

In default mode, all successful inserts up to the record that failed are committed and the entries in the batch that followed the error entry are not processed. All of the pzInsKeys of that batch are written out to the log file.

To rectify the error and rerun BIX for the remaining records in the batch, specify the pzInsKey range for the remaining records using the –z and –Z options.

Note:
  • When the –f option is in effect, the extraction process terminates after the first error is encountered. All of the successful batch inserts up to that point are committed. The batch that caused the failure is rolled back completely.
  • For Pega Cloud applications, BIX is an add-on service that Pega configures if you choose it as part of your subscription. For on-premises applications, BIX is available when you purchase and install the BIX application.