Sunday, 1 December 2013

CRM 2013 Custom Actions


CRM 2013 adds a new handy feature called Custom Actions. Custom Actions provide the ability for non-developer administrators to write reusable modules of logic that developers can trigger through client-side or server-side code. Custom Actions are built using a similar UI as workflows with the same capabilities. The actions are run synchronously and can take in parameters as well as return values. Custom Actions can be pretty powerful and are a great way to share logic between both JavaScript and plugins. Below is a great example we came up with to show how we can replace a 2011 style configuration entity with 2013 Custom Actions.

In CRM 2011, if you need to reference values in code that would change between deployments, the best practice is to create a new entity (typically called Configuration) and add necessary attributes for configurable values such as a “Server URL” of an integration web service. The sole purpose of this entity is to hold one record that would contain the correct values that your custom code can reference, usually for integration purposes. The downside to this approach is that it adds overhead by needing to create a whole entity that will only ever have one record and you need to manually import that record into your target environment. Below is a step-by-step guide on how we can avoid a configuration entity in CRM 2013 using Custom Actions.

In CRM 2013, go to Settings and then Processes. Create a new Process and set the Category to “Action” and the Entity to “None (global)”.

Once the process is created, click the plus icon to add a new argument and set the name to the configuration value such as “ServerUrl”. Set the Type appropriately based on your value and set the Direction to Output. Do this for each configuration value needed.

Scroll down to the designer and click “Add Step” and then “Assign Value”.

Click Properties and in the new dialog window, type in the value for your configuration attribute.

Now save and activate your new custom action.

The custom action is now live so we can use the CrmSvcUtil to generate an SDK message for the action so that we can easily use it with server-side code. You can use the CrmSvcUtil the same way in 2013 as you did in 2011 but you will need to add the “/a” flag to generate an SDK message for your custom actions.

Note: You will need the latest CrmSvcUtil which is provided here in the 2013 SDK.

CrmSvcUtil /url:http://server/org/XRMServices/2011/Organization.svc /out:Demo.cs
/serviceContextName:DemoContext /namespace:Demo.Model /a

Now we can reference the new_GetConfigurationValuesRequest and execute it to get the ServerUrl value from CRM. Even though we specified the custom action as global, we are still required to pass in an EntityReference otherwise CRM will throw an error. Our workaround for this is to pass in the ID of the current user.

var request =
new new_GetConfigurationValuesRequest()
Target = new EntityReference("systemuser", GetCurrentUserId()),

var response = (new_GetConfigurationValuesResponse)_service.Execute(request);
var url = response.ServerUrl;

So there you have it! Executing this request returns “http://server” that I had set in the custom action and now we can use it to replace a configuration entity. As you can see, custom actions can be pretty powerful. One improvement we’re hoping for in the future is to allow custom actions to execute custom code, similar to a workflow assembly. This would allow developers to easily kick off server-side code from JavaScript.