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:

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.