Xrm.Utility.invokeProcessAction – A function introduced in Dynamics API for quite sometime. And frankly with the magnitude of actions being used in each project, this should have been the most widely used function by now. But unfortunately this is hardly used and the reason for that being it’s purpose is not being understood.
We may have never thought that with Xrm.WebApi.execute being already there, what is the need for a separate API to call the action? And also why it is called invokeProcessAction and not just invokeAction? If you have just noticed what I have higlighted, may be by now you have already started guessing. And that’s why the old advice of reading in between the lines just works out everywhere and even in a function name.
So let’s get serious. I have gone through multiple articles on this topic and all these articles always show how to execute a global function using this API. Surprisingly there is no article which shows how to call a bound (entity) action. Microsoft documentation on this topic doesn’t help either. And if you are curios enough and tried to execute a bound action using this method, you must have received the error – “Action not supported”.
So if the capability is just limited to execute global action why a separate API. After all Xrm.WebApi.execute just works fine. As we go through the process of unravelling this method, things will become more clear.
I have created a bound action with Account entity. Below is the screenshot of the action and it has few input arguments. Also it creates a task and associates it with an account. Pretty simple right?
I write code to execute this action on an account entity form. And we get the below error – “The action is not supported.” This made us to believe that bound actions are not supported. Let’s burst that myth first, bound action is supported but we are not using it the correct way.
I then put a lot of thought on it’s naming. Why it is called invokeProcessAction? If process something to do with it. So the next step is I went ahead and created a business process flow for the account so that any new account I create have an associated business process flow to it.
Now I run the same code. Error again right? But watch, the error just changed. Now it says “UciError”. Some progress right. At least we now know that bound actions are supported. Things are getting interesting here. Tighten your belt.
Now the next stuff I do is I check the option – “As a Business process flow Action Step” in the Action.
And once I do that, I add the action as Action step in the business process flow for the Account entity which I created in the earlier step. And then I update the process.
And now I run the same code on account record. And I can’t believe my eyes here. It’s in-fact hit the success callback.
And the action executed and created a task
What’s the change? The only change is the now the account record is having a business process flow with the action as an Action Step. And now I guess you started to understand what it is called invokeProcessAction.
So finally a breakthrough!
But wait the joyride is still not over. Let’s explore it a bit more.
Now that we understand it’s related to Business Process flows, can we execute this action from anywhere? All this time I was executing the code from entity forms. But let’s try this time to execute from a webresource.
Error again! So can’t it work outside an entity form. Hell yeah! it can work.
All you need to do is pass the Business Process flow id as one of the parameters. Check for the parameter “BusinessProcessFlowId” in the action call.
Now the question comes, how did it work on the entity form without this parameter? The reason is when we executed the code from the entity form, the business process flow was present and the context could retrieve the business process flow id of the record on the form. Now that we are executing it outside the context of form, we need to pass it explicitly.
Finally to end off, a question may come to your mind. Can I fire it for specific instance of Business Process Flow? Affirmative – you can. All you need to do is pass the BusinessProcessFlowInstanceId.
And below is the code to do the same.
Trust me, it was kind of a discovery I relished and thoroughly enjoyed writing. And I don’t want my readers to miss it too!
Hope this helps!
Debajit Dutta
(Dynamics MVP)
For consultation/ corporate training visit www.xrmforyou.com or reach out to us at info@xrmforyou.com
Our product offerings:
CRM-Sharepoint Attachment uploader and metadata manager (http://www.xrmforyou.com/sharepoint-integrator.html)
Notes Manager (https://debajmecrm.com/add-metadata-to-your-notes-and-attachments-in-dynamics-notes-metadata-manager-from-xrmforyou-com/)
Role based views for Dynamics 365 (http://www.xrmforyou.com/role-based-views.html)
Record Cloner for Dynamics 365 (http://www.xrmforyou.com/record-cloner.html)
Good to know this. Thanks for the detailed write-up. Enjoyed reading it.