Formula, Aggregation and Validation (FAV) Plugin for Microsoft Dynamics CRM 2013

InfoStrat has developed the FAV Plugin for use with Microsoft Dynamics CRM to support data validation, aggregate operations, and formula support without programming.  Many business applications for Dynamics CRM require complex business operations that are not supported in Dynamics CRM out of the box but can be implemented through plug-in configuration.

Typically, in a complex Dynamics CRM deployment, business rules, complex calculations and additional security measures are scattered across multiple layers.  Often all of the above are implemented in JavaScript code on various Dynamics CRM forms, in Plugins, and in other extensions such as external portals and data integration components. This proliferation of implementation decisions makes a solution extremely hard to maintain and modify, breaking the development agility inherent to Dynamics CRM. The FAV Plugin allows an implementer to concentrate these functions in a single location and implement all requirements declaratively.

For the purposes of this page, we assume that the reader has basic familiarity with using Plugins in Dynamics CRM.

Background of the Formula, Aggregation and Validation (FAV) Plugin

Microsoft Dynamics CRM includes a flexible SDK framework that allows developers to modify the standard behavior of the CRM platform.  One of the approaches to customization in Dynamics CRM is custom compiled code—a Plugin—that runs against events triggered by actions in Dynamics CRM. These Plugins can be run on the Dynamics CRM server either synchronously or asynchronously.

The Dynamics CRM framework is designed for extension: the metadata for core entities is exposed in the API for creation of custom entities. Due to this high degree of extensibility, Dynamics CRM development can address the business functions for a wide variety of organizations.

InfoStrat has developed the FAV Plugin for use with any Dynamics CRM instance, whether based in the 2011 or 2013 version, hosted on premise or online. The context for the FAV Plugin operation is driven entirely by configuration objects located in the FAV Plugin registration properties, enabling developers to use this FAV Plugin against many CRM instances with increasing economies of scale for each implementation. As a result, the FAV Plugin can be used to implement declaratively complex business rules and additional security measures.

Use Cases

The FAV Plugin addresses following common use cases while allowing them to be implemented completely generically, using JSON-based configuration rules, and deploy across any flavor of CRM 2013 or CRM 2011.

1.      Data Validation

Have you ever come across a need to change access rules dynamically, based on a set of values in a record? For example, an Application record should be writeable while in Draft status, and read-only in Submitted or Cancelled status. Furthermore, if an Application is read-only, all its child records should be read-only as well. In another example, if you have a portal or an integration component that allows the submission of Invoice records, you want to make sure that total of Invoices doesn’t exceed the total value recorded on Purchase Order record. If total is exceeded, the operation should be blocked.

While Dynamics CRM has a robust security model, it is static, and does not react to changing data. The FAV Plugin addresses many complex data validation needs, such as:

-       Validating a Dynamics CRM message (such as create, update, delete, associate etc.) by checking record’s values against a static value recorded in rule’s configuration or against another field value

-       Validating a Dynamics CRM message by comparing record’s value(s) against a value in any other entity in CRM instance

-       Executing an action when validation fails. The FAV Plugin can take following actions:

o   Stop the operation. If validation fails, plugin can terminate the operation and display an error message to the user. The FAV Plugin supports built-in and custom error string formatting, and allows for multiple levels of logging the operation results

o   Send an email message with the description of the validation failure

o   Create a task with the description of the validation failure

o   Set a field value, for example, if a dollar amount exceeds certain value, set a flag variable

o   Combine any of the actions above

 

2.      Calculating dynamic aggregate values and rollups

Imagine that when a record is updated you’d like to calculate subtotal of a certain numeric or currency field from all records logically related together and use the calculated value to update another record (such as a parent record). The FAV Plugin allows you to do it through configuration, while supporting updates of any parent values, and additional filtering logic while determining the subset of records that should be involved in the aggregate operation.

 

3.      Implementing complex formulas

 Dynamics CRM 2013 allows you to implement some simple formulas using Business Rules. However, there is no built-in way to implement complex formulas that use logical expressions and math/string functions. The FAV Plugin allows you to implement declaratively mathematical expressions and formulas of arbitrary complexity thus significantly extending calculation capabilities of your solution. FAV Plugin is using NCALC to support evaluation of mathematical expressions.

 

Where to get a copy of the FAV Plugin and additional FAV Plugin documentation

You can download the plugin from Releases page and additional technical information from Documentation page.

Deploying the FAV Plugin using the Plugin Registration Tool

Walkthrough: Register a plugin-in using the Plugin registration tool

