Partager via

Create your own actions

  • Article

 

Applies To: Dynamics CRM 2013

You can extend the functionality of Microsoft Dynamics CRM by creating custom messages known as actions. These actions will have associated request/response classes. Presently, actions are available to business applications and extensions through organization web service calls only. Actions are typically used to add new domain specific functionality to the organization web service or to combine multiple organization web service message requests into a single request. For example, in a support call center, you may want to combine the Create, Assign, and Setstate messages into a single new “Escalate” message.

The business logic of an action is implemented using a workflow. When you create an action, the associated real-time workflow is automatically registered to execute in stage 30 (core operation) of the execution pipeline. For more information about real-time workflows, see Workflow categories.

While actions are supported in both Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online, creating an action in code (using XAML) is only supported by Microsoft Dynamics CRM 2013 on-premises and IFD. Online customers must create actions interactively in the web application.

An action is defined by using a Workflow entity record, similar to a real-time workflow. Some key points of what an action is and how it works are in the following list:

  • Can be associated with a single entity or be global (not associated with any particular entity).

  • Is executed in the core operation stage 30 of the event execution pipeline.

  • Supports the invocation of plug-ins registered in the pre-operation and post-operation stages of the event execution pipeline.

  • Can have plug-ins registered in the pre-operation or post-operation stages only when the action status is Activated.

  • Is available through the organization.svc and organization.svc/web endpoints, but not the organizationdata.svc (OData) endpoint.

  • Can be executed using a JavaScript web resource. More information:Execute an action using a JavaScript web resource

  • Always runs under the security context of the calling user.

  • Record can’t be deleted while there are plug-in steps registered on the action.

  • Can be invoked only by a web service method call, not directly from a workflow. However, the workaround is to write a custom workflow activity that invokes the action and add that to a workflow.

  • Can optionally, through a configuration setting, participate in the current database transaction.

  • Doesn’t support a scope where the execution is restricted to a user, business unit, or organization. Actions always execute in organization scope.

  • Supports input and output parameters.

  • Supports auditing of data changes.

  • Isn’t supported with offline clients.

In this topic

Required permissions

Create an action using code

Package an action for distribution

Generate early-bound types for an action

Execute an action using the web service

Watch out for long running actions

Required permissions

A security privilege named Activate Real-time Processes (prvActivateSynchronousWorkflow) is required to activate an action’s real-time workflow so that it can be executed. This is in addition to any privileges needed to create a workflow. For more information on these privileges see Customization Tab.

Create an action using code

Typically, an action would be implemented by a customizer using the interactive workflow designer of the web application. However, developers can implement actions using SDK calls and deploy to an on-premises or IFD server if desired.

The workflow entity attributes that are used for an action are described in the following table. Sample code for a real-time workflow can be found in the topic Create a real-time workflow in code.

Workflow attribute

Description

Category

Set to WorkflowCategory.CustomOperation.

SyncWorkflowLogOnError

When true, errors are logged to ProcessSession records. Unlike asynchronous workflows, real-time workflow execution isn’t logged to System Job records.

Mode

Not used.

IsTransacted

Set to true if the action should participate in the database transaction; otherwise, false. Default is true.

UniqueName

A unique name for the action. The name is composed of a publisher prefix + "_" + the unique name.

Xaml

Set to the XAML code that defines your action’s real-time workflow. There is no way to refer to another existing real-time workflow.

Add input and output parameters

Actions support input and output parameters that can be added to the workflow using a DynamicActivityProperty type. When you add these parameters to an action’s workflow, they become properties in the message request and response classes associated with that action. For example, the following example shows C# and XAML code for two input and one output parameters.

DynamicActivityProperty inputProperty1 = new DynamicActivityProperty 
    { Name = "Subject", Type = typeof(InArgument<string>) };
DynamicActivityProperty inputProperty2 = new DynamicActivityProperty 
    { Name = "EntityCollection", Type = typeof(InArgument<EntityCollection>) };
DynamicActivityProperty outputProperty1 = new DynamicActivityProperty 
    { Name = "Output", Type = typeof(OutArgument<string>) };

inputProperty1.Attributes.Add(new ArgumentRequiredAttribute(true));
inputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The subject"));
inputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));

inputProperty2.Attributes.Add(new ArgumentRequiredAttribute(false));
inputProperty2.Attributes.Add(new ArgumentDescriptionAttribute("The entity collection"));
inputProperty2.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));

outputProperty1.Attributes.Add(new ArgumentRequiredAttribute(false));
outputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The output"));
outputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Output));

<x:Property Name="Subject" Type="InArgument(x:String)">
  <x:Property.Attributes>
    <mxsw:ArgumentRequiredAttribute Value="True" />
    <mxsw:ArgumentTargetAttribute Value="False" />
    <mxsw:ArgumentDescriptionAttribute Value="The subject " />
    <mxsw:ArgumentDirectionAttribute Value="Input" />
    <mxsw:ArgumentEntityAttribute Value="" />
  </x:Property.Attributes>
