Use Workflow Custom Actions with code

• 10/26/2020
• 2 minutes to read
• • J

Workflow Custom Actions, also known as simply Custom Actions, are one of two ways to create custom messages for the Microsoft Dataverse. The other is a preview feature called Custom APIs. More information: Create and use Custom APIs.

Both of these capabilities allow for creating new messages that can be called from web services. Workflow Custom Actions will continue to provide a no-code way to declaratively define synchronous business logic. Custom actions have always been synchronous 'real-time' workflows and therefore not suitable to be converted to use Power Automate.

For a comparison of the capabilities of Workflow Custom Actions and Custom APIs, see Compare Workflow Custom Action and Custom API.

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 the main operation stage of the message execution pipeline.

For developers, the creation of a new message means you can use the message in code with either the Web API or the Organization service.

• With the Web API, the new messages created with Workflow Custom Actions are always OData actions. For information about calling actions using the Web API, see Use Web API actions.
  • Custom actions can be used in client-side JavaScripts in Model-driven apps by using the Xrm.WebApi.online.execute method.
• With the Organization service, the messages can be called generically in a late-bound style by using the OrganizationRequest class or by using early-bound request and response classes generated by the code generation tool (CrmSvcUtil.exe).
  • More information:
    • Generate early-bound classes for the Organization service
    • Use messages with the Organization service

For information about creating a Workflow Custom Action using the workflow designer see: Create a custom action

Extend Workflow Custom Actions

There are two ways to extend Workflow Custom Actions using code: with custom workflow activities or by registering plug-ins on stages.

Custom Workflow Activities

Because a Workflow Custom Action is a workflow, you can include re-usable custom workflow activities in the workflow definition as part of the workflow. More information: Workflow extensions

Register plug-ins steps for stages in the execution pipeline

Because a Workflow Custom Action creates a message, you can register plug-ins steps on the PreOperation and PostOperation stages to modify the behavior of the Workflow Custom Action. Developers have used this to define all the logic for the message, frequently not defining any workflow logic at all. The Custom API preview feature now simplifies this code-first pattern and provides other capabilities not possible with Custom Workflow Activities. More information: Create and use Custom APIs

The message for a Workflow Custom Action is only available with the Workflow that defines it is activated. You cannot register plug-in steps for a Workflow Custom Action that isn't active.

If you register any plug-in steps on a Workflow Custom action it will establish a dependency in the solution that will prevent deleting the Workflow Custom Action.

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.

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 plug-ins are managed. However, there are no specific restrictions on the amount of overall time the action itself can take. This is not an advantage. The workflow cannot run indefinitely. It will eventually fail for various reasons. For example, if an action participates in a transaction, where rollback is enabled, SQL Server timeouts will apply. Take care to ensure that your custom actions can complete with a clear success or failure in a reasonable period of time. Anything longer than 2 minutes is probably too long.

The existing Depth platform checks ensure an infinite loop does not occur. For more information on depth limits see MaxDepth.

See also

Create a custom action
Use actions
Classic Dataverse workflows