Link: http://msdn.microsoft.com/en-us/library/gg309580.aspx

In order to register your custom code with your CRM environment, the code must be linked directly to actions in the CRM platform. The Plugin Registration Tool is a platform for connecting to your CRM system’s Discovery web service, and it links the individual steps of your assembly to particular CRM operations.

Connect to the Microsoft Dynamics CRM Server

Open the Plugin Registration Tool. In the Login window, enter your CRM server properties & login credentials to initialize the Discovery service for your CRM organization. Toggling “Always display list of available orgs” before submitting your login request will transport you either to your default org or to the list of your orgs. 

Register a Plugin assembly

6 Great Reasons to Register your Plugins in Database Instead of Disk/GAC, Gonzalo Ruiz, 6/2/2011.

Link: http://gonzaloruizcrm.blogspot.com/2011/06/6-great-reasons-to-register-your.html

 

In the command bar, click Register > Register New Assembly to open the Assembly properties window. Browse to the assembly file’s location & load the assembly to display the plugins in your .dll file. Microsoft officially recommends database storage for your assembly file in order to distribute it across multiple CRM servers in a data center cluster, since the assembly file is stored in your SQL database. Disk storage supports Plugin debugging in Visual Studio; however, the number and maturity of debugging tools available in modern browsers nearly eliminate the need for a heavy IDE to debug Plugins.

Register Steps

Following the registration of your assembly, you will also need to register steps that will be triggered by CRM events. For example, if the FAV Plugin assembly was programmed to update a parent record field when its child records are saved, you will need to register a Create step. You can execute a step against 2 or fewer entities, and configure its execution stage (for synchronous execution), execution mode (sync/async), and deployment type (server/offline).

Message

The SDK messages are types of events available for insertion into the Dynamics CRM processing pipeline for which a Plugin should be executed. You cannot create your own messages, but you do have a long list of default entity messages and custom entity messages (fewer than for default) available for use. For example, if the FAV Plugin is set to execute when a default entity record is updated, set the Message to Update.

Entity (Primary/Secondary)

Primary can be any custom or default entity that is available to your organization. Secondary Entity is used only with RemoveRelated and SetRelated messages, otherwise it is null.

Execution Stage

In CRM 2013, you have 3 operations to bind to your Plugin step: Pre-validation, Pre-operation, and Post-operation. Pre-validation and Pre-operation occur prior to the database transaction commit event, and Post-operation follows the commit. For example, deletion cascades execute prior to pre-operation, so any child record retrieval would need to occur in the pre-validation stage. An update Plugin that updates its own record will run optimally if it occurs after validation and before the commit, which is the pre-operation stage. Finally, the post-operation stage is best for create Plugin steps, allowing relationships to be built with the newly created records.

Operations Supported by the FAV Plugin

The FAV plugin’s expression parser is based on the NCalc framework. It supports dynamically parsed formulas based on static values, common math functions, and values of numeric CRM fields.

 

  •          Supports the following aggregation operators: Sum, Average, Count, Min, Max
  •          Supports the Copy operation, allowing a child field value to be copied up to a field value in a parent record
  •          Supports NoOp operation, allowing configuration of an event trigger and to execute validation rules and formulas only on the triggering entity (skipping any steps for the rollups or updates of the parent entity)
  •          Supports a data validation operation for numeric fields, including Equals, Min, Max, and Range validation on all numeric CRM fields
  •          Supports the following actions (including action combinations) when field validation fails: set Value of another field, create Task, create and send Email
  •          Responds to validation failure with optional termination of the operation
  •          Enforces the following validation rules:

o   Field-to-static-range: Validates the field value of an entity that triggers the event against a static Range (with values stored in configuration settings)

o   Field-to-field: Validates a field value in the entity that triggers the event against another field in the same entity

o   Field-to-dynamic-range: Validates a field value in the entity that triggers the event against a dynamic Range where each Range value comes from another entity (using custom FetchXML query)

o   Operation-to-dynamic-range: Validates the entire operation (regardless of what type of change triggered the plugin execution) against a dynamic range (with Range value coming from another entity retrieved using a custom FetchXML query)

  •          Maps each event message to multiple Rules—each Rule with none, one, or more of its own formulas, validators and validation actions

 

FAV Plugin Configuration

The configuration itself is recorded as a JSON object wrapped in an XML container.

The JSON configuration object may contains multiple sets of configuration rules for multiple entities.

A rule set for each entity might contain multiple rules, for example two rules for data validation of two different fields, another rule for calculating a rollup field and a final rule for updating a field value based on a formula.

