Create real-time workflows

 

Applies To: Dynamics CRM 2013

Similar to asynchronous workflows, real-time workflows can be used to model and automate real world business processes. They can optionally require user input, can start automatically based on specified event conditions, or can be started manually by a user. Real-time workflows are for business users, for example business analysts, to implement similar functionality to synchronous plug-ins without requiring .NET Framework programming experience. You can create asynchronous or real-time workflows in the Microsoft Dynamics CRM web application or in code.

Some key points about a real-time workflow include the following items:

• Defined by using a Workflow entity record, similar to an asynchronous workflow.

• Executes in a stage of the event execution pipeline, similar to synchronous plug-ins. The real-time workflow can execute before (pre-operation), after (post-operation), or during the core operation. A real-time workflow that is executed during the core operation is the implementation of a custom action. Real-time workflows can be ranked within a stage just like you can do with plug-ins. More information: Pipeline stages

• Whether configured to run on-demand or in response to an event, a real-time workflow runs immediately rather than being queued to run at a later time.

• Can run in the security context of the logged on user or owner of the workflow. However, workflows set to run on-demand always run under the security context of the logged on user.

• Can’t contain any delay or wait activities.

• Only logs errors, and only when logging is enabled.

• Executes in the current transaction. All activities in the workflow and any child workflows, except asynchronous workflows, are part of a single transaction. Asynchronous child workflows are queued and execute in a separate transaction.

• Can be converted to asynchronous workflow and back to real-time.

In This Topic

Required security privileges

Create a real-time workflow in code

Convert an asynchronous workflow to real-time and back

Error handling and rollback

Package a real-time workflow for distribution

Required security privileges

A security privilege named Activate Real-time Processes (prvActivateSynchronousWorkflow) is required to activate real-time workflows so that they can be executed. The Execute Workflow Job (prvWorkflowExecution) privilege is required to start the workflow. Because a real-time workflow impacts the core system operation, it is recommended that only a small experienced group of users are granted the activate privilege.

For more information on these privileges see Customization Tab.

Create a real-time workflow in code

While Microsoft Dynamics CRM Online does support real-time workflows, they must be created interactively in the web application. XAML based workflows, discussed in this section, are only supported by an on-premises or IFD server. For more information about XAML workflows see Custom XAML workflows and Create and deploy XAML workflows using the Developer Toolkit.

You can create a real-time workflow in code by creating a Workflow entity record. Review the Workflow entity’s attribute metadata by using the Metadata Browser tool or the EntityMetadata.xlsx spreadsheet in the SDK package. To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also view the metadata for an uncustomized organization in the Excel file called EntityMetadata.xlsx included in the top-level folder of the SDK download. Download the Microsoft Dynamics CRM SDK package.

The following example compares code that creates an asynchronous workflow to code that creates a real-time workflow.

// Create an asynchronous workflow.
// The workflow should execute after a new opportunity is created.
Workflow workflow = new Workflow()
{
    // These properties map to the New Process form settings in the web application.
    Name = "Set closeprobability on opportunity create (async)",
    Type = new OptionSetValue((int)WorkflowType.Definition),
    Category = new OptionSetValue((int)WorkflowCategory.Workflow),
    PrimaryEntity = Opportunity.EntityLogicalName,
    Mode = new OptionSetValue((int)WorkflowMode.Background),

    // Additional settings from the second New Process form.
    Description = @"When an opportunity is created, this workflow" +
        " sets the closeprobability field of the opportunity record to 40%.",
    OnDemand = false,
    Subprocess = false,
    Scope = new OptionSetValue((int)WorkflowScope.User),
    TriggerOnCreate = true,
    AsyncAutoDelete = true,
    Xaml = xamlWF,

    // Other properties not in the web forms.
    LanguageCode = 1033,  // U.S. English                        
};
_workflowId = _serviceProxy.Create(workflow);

