Workflow Design Basics
- 8 minutes to read
The Workflow module integrates Windows Workflow Foundation (WF) 4.0 support into XAF. WF is a workflow management framework you can use to create more manageable, workflow-enabled applications. The module simplifies design and workflow execution, requiring users to be familiar only with the general concepts associated with workflow design. This topic describes the basics of using the module. For step-by-step instructions showing how to design a sample workflow, refer to the How to: Design Workflow help topic.
Note
ASP.NET Core Blazor applications do not support the Workflow Module.
WWF and WCF will not be ported to .NET Core/.NET 6+ by Microsoft. We recommend that you implement Controllers or custom solutions such as Hangfire, Quartz.NET, and others for former Workflow Module scenarios. To save your time, consider this free module within the eXpand Framework.
Workflow Module
If you use the Entity Framework Core, register the following entity types within your DbContext. Otherwise, if you use XPO, skip this step.
using DevExpress.Workflow.EF;
using DevExpress.ExpressApp.Workflow.EF;
using DevExpress.ExpressApp.Workflow.Versioning;
// ...
public DbSet<EFWorkflowDefinition> EFWorkflowDefinition { get; set; }
public DbSet<EFStartWorkflowRequest> EFStartWorkflowRequest { get; set; }
public DbSet<EFRunningWorkflowInstanceInfo> EFRunningWorkflowInstanceInfo { get; set; }
public DbSet<EFWorkflowInstanceControlCommandRequest> EFWorkflowInstanceControlCommandRequest { get; set; }
public DbSet<EFInstanceKey> EFInstanceKey { get; set; }
public DbSet<EFTrackingRecord> EFTrackingRecord { get; set; }
public DbSet<EFWorkflowInstance> EFWorkflowInstance { get; set; }
public DbSet<EFUserActivityVersion> EFUserActivityVersion { get; set; }
To operate the Workflow Module in your Windows Forms application, add it using the Application Designer. Invoke the Application Designer and drag the WorkflowWindowsFormsModule from the Toolbox to the Modules panel. Do not forget to rebuild your solution after making changes in the Designer.
Note
You can add modules to your application when you use the Solution Wizard to create a new XAF solution. Select modules in the Choose Additional Modules step.
- To add an extra module in code, add it to the XafApplication.Modules or ModuleBase.RequiredModuleTypes list (adding a reference to the module assembly is insufficient).
The Conditional Appearance module, which is required by the Workflow Module, is added automatically. Additionally, the WorkflowModule‘s properties that specify built-in business object types used by the module to persist workflows (WorkflowDefinitionType, WorkflowInstanceType, WorkflowInstanceKeyType, WorkflowControlCommandRequestType, UserActivityVersionType, StartWorkflowRequestType, RunningWorkflowInstanceInfoType) are initialized depending on the currently used ORM (either EF entities or XPO persistent objects are used).
After you have added the module to your application, run the application once. This will create service workflow tables in the database to be used later by the workflow server service that launches workflows. This is an essential step, as the service cannot function properly unless these tables exist.
When running the application, notice that a Workflow Definition navigation item becomes available.
This navigation item invokes a List View containing all workflow definitions designed at run time. To create your first workflow definition, use the New Action.
When creating a workflow definition, first specify its name and the type of the target objects. A workflow definition must target business objects of a particular type specified by the Target Object Type property. Because of this, each definition contains a pre-declared targetObjectId input argument you can use when designing definition activities. This argument specifies the identifier of the object for which a workflow instance has been executed.
You can choose when a workflow instance is executed by using the Automatically start when layout group. Check the Object Is Created option to specify that an instance should be executed after an object has been created in the database. Check the Object Fits Criteria option to specify a condition for workflow execution. If the AllowMultipleRuns property is not checked, the workflow runs once for each target object that fits the criteria. Check this option if you want to repeat the workflow multiple times while the object fits the criteria.
Important
The Workflow Server Service should be running in the background to execute workflows. There are by-design delays between an event that triggers the workflow and the workflow execution. By default, the workflow server service rechecks the database every 15 seconds. So, after an object is created or after it changes its state to satisfy criteria, it can take up to 15 seconds to execute a corresponding workflow instance.
After you have filled the Properties tab, click the Designer tab to invoke the re-hosted workflow designer and create actual activities.
Newly created workflow definitions are inactive and will not be executed by the workflow server service. To activate and deactivate definitions after designing them, use the Activate and Deactivate Actions.
Note
You can see a sample workflow definition in action in the WorkflowDemo.NETFramework.XPO demo shipped with XAF. The demo application is located in the %PUBLIC%\Documents\DevExpress Demos 23.2\Components\XAF folder by default.
Workflow Designer
The Workflow designer is a graphical means of creating and modifying workflows. It is based on the standard Microsoft WPF WorkflowDesigner component rehosted in a custom WinForms control (see Rehosting the Workflow Designer). Look for more details on its features and customization in MSDN and other public community resources. To access the WorkflowDesigner object in code, handle the static WorkflowDesignerControlBase.WorkflowDesignerCreated event.
The Workflow designer is composed of three panes.
The Toolbox pane contains activities you can combine to create a workflow.
Drag and drop an activity from the toolbox onto the design surface to create a workflow. Use the search textbox to quickly locate a particular activity. Click the search textbox and start typing. Activities in the toolbox will be filtered accordingly.
The Design Surface is the central part of the workflow designer. Here, you can configure activities and reorder them using drag and drop operations.
The design surface contains three important pages that can be invoked by clicking the corresponding page name at the status bar.
Variables - Use this window to declare variables needed by the current workflow. These are storage locations used to persist data during the workflow lifetime.
Arguments - Use this window to specify the argument a workflow instance will take and return. Each XAF workflow definition contains a pre-declared targetObjectId input argument that specifies the identifier of the object for which a workflow instance has been executed.
Imports - Use this window to see the namespaces containing types referenced by the current workflow definition.
To learn more about variables and arguments, refer to the Variables and Arguments MSDN article.
The Property Pane allows you to specify properties of the activity currently selected on the design surface.
Different activities have different property sets, and it is not always necessary to provide values for all properties.
Debug Workflows
To simplify workflow creation, the Workflow module ships with a built-in debugging functionality. You can debug workflows either while designing them or after deployment. To debug workflows while designing them, the Workflow module provides a set of specific Actions. These Actions are enabled after the current workflow definition has been loaded. To load a workflow definition, switch from the Properties page of a workflow definition to the workflow designer. This will enable debugging Actions.
| Action | Description |
|---|---|
 Debug |