When you write your FAV Plugin using the Dynamics CRM SDK, you can define a constructor with two parameters for your FAV Plugin: secure and unsecure configuration. The parameter type is string, and they should be formatted as valid XML expression.

The rollup FAV Plugin requires that its configuration be stored in Secure Config parameter.

Below please find an example of the simple plugin configuration string containing two rules for one entity.

You can find full description of all configuration objects and additional plugin configuration examples on Documentation page. Below is an example of a simple FAV Plugin configuration which calculates a subtotal of a currency field from all child entities of a given parent record and updates a field on parent record with calculated value. 

<Settings>
<setting name="JsonRules">
<value>
<![CDATA[
{
"RulesForEntities":[
{
  "Key": "gm_paymentrequest",
  "Value": {
  "EntityName": "gm_paymentrequest",
  "Rules":
  [
    {
    "Name": "PaymentReq.TotalAmtRequested to Grant PayRequestRequested Total",
    "SourceSetting": {
    "FieldName": "gm_totalamountrequested",
    "CrmStateCodes": [{ "Value": 0, "Name": "Active" }],
    "Relationship": { "ForeignKeyName": "gm_grantid" },
    "RollupOperation": { "OperationType": "Sum" }
    },
    "TargetSetting": {
        "EntityName": "incident",
        "RollupFieldName": "gm_paymentrequesttotalrequested",
        "PrimaryKeyName": "incidentid"
    }
  ]}}]}]]></value></setting></Settings>

Each activated step registered in the assembly must have a secure configuration string in order to distribute the processing rules correctly for the associated entity.

Image

Each step needs to be attached to an Existing Image. The image type depends on the type of operation being performed. The properties for the FAV Plugin are as follows:

Update: Pre-image and Post-image

Delete: Pre-image only

Create: Post-image only

Functionality

Steps

The rollup FAV Plugin executes the following steps:

1)    When the FAV Plugin step is executed, the operation retrieves the configuration settings from the FAV Plugin registration & initializes the configuration.

2)    For each rule contained in the configuration object, the FAV Plugin evaluates whether this rule should be invoked.

3)    If a given rule is executed, then the FAV Plugin executes every action associated with that rule, including formula calculations, rollups, data validation, etc.

4)    If a particular validation method fails, the FAV Plugin will execute whatever action is defined for it in the configuration settings. For example, if the validation fails, the code can stop the event entirely, or it could submit notification of the validation failure (by email), depending on how the FAV Plugin has been configured.

Exporting plugin to other Dynamics CRM systems

Registration of the plug-in will automatically add the assembly to the Plug-in Assemblies component in the CRM Solution Designer. In order to migrate plugins to a new CRM instance, each assembly step must be added to a solution where the assembly was registered. Export the solution to the production server (assuming there are no incompatibilities between your CRM instances) and import the solution with the plugin components. You will see the Plug-in Assemblies and SDK Message Processing Steps containers with the migrated assemblies and steps.

Additional Resources and References

http://crmbook.powerobjects.com/extending-crm/plug-in-development-and-workflow-extensions/plug-ins/

http://msdn.microsoft.com/en-us/library/hh237515.aspx

http://msdn.microsoft.com/en-us/library/gg309580.aspx

 

About InfoStrat (Information Strategies, Inc.)

Since 1987, InfoStrat has been delivering IT solutions to government and business customers, focusing on portals, customer relationship management, and custom database applications and integration.  We were named Microsoft Federal Partner of the Year in recognition of our work with the U.S. government and are winners of numerous Microsoft Partner Awards.  InfoStrat has completed over 800 technology projects. 

Together, we have over 60 publications to our credit, including the most recent book Building Portals, Intranets, and Corporate Web Sites with Microsoft Servers (Addison Wesley, 2004).  This book was the first to address the entire Microsoft portal platform, and contains valuable information not only for software developers but also for chief information officers and other technology managers. InfoStrat helped develop one of the largest portals used by the U.S. federal government, www.employeeexpress.gov, hosted by the Office of Personnel Management.  The portal has over one million users from dozens of civilian federal agencies.

Information Strategies line of business solutions built on Microsoft Dynamics CRM and SharePoint include:

  •          Case Management
  •          Grant Management
  •          Sales Force Automation
  •          SharePoint Classification Tool
  •          Housing Management
  •          E-Permitting
  •          Association Management
  •          Lobbying

 

Last edited Oct 2, 2014 at 8:46 PM by nathanielm, version 9