Using MS CRM “IPluginExecutionContext” to Tackle Business Needs: A 3 Part Series

STOPPING A SALES ORDER FROM BEING CREATED

Stopping an operation using a plugin is a simple process. All you need to do is throw an exception, but its best to not just throw any exception. CRM provides the “InvalidPluginExectionException” that allows you to pass in a message that will get displayed to the user. Using that, we can alert the user that the action they took is not allowed and guide them in the direction of the correct way to create an order.

            throw new InvalidPluginExecutionException(OperationStatus.Canceled,

                “You can only create a sales order through the quote to sales order process. Please create a quote and then convert it to a sales order”);

This code causes the current process to be cancelled and rolled back, and an error to be shown to the user that looks like the image above. We set the Operation Status to cancelled since that more accurately fits what is taking place here. That piece of code is great and we can put that into a plugin, register on the created sales order and it will do the job. Unfortunately, without proper filtering, it will also block sales orders that are created when a quote is being converted, which leaves us slightly short of meeting the requirements. The CRM plug-in architecture gives us the ability to gather information about how a plugin was triggered. It does this through the “IPluginExecutionContext” and the parent context.

WHAT IS THE “IPLUGINEXECUTIONCONTEXT” PARENT CONTEXT?

The parent context is a useful property because it allows you to write a plugin that is aware of how it was triggered and what events lead up to the plugin executing. For example, if you wrote a plugin on the post quote create that created quote details. Any plugin that was registered on the quote detail entity would have a reference to the context of your post quote create plugins context through the parent context when your plugin initiates the action. To put it in simpler terms, the parent context is a reference to the context of a pipeline event that triggered your plugin to run. It’s possible that it is null, which would indicate that it is a direct action. The parent context is a reference to another “IPluginExecutionContext,” so it is a linked list and it is possible that it is more than one link long.  This can occur if you have a lot of plugins that take action on entities and cause more plugins to run.

There is a “ConvertQuoteToSalesOrder” message which is triggered when you press the “Create Order” button on a submitted quote. The step boxes are plugins / CRM system pipeline steps. You can see the first step of the converting process is to create a sales order using the fields mapped from the quote. That creation triggers the Create (Sales Order) pipeline to be initialized and started. Because that entity and pipeline were created by an action inside of another pipeline, every plugin that executes during it will have access to a parent context that returns the context from Step 1 of the “ConvertQuoteToSalesOrder” pipeline. The ParentContext property holds a reference to a “IPluginExecutonContext” so the whole thing is a linked list all the way to the initiating message. So in a hypothetical situation where you would want every sales order to start out with a single product in it, you could create a post-operation plugin to add that item. If the whole thing was initiated from the quote conversion, you could traverse the parent context all the way from a plugin in the sales order detail pipeline to the “ConvertQuoteToSalesOrder” context of step 1. So now that we know what the parent context is, how do we use it?

Stay tuned for our final part, Part 3: Putting KTL’s Ideas to Work, where Andrew will go over how KTL will use the “IPluginExecutionContext” to ultimately solve the problem and wrap up another successful project. Want to play around with this plugin further? Catch it in Part 3, when Andrew releases a link to a demo version just for you!