7. Error Handling and Logging - Betaalvereniging-Nederland/emandates-libraries-dotnet GitHub Wiki

Error handling is part of the Directory, Transaction and Status protocols. When a request is rejected for system-related or field-related reasons, an error message is sent in response to the occurrence of this error.

A generic error response message is sent as a reaction to:

  • The Directory request
  • The Transaction request
  • The Status request

For all messages received by the eMandates Creditor Library, a log will be created containing references to the date/timestamp, and the actual message, including any errors the message might contain.

The libraries provide extensive logging support for monitoring the messages between the Creditor and Routing Service. This will be optional and configurable from the application configuration file (see section 4.2 - Library settings, for more information about how you can configure the library to output these messages).

In addition to logging the response and request messages to disk, the libraries allow programmatic access to the messages, to be used in cases in which simply logging the message to disk doesn’t fulfill your requirements (e.g. running in a cluster, saving the messages in a database, sending a notification when an error message is received, etc.). This can be achieved using any of the following approaches:

  • The original xml response messages are accessible directly from the response objects for the directory request, new mandate request, status request, amendment request and cancellation request. This approach enables developers to associate a response with its xml representation, but it is only available for responses, and only for the responses with no parsing errors. For more details on how to access the xml messages for each response, see chapter 5. Integration Workflow.
  • The internal logging code uses a pluggable architecture, allowing developers to plug in their own logging code and handle the messages however they see fit. This is the more powerful approach, allowing merchants to save all messages (both request and response), even if parsing errors occur. The messages will not be associated with their object representation however, so if this is needed then the first approach should be used. For more information on how to plug your own logging code, see the examples below.

Additionally, apart from logging the request and response, the libraries will also log diagnostic information, enabling you to investigate potential configuration issues. Instructions for how to enable the logging of diagnostic information are included below.

The following steps should be followed in order to plug in your own logging code:

  • Implement interface ILogger, specifically the Log and LogXmlMessage methods. The Log method will be called by the library for logging trace/diagnostic messages, such as when a signature is being computed, the result of a message validation check, etc. The LogXmlMessage will be called by the library when logging a request/response message, and will receive the entire xml message as an argument. You can use this method to save the messages wherever you see fit.
  • Implement interface ILoggerFactory to return your own implementation of ILogger. The interface only has one method – Create, which you will have to implement so that it returns your own custom implementation of ILogger. The factory will be used internally by the library for creating logger instances for each communicator.
  • Set the Configuration.LoggerFactory property to overwrite the default logger factory with your own implementation that the library will use for creating loggers.

For logging diagnostics, the library is using the standard Trace class, and in order to enable the saving of these messages to disk you will have to configure the output for standard .NET trace diagnostics. For more information on how to do this, see this MSDN article.

Additionally, the library will itself throw errors whenever it detects invalid input data. In order to handle these errors you should catch the library-specific exception, CommunicatorException.