Starts a debugging session. |
 Toggle Breakpoint |
Creates a breakpoint at the activity currently selected on the design surface. |
 Stop Debug |
Stops the current debugging session. |
To start a debugging session, execute the Debug Action.
A special window will be displayed, logging all the activities being executed along with occurred exceptions, if any.
No test objects are created when debugging. That is why the pre-declared targetObjectId input argument is not initialized when it is being debugged, and the GetObjectByKey<T> activity returns null for this argument. As a result, a NullReferenceException will occur if consequent activity accesses the GetObjectByKey<T> result. As a workaround, you can temporary modify your workflow definition to be able to debug it against a specific target object. The simplest way to do this is to assign an Oid of some existing business object as a default value of the targetObjectId argument using the following syntax.
To debug workflows after deploying them, use the Show Workflow Instances Action.
The Action invokes a List View containing a track record of workflow instances executed by the Workflow Server Service.
Double-click a workflow instance record to see the details on which activities have been executed and when they were executed.
Click a particular tracking record to see details on how an associated activity has been executed.
Manage Changes with WorkflowDefinition if there are Running Instances
Do not modify a WorkflowDefinition object that is in use. The designed workflow is stored in each running instance as a separate copy, thus any changes will break it (this is a WWF restriction). To avoid this situation, create a new WorkflowDefinition object and re-design a workflow as required. You can manually copy the Xaml property value from one WorkflowDefinition object to another, or better use the CloneObject Action provided by the Clone Object Module.