// Create a real-time workflow. 
// The workflow should execute after a new opportunity is created
// and run in the context of the logged on user.
Workflow workflow = new Workflow()
{
    // These properties map to the New Process form settings in the web application.
    Name = "Set closeprobability on opportunity create (real-time)",
    Type = new OptionSetValue((int)WorkflowType.Definition),       
    Category = new OptionSetValue((int)WorkflowCategory.Workflow),
    PrimaryEntity = Opportunity.EntityLogicalName,
    Mode = new OptionSetValue((int)WorkflowMode.Realtime),

    // Additional settings from the second New Process form.
    Description = @"When an opportunity is created, this workflow" +
        " sets the closeprobability field of the opportunity record to 40%.",
    OnDemand = false,
    Subprocess = false,
    Scope = new OptionSetValue((int)WorkflowScope.User),
    RunAs = new OptionSetValue((int)workflow_runas.CallingUser),
    SyncWorkflowLogOnFailure = true,
    TriggerOnCreate = true,
    CreateStage = new OptionSetValue((int)workflow_stage.Postoperation),
    Xaml = xamlWF,

    // Other properties not in the web forms.
    LanguageCode = 1033,  // U.S. English
};
_workflowId = _serviceProxy.Create(workflow);

The real-time workflow has some additional properties set that the asynchronous workflow doesn’t:

Workflow attribute	Description
Category	Set to WorkflowCategory.Workflow.
RunAs	Specifies to execute the workflow under the security context of the workflow owner (workflow_runas.Owner), or logged on user (workflow_runas.CallingUser).
SyncWorkflowLogOnError	When true, errors are logged to ProcessSession records. Unlike asynchronous workflows, real-time workflow execution isn’t logged to System Job records.
CreateStage, DeleteStage, or UpdateStage	Identifies the stage in the event execution pipeline where the workflow is to run: before the core operation (workflow_stage.Preoperation), or after (workflow_stage.Postoperation). You must match the stage to the trigger event for the intended operation. For example, if TriggerOnUpdate is true, you must also set UpdateStage. Real-time workflows can’t be executed on retrieves. Other than retrieves, the rest of the supported web services messages map to one of these three supported events. For example, an assign or setstate ultimately is an update.
Mode	This is the execution mode. Set this to WorkflowMode.Realtime.
Rank	You can order the execution of plug-ins and real-time workflows within a stage by setting a rank. All plug-ins or real-time workflows with a rank of 1 execute before those with a rank of 2, and so on.
Xaml	Set to the XAML code that defines your real-time workflow.

You can see the complete sample code for creating a real-time workflow in the topic Sample: Create a real-time workflow in code.

Convert an asynchronous workflow to real-time and back

You can convert workflows from asynchronous to real-time and back using UpdateRequest without the need to rewrite the workflow, as long as the asynchronous workflow doesn’t contain any wait or delay activities. You can also do the conversion interactively by using the web application. The workflow must be in a draft state (not-activated) before the conversion is performed.

Convert an asynchronous workflow to real-time

1. Create an UpdateRequest for the workflow.

2. Set the workflow’s Mode property to WorkflowMode.Realtime.

3. Set the workflow’s CreateStage, UpdateStage, or DeleteStage as appropriate. For example, if your workflow has TriggerOnDelete set, then also set the DeleteStage property.

4. Call the Execute method passing the update request as a parameter.

Convert a real-time workflow to asynchronous

1. Create an UpdateRequest for the workflow.

2. Set the workflow’s Mode property to WorkflowMode.Background.

3. Call the Execute method passing the update request as a parameter.

Error handling and rollback

Any workflow activity that executes during the database transaction and that passes an exception back to the platform cancels the core operation. This results in a rollback of the core operation if it’s already occurred. In addition, any pre-event or post-event registered plug-ins or real-time workflows that haven’t executed yet. Any asynchronous workflows that are triggered by the same event won’t execute.

If you include a stop workflow (TerminateWorkflow class) activity with the cancelled option in your workflow, you can add a custom status message (Reason property) to that activity containing a single line of text to be displayed to the user in the Business Process Error dialog.

When SyncWorkflowLogOnError is set to true, real-time workflow errors are logged in ProcessSession entity records.

Package a real-time workflow for distribution

To distribute your workflow so that it can be imported into a Microsoft Dynamics CRM organization, add your workflow to a Microsoft Dynamics 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.

See Also

Write workflows to automate business processes
Create your own actions
Event execution pipeline
Write plug-ins to extend business processes