Inbound Mapper Error Handling

BeginMapper provides an exception handling mechanism that is intended to trap unhandled exceptions that may occur during the mapping process (for example Parser Exception, Database Exception). Prior to invoking the mapper, it initializes the mapping result on the IBM® App Connect Enterprise Environment (Environment.PMP.Variables. Mapper.Result = 'Success'). If an exception is caught from the mapping, BeginMapper changes the result to 'Abort' and propagates the message to the failure terminal. BeginMapper may also be configured to re-throw the exception resulting in the inbound message being backed out to the input channel.

BeginMapper is not typically expected to handle logical mapping failures.

All inbound mappers should complete with one of the results shown in the following table.
Table 1. Inbound mapper return values
Mapper result Description
Success Mapping has completed with no known errors.
Failure Mapping has completed but some errors were encountered. All mapped objects will be created and depending on the business process the processing may be recoverable. This is the result that should be passed if one or more transactions is deemed to have failed mapping.
Aborted Mapping has failed and is deemed unable to continue. Some but not all mapped objects may have been created but the business process cannot continue with the transmission that was received.

Mappers using EndMapper (v1) should record the mapping result on the IBM App Connect Environment (Environment.PMP.Variables. Mapper.Result ).

Errors or failure information should also be recorded on the IBM App Connect Environment under the location Environment.PMP.Variables. Mapper.Errors[]; an array of error objects that occurred during the mapping. These need not be fatal errors, that is, it may be able to continue mapping after adding an error to this array.

The error object has the following fields:
  • Type
  • Description
  • ReferenceNumber

If the error is related to a specific transaction, the transaction reference number (CID) should be set in the ReferenceNumber field. Otherwise, the error is logged against the physical transmission. If the mapping result is aborted, any errors will be recorded against the Transmission or Fragment.

For batch mappings using EndMapper (v1) the mapper should identify the transactions that failed mapping by setting the following environment values:
  • Environment.PMP.Variables.BATCH_MAPPING_VARS.MAPPING_RESULTS.SUCCESS[idx] = FALSE, where idx is the one-based index of the ISF message in the batch
  • Environment.PMP.Variables.BATCH_MAPPING_VARS.MAPPING_RESULTS.ERROR_CODE[idx] = xxx, where idx is the one-based index of the ISF message in the batch, and xxx is any meaningful error code.

Mappers using EndMapper (v2) should pass the mapping result in the EndMapper XML document in accordance with the schema and message set definition. Error or failure information should also be provided in the content of the EndMapper XML document related to specific objects.