Logging and Handling Microsoft Dynamics CRM 2013 Exceptions – Part 2

In the previous post, I described the business problem of logging and handling implementation level exceptions. In this post, I would like to suggest a solution.

Before you continue reading, note that logging implementation level exceptions is up to your code developer. Although the solution supplies easy methods to log exceptions (to be demonstrated in part 3), nothing will be logged If your custom code does not use the solution components.

Let’s start by defining some business requirements for the suggested solution:

  • Support Microsoft Dynamics CRM 2013 of any deployment type
  • Expose minimum exception details to the user, maximum to the System Administrator
  • Supply the client (user or software component) with a unique correlation code to id each exception instance
  • Require minimum effort from software developers to log exceptions
  • Allow logging and handling client side & server side exceptions in a similar manner
  • Supply System Administrator with an efficient way to search and view exceptions
  • Allow flexible handling when exception is logged: send email notification, move to queue, assign to user/team, send acknowledgment to user etc.

Next, here are the suggested solution major components along with some architecture consideration:

  1. Exception Entity
    This custom entity describes an exception instance details and will be created whenever an exception is logged. Using a custom Exception entity will allow using Microsoft Dynamics CRM UI to easily search and view exception records. A custom entity will also allow great flexibility for handling exceptions by using all Microsoft Dynamics CRM magic: Processes, Queues, Advanced Search, Dashboards, Charts, export to Excel etc.

    The Exception entity will have the following attributes:

    • Name – describes the exception’s raw error message  
    • Created By – reference to the user who initiated the process from which the exception was raised
    • Created On – Date & time on which the exception was logged
    • Friendly Message – the error message that was displayed to the user
    • Unique Token – a unique id assigned to the exception instance and returned to the client along with the friendly message. This token will be used by the System Administrator to correlate the logged exception instance to the error message displayed to the user
    • Priority – describes the exception handling priority
    • Stack Trace – describes the exception’s stack trace which supplies contextual information regarding the calling source function, file etc.
  2. LogException Action
    A custom Action will be used to create an Exception record according to the specified details, generate and assign a unique token and return a friendly message to the client.

    Why Action?

    • Compared to writing custom code, Actions simplify the task of creating and updating an Exception record as it harness the powerful Process tools
    • Action is the only MSCRM mechanism that can receive input parameters and return output parameters in a straight forward manner. Sort of a web service
    • As Action can be accessed from client side (JavaScript code) and server side (Plugins, Custom Workflow Activities, external applications), it provide a single point of implementation
    • Actions allow defining business logic in a declarative manner, so Actions can be easily created and maintained by non developers, as long as the Action signature (parameters and name) is not changed

  3. Unique Token Generator Custom Workflow Activity
    This component will be used by the LogException Action to generate the unique token value. The unique token will be saved to the Exception record and also displayed to the user as part of the managed error message. This will allow the System Administrator to quickly locate the exact exception instance the user has reported.
    As the Process basic tools do not allow generating a unique token, a custom component is required. I prefer a Custom Workflow Activity component as it can be embedded in Actions natural (and transactional) flow, rather than Plugin which is external to the Action. It can also be reused in Workflow Rules and Dialogs.
  4. Sdk.Soap.js
    The Sdk.Soap.js package was recently released by Microsoft as part of the 6.1 SDK. It supplies a comprehensive and intuitive framework for MSCRM JavaScript developers and I recommend it completely.
    One of the package’s tools is the Action Message Generator which automatically generates a JavaScript API for Actions. This API simplifies the execution of Actions from JavaScript and the solution will use it to execute the aforementioned LogException Action from JavaScript Code.
  5. ExceptionManagement.js
    This JavaScript Web Resource is used to wrap the functions required to log exception from JavaScript code. 
    In order to use the exception logging functionality, a developer is required to reference this Web Resource in forms event handlers or other Web Resources. This file includes the Sdk.Soap.js library in order to prevent the need for additional reference.
  6. ExceptionManagement.cs
    This C# class is used to wrap the methods required to log exception from c# code written in Plugins, Custom Workflow Activities, external .net applications etc.
    In order to use the exception logging functionality, the developer is required to add this class to his project or compile it into a DLL and reference it.
  7. Exception Management Dashboard
    This dashboard is aimed to help the System Administrator manage exceptions with the following components:
    • Exceptions by priority and creation day chart
    • Exceptions by priority and user chart
    • Exceptions by priority chart
    • Critical & High priority exceptions view


Finally,  a nice diagram of the solution’s major components:

Solution Components Diagram

Feel free to comment on the architecture and the planned Implementation, I welcome your feedback.

In the next post I will describe the actual Solution and will demonstrate common usage scenarios.


Logging and Handling Microsoft Dynamics CRM 2013 Exceptions – Part 1

In this 3-parts post I would like to suggest a general approach and solution for logging and handling exceptions in Microsoft Dynamics CRM 2013 implementations.

By exceptions, I don’t mean Microsoft Dynamics CRM product core exceptions which occur from time to time. These are logged by various designated repositories (such as Event Viewer and CRM Trace) and beyond our reach anyway, certainly in Online deployments. I do mean unexpected events that arise from custom code written in both server and client side in most Microsoft Dynamics CRM 2013 implementations. These events are usually related to poorly written code, unexpected customization changes or external resources that are beyond your control.

Here are some examples for such exceptions:

  • Custom JavaScript code accessing an attribute of a an object with value of null
  • Custom JavaScript code accessing a field which was removed from the entity form
  • Custom Workflow Activity trying to access an external web service which does not respond or returns an error
  • Plugin code, triggered by an Update event, accessing an attribute which was not updated

Why is it important to log and handle such exceptions? Here are some of the reasons:

  • Bad user experience: When a custom code exception is not handled, it often bubbles to the user interface. This means a vague message is displayed to the end user, a message that he probably can’t handle or tell if and how it affect the business process he is attempting. 
  • Potential business damage: When a user encounters an exception he usually does one of two: ignore it and try again or report the system administrator.
    The first option is bad. It means your application is not healthy and you, as system administrator, are not aware. Beside your users getting frustrated, this may cause data integrity problems, junk data, missed business opportunities or other business related problems.
    It can cost you money!
  • Interrupting your users work: If a user does report an exception to the system administrator, he usually supplies minimum details, less than required to solve the problem without interrupting him to try and reproduce the exception. While some exception details are available to the user (approximate time, attempted business process, error message etc.), other critical details (Internal exception, Stack trace, source component etc.) are hidden from him. 
  • Security breach: Some unmanaged exceptions messages can expose internal mechanisms and supply hackers with details that can help them damage your organization.

Unfortunately, exceptions are part of any business application and cannot be completely avoided. The purpose of the suggested approach is to improve exception handling experience.

So, here is the business problem. In the next post I will describe the suggested solution approach, while the third post will discuss the actual implementation details.

Stay tuned.