When it comes to process (plugin/workflow) execution in MS Dynamics CRM 2015, there are various ways of achieving this. Sometimes, developers have requirement to run on-demand workflow when user clicks on the menu button, or if we want to be more general, on any event that can happen on the CRM form. The easiest way to do this is to use Ribbon Workbench and create commands that will be attached on the button visible on the menu. It is fairly easy procedure as depicted on the picture below.
However, there are several imperfections in this approach:
- User has to find ID of the process (<WorkflowID> in the picture above) and set its fixed value as part of the action configuration. This will work if you have workflow that is rarely changed, but if you are migrating across CRM online instances, this command probably won’t work as your process ID might change (unless you are careful and create workflow with the same ID on new instance).
- There is no clear and efficient way of performing any action on CRM form as synchronous step after workflow executes (either successfully or with error/fail). To put it more straightforward, you can’t have custom client code executed as a result of workflow completion. The best you can do here is to register additional JS action (to be run in parallel) with custom code that will wait and periodically check for whatever changes you expect (i.e. changes workflow might make on the server-side).
Luckily, there is better approach that I adopted as a best-practice whenever I have to deal with requirement of executing on-demand workflows from UI components. With a little more effort and code that will be presented in the upcoming sections, you can create own JS action, capable of finding workflow process by it’s name, execute it and also register workflow result callbacks. This means that you can have any custom client (JS) code executed as soon as your workflow succeeds or fails.
This opens door to many degrees of freedom, like post-processing validation (of any changes that workflow created), additional formatting, updating calculated fields based on workflow results etc.
So, let’s get started.
- The very first step is to create JS library, upload it as WebResource to CRM, and by using Ribbon Workbench add it as an action of button command.
- Once you have that UI customization, you need to edit JS WebResource (library) attached to the action. In our example, entry point to client code is function named onCreateBlastRibbonClick() inside file named createBlastWorkflowTrigger.js:
Basically this function just calls another JS function responsible to find Workflow ID for the workflow we want to execute. It does so by passing well-known name of the workflow, in this example “Create Blast”.
- Implement client code for fetching Workflow GUID from Organization web service. To accomplish this, you can write simple JS function that user Organization service and OData protocol to search WorkflowSet for workflow with given name:
As you can see, this function will create AJAX GET request to CRM to get Workflow based on filter criteria. Regular success and fail callbacks are registered here, and when AJAX request is successful, we pass response data to the handler function, responsible for parsing Workflow GUID and executing process in CRM (next step).
- Function which will be responsible to parse Workflow GUID and execute workflow is provided below.
After workflow GUID is parsed from response data record, we use Process JS object and function named callWorkflow() to call workflow execution. Behind the curtain, Process.js is library publicly available, and works as a wrapper which prepares XML payload and request for workflow execution. Internally it also uses Organization web service. You can download it from this URL: https://processjs.codeplex.com/
As provided in the comments above, last two parameters are callbacks which will be called when execution is completed.
- Finally, you need to implement those callbacks. Typically we add/hide some notifications on the CRM form here, but you can implement any custom logic.
Now you are left with more control because callbacks are triggered only when workflow completes, and at the same time you don’t depend on the fixed parameter like Workflow GUID. Described solution depends only on the name of the workflow which is not changed very often by administrators.