Workflow Best Practices
Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012
Best practice checks for workflow focus on the properties of workflow categories, types, approvals, and tasks. The checks verify that the properties are correctly configured. For information about how to set the options for best practice checks, see Best practice parameters. This topic includes general principles to follow when you develop workflows and a table of the best practice checks and how to fix the errors.
General Principles
When creating a query for a workflow document, consider the following:
Most document data is available to set up conditions for workflow. In addition, the query identifies workflow placeholders used in messages in the configuration user interface for instructions and notifications. Make sure to use placeholder fields that the end-user can understand and not fields that contain internal data not typically visible to users.
By default, all data fields with the Visible property in the table set to Yes are exposed for workflow conditions. To simplify the set up for workflow conditions, you can remove unnecessary data fields that will not be used for workflow conditions or placeholders in the configuration UI. To remove data fields, set the Dynamic property on the Fields node of the data source to No. Expand the Fields node, right-click a field, and then click Delete. If the query is not saved, the Delete command is not available.
Set the Relations property of the query to Yes if the query system should use the relations that are defined for tables and extended data types. When set to Yes, the query is automatically updated if a relation is changed.
Optionally, set the Join Mode property of the query to Outer Join. Records in one data source are joined even if there are no matching values in the joined field from the second data source. Only fields from Inner Join or Outer Join are visible in the configuration user interface as conditions and placeholders.
In the Properties sheet, set the Table property to the table that contains the data for the workflow document. The root table in the query should be the same as the workflow data source property of the form.
When creating task and approval elements in the Application Object Tree (AOT), be sure to use unique and declarative label names for the element. When adding an approval to a workflow configuration, the label Approval would not be unique enough for the user to determine which approval is to be added.
Use the WorkflowWorkItemActionManager Class to manage task or approval outcome action menu items for type Complete, Return, RequestChange, and Deny.
Best Practice Checks
The following table lists the best practices error messages and how to fix the errors.
Message |
Message type |
How to fix the error or warning |
|---|---|---|
Configuration key not defined |
Error |
The workflow type or a workflow element ConfigurationKey property setting is invalid or not defined. Set the ConfigurationKey property to a valid setting. This property is optional. |
Workflow document not defined |
Error |
The workflow type, task, automated task, or approval Document property setting is invalid or not defined. Set the Document property to a valid setting. For more information, see How to: Create a Workflow Document Class. This property is required. |
Workflow document does not reference a valid class deriving from the WorkflowDocument Class |
Error |
The workflow type, task, automated task, or approval Document property setting must reference a class that extends the WorkflowDocument Class and overrides the WorkflowDocument.getQueryName Method. The class was probably deleted, renamed, or no longer extends the WorkflowDocument Class. For more information, see How to: Create a Workflow Document Class. |
The action menu item is not defined. The action menu item or the action Web menu item must be defined. |
Error |
The task or approval ResubmitMenuItem or DelegateMenuItem property setting is invalid or not defined. Set the menu item to a valid setting. For more information, see How to: Associate an Action Menu Item with a Workflow Task or Approval Outcome. This property is optional. |
Reference to action menu item is invalid |
Error |
The workflow type, task, or approval menu item property setting is invalid or no longer exists. The action menu item was probably deleted or renamed. For more information, see Creating a Workflow Type. |
Reference to web action menu item is invalid |
Error |
The workflow type, task, or approval web menu item property setting is invalid or no longer exists. The web action menu item was probably deleted or renamed. For more information, see Creating a Workflow Type. |
The document menu item is not defined. The document menu item or the document Web menu item must be defined. |
Error |
The task or approval display DocumentMenuItem property setting is invalid or not defined. Set the menu item to a valid setting. For more information, see How to: Associate a Display Menu item with a Workflow Task or Approval. This property is required. |
Reference to display menu item is invalid |
Error |
The task or approval display DocumentMenuItem property setting is invalid or no longer exists. The display menu item was probably deleted or renamed. For more information, see How to: Create a Workflow Task and How to: Create a Workflow Approval. |
Reference to Web URL menu item is invalid |
Error |
The task or approval display DocumentWebMenuItem property setting is invalid or no longer exists. The display menu item was probably deleted or renamed. For more information, see How to: Create a Workflow Task and How to: Create a Workflow Approval. |
Event handler should be defined |
Warning |
The task or approval EventHandler property is invalid or not defined. Set the EventHandler property to the event handler for that workflow element. For more information, see Handling Workflow Events. This property setting is optional. However, when an event handler is not defined, no application logic will run when this event is triggered. |
Event handler not defined |
Error |
The task or approval outcome EventHandler property is not valid or defined. Set the EventHandler property to the event handler for that workflow element. For more information, see Handling Workflow Events. This property is required for all outcomes that are enabled. |
Event handler does not reference a valid class implementing the '%1' interface |
Error |
All workflow type event handlers must implement the appropriate workflow interface. For example, the WorkflowCompletedEventHandler Interface must be implemented by the class that is referenced by the workflow type CompletedEventHandler property setting. For more information, see Handling Workflow Events. |
Module not defined |
Warning |
The workflow category Module property setting refers to a module that is invalid or no longer exists. The module was probably deleted or renamed. For more information, see ModuleAxapta Enumeration. This property is required. |
Category not defined |
Error |
The workflow type Category property setting is not defined. Set the workflow type Category property setting to a valid category. This property is required. |
Invalid reference to workflow category |
Error |
The workflow type Category property setting is invalid or no longer exists. The category was probably deleted or renamed. For more information, see How to: Create a Workflow Category. |
Required element '%1' does not reference same document as the workflow template |
Error |
The Document property setting of the specified task, automated task, or approval workflow element in the workflow type Supported Elements node does not match the Document property setting of the workflow type. Set the specified workflow element Document property setting to match the workflow type Document property setting. For more information, see How to: Create a Workflow Task and How to: Create a Workflow Approval. |
Approve outcome must exist and be enabled |
Error |
The Approve outcome in the approval Outcomes node has the Enabled property setting set to No. Each approval must have at least one enabled outcome of type Complete and an action menu item for the approval work item button to display in the user interface. For more information, see How to: Create a Workflow Approval. |
The element outcome '%1' action menu item property is not defined. The action menu item or the action Web menu item must be defined. |
Error |
The specified task or approval outcome action menu item is invalid or not defined. Set the action menu item to a valid setting. For more information, see How to: Associate an Action Menu Item with a Workflow Task or Approval Outcome. This property is optional. |
Element outcome '%1' ActionWebMenuItem property does not reference a valid web action menu item |
Error |
The specified task or approval outcome action web menu item is invalid or no longer exists. The specified action web menu item was probably deleted or renamed. For more information, see How to: Create a Workflow Task and How to: Create a Workflow Approval. |
Element outcome '%1' ActionMenuItem property does not reference a valid action menu item |
Error |
The specified task or approval outcome action menu item is invalid or no longer exists. The specified action menu item was probably deleted or renamed. For more information, see How to: Create a Workflow Task and How to: Create a Workflow Approval. |
Element outcome '%1' EventHandler property should be defined |
Warning |
The specified task or approval event handler is invalid or not defined. Set the event handler to a valid setting. For more information, see Handling Workflow Events. This property is optional. However, when an event handler is not defined, no application logic will run when this event is triggered. |
Element outcome '%1' EventHandler property does not reference a valid class implementing the '%2' interface |
Error |
The specified task and approval outcome event handler property setting must reference a class that implements the associate event handler interface. An approval, for example, has an Approve outcome of type Complete and the EventHandler property setting must reference a class that implements the WorkflowElementCompletedEventHandler Interface. For more information, see Handling Workflow Events. |
Task outcomes must contain one enabled outcome of type Complete |
Error |
There are no enabled outcomes in the task Outcomes node of type Complete. Each task must have at least one enabled outcome of type Complete and an action menu item for the task work item button to display in the user interface. For more information, see How to: Create a Workflow Task. |
See also
Announcements: New book: "Inside Microsoft Dynamics AX 2012 R3" now available. Get your copy at the MS Press Store.