</x:Property>

<x:Property Name="EntityCollection" Type="InArgument(mxs:EntityCollection)">
  <x:Property.Attributes>
    <mxsw:ArgumentRequiredAttribute Value="False" />
    <mxsw:ArgumentTargetAttribute Value="False" />
    <mxsw:ArgumentDescriptionAttribute Value="The entity collection" />
    <mxsw:ArgumentDirectionAttribute Value="Input" />
    <mxsw:ArgumentEntityAttribute Value="" />
 </x:Property.Attributes>
</x:Property>

<x:Property Name="Output" Type="OutArgument(x:String)">
  <x:Property.Attributes>
    <mxsw:ArgumentRequiredAttribute Value="False" />
    <mxsw:ArgumentTargetAttribute Value="False" />
    <mxsw:ArgumentDescriptionAttribute Value="The output" />
    <mxsw:ArgumentDirectionAttribute Value="Output" />
    <mxsw:ArgumentEntityAttribute Value="" />
  </x:Property.Attributes>
</x:Property>

The names used for the properties should be consistent with parameter names since code generation will define these names as request or response properties.

Supported parameter types for the input and output arguments are shown in the following table.

.NET Type

Parameter Type

System.Int32

Integer

System.String

String

Microsoft.Xrm.Sdk.EntityReference

EntityReference

Microsoft.Xrm.Sdk.Entity

Entity

Microsoft.Xrm.Sdk.EntityCollection

EntityCollection

System.DateTime

DateTime

System.Double

Float

System.Decimal

Decimal

Microsoft.Xrm.Sdk.Money

Money

System.Boolean

Boolean

Microsoft.Xrm.Sdk.OptionSetValue

Picklist

Supported argument attributes are listed in the following table.

Argument Attribute

Description

ArgumentRequiredAttribute

Indicates if the argument is required.

ArgumentDirectionAttribute

Indicates if the argument’s direction is an input or output.

ArgumentDescriptionAttribute

Specifies a description for the argument.

ArgumentEntityAttribute

Used if you want to pass in an entity.

ArgumentTargetAttribute

This attribute is automatically generated or added. It points to the primary entity for which the workflow is run. This attribute is optional for global actions.

Package an action for distribution

To distribute your action so that it can be imported into a Microsoft Dynamics CRM organization, add your action to a CRM solution. This is easily done using the web application by navigating to Settings> Customizations > Solutions. You can also write code to create the solution. For more information about solutions, see Package and distribute extensions using solutions.

Generate early-bound types for an action

Using the CrmSvcUtil tool supplied in the SDK package, you can generate request and response classes for your action to include in your application code. However, before you generate these classes, be sure to activate the action.

Download the Microsoft Dynamics CRM SDK package.

The following sample shows the format for running the tool from the command line for an on-premises installation of CRM. You supply the parameter values for your installation.

CrmSvcUtil.exe /url:http://<serverName>/<organizationName>/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /domain:<domainName> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions

The following sample shows the format for running the tool from the command line with Microsoft Dynamics CRM Online. You supply the parameter values appropriate for your account and server.

CrmSvcUtil.exe /url:https://<organizationUrlName>.api.crm.dynamics.com/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions

Notice the use of the /generateActions parameter. More information: Create early bound entity classes with the code generation tool (CrmSvcUtil.exe).

You can use early-bound or late-bound types with the generated request and response classes for your action.

Execute an action using the web service

To execute an action using the organization web service using managed code, follow these steps.

  1. Include the early-bound types file that you generated using the CrmSvcUtil tool in your application’s project.

  2. In your application code, instantiate your action’s request and populate any required properties.

  3. Invoke Execute, passing your request as an argument.

Before you run your application code, make sure the action is activated. Otherwise, you’ll receive a run-time error.

Execute an action using a JavaScript web resource

The Sdk.Soap.js sample library demonstrates how messages can be used with JavaScript web resources and the Modern App SOAP endpoint (organization.svc/web). Use the companion Sdk.Soap.js Action Message Generator sample to generate JavaScript libraries that can be used with Sdk.Soap.js in the same way you can use the libraries for system messages provided in that sample. The files generated using the Sdk.Soap.js Action Message Generator are separate JavaScript libraries for each action. Each library contains a request and response class that correspond to the classes generated by the CrmSvcUtil.

Watch out for long running actions

If one of the steps in the action’s real-time workflow is a custom workflow activity, that custom workflow activity is executed inside the isolated sandbox run-time environment and will be subject to the two minute timeout limit, similar to how sandboxed plug-ins are managed. However, there are no restrictions on the amount of overall time the action itself can take. In addition, if an action participates in a transaction, where rollback is enabled, SQL Server timeouts will apply.

Tip

A best practice recommendation is that long running operations should be executed outside of Microsoft Dynamics CRM using .NET asynchronous or background processes.

See Also

Create real-time workflows
Use dialogs for guided processes
Event execution pipeline
Write workflows to automate business processes
Customize Microsoft Dynamics CRM