The workflow document, sometimes referred to as the business document, is the focal point for workflows in Microsoft Dynamics AX 2012. Every workflow type and every workflow element must reference a workflow document because it provides the data context for the workflow. A workflow document is an AOT query supplemented by a class in the AOT (referred to as the workflow document class). The term workflow document is used instead of query because it more accurately portrays what the workflow operates on. The query used by a workflow document can reference multiple data sources and isn’t constrained to a single table. In fact, a query can reference data sources hierarchically. However, if there are multiple data sources within a query, the first data source is considered the primary or root data source.

Workflow in Microsoft Dynamics AX 2012 incorporates an expression builder that you can use to define conditions that control the behavior of an executing workflow. The expression builder uses the workflow document to enumerate the fields that can be referenced in conditions. To make derived data available within conditions, you add parm methods to the workflow document class, and then add X++ code to the parm methods to produce the derived data. The workflow document then returns the fields from the underlying query plus the data generated by the parm methods.

Workflow categories determine the association a workflow type has to a specific module. (Without these categories, you would see all workflows in the context of every module in Microsoft Dynamics AX 2012.) For example, a workflow category named ExpenseManagement, which is mapped to the Travel and Expense module, comes with Microsoft Dynamics AX 2012. All workflows associated with this module are visible in the Microsoft Dynamics AX 2012 client within the Travel and Expense module. If you add a new module to Microsoft Dynamics AX 2012, you must create a new module and a new workflow category that references that module.

The workflow type (called a “template” in Microsoft Dynamics AX 2009) is the primary building block that developers use to create workflows. You generate the workflow type by using the new Workflow wizard, shown in Figure 8-3. The wizard automates the creation of the metadata required for a workflow type; all you need to do is specify the name, workflow category, query, and menu items.

Figure 8-3. The Create Workflow Type page in the Workflow wizard

The resulting metadata is created under the AOTWorkflowWorkflow Types node. The business process owner later references this workflow type when creating an actual workflow.

For more information about the Workflow wizard, see “How to: Create a New Workflow Type” at http://msdn.microsoft.com/en-us/library/cc594095.aspx.

Event handlers are well-defined integration points that developers use to trigger application-specific business logic during workflow execution. Workflow events are exposed at the workflow level and the workflow element level. For more information about event handlers, including where they are used, see “Workflow Events Overview” at http://msdn.microsoft.com/en-us/library/cc588240.aspx.

Workflow in Microsoft Dynamics AX 2012 uses both display and action menu items. Display menu items are used to navigate to a form in the Microsoft Dynamics AX 2012 client that displays the details of the record being processed by workflow. Web menu items are used to navigate to the same type of webpage in Enterprise Portal. Action menu items are used for each possible action that a user can take in relation to a workflow. They also provide another integration point for you to integrate custom code. For more information about the menu items that are used in the workflow infrastructure, see “How to: Associate an Action Menu Item with a Workflow Task or Approval Outcome” (http://msdn.microsoft.com/en-us/library/cc602158.aspx) and “How to: Associate a Display Menu item with a Workflow Task or Approval” (http://msdn.microsoft.com/en-us/library/cc604521.aspx).

The elements of a workflow represent the activities within the workflow. The business process owner models these elements. An element can be a task, an approval, a subworkflow, a manual decision, an automated decision, a parallel activity with multiple branches, a line-item workflow, or an automated task. Developers implement the task, approval, line-item workflow, and automated task elements. The rest are referred to as “configuration only” elements that business process owners can use in the graphical workflow editor. The following list describes each element:

Manual and automated decisions, parallel activity, line-item workflows, and automated tasks are new in Microsoft Dynamics AX 2012. In addition workflow wizards have been added to make the creation of approval and task elements easier.

The ability to assign workflow work items to a queue is new in Microsoft Dynamics AX 2012. Queues offer an alternative to assigning workflow work items directly to users by providing support for teams that collaborative within a business process. With this approach, a work item is first assigned to a queue; then, the work item is claimed by a member of the queue so it can be worked on. The eventual work item owner can also return the work item to the original queue, put the work item in another queue, or assign the work item to another user.

To use work item queues, complete the following steps:

For more information about setting up work item queues, see “Configure work item queues” at http://msdn.microsoft.com/en-us/library/gg731875.aspx.

Workflow in Microsoft Dynamics AX 2012 uses the provider model as a flexible way of allowing application-specific code to be invoked for different purposes when a workflow is executing. There are four provider types within the workflow infrastructure: due date, participant, hierarchy, and queue. The way in which provider metadata is stored has changed in this release. In Microsoft Dynamics AX 2009, providers were developed as classes that implemented a provider interface and were registered on the workflow element as a property. Workflow providers in Microsoft Dynamics 2012 now have their own node in the AOT (AOT > Workflow > Providers), as shown in Figure 8-4.

Figure 8-4. The new Workflow Providers node in the AOT.

In addition each provider now has properties that are used to define the following:

For more information about workflow providers, including where they are used, see “Workflow Providers Overview” at http://msdn.microsoft.com/en-us/library/cc519521.aspx.

The business process owner creates workflows using the new graphical workflow editor (shown in Figure 8-5) in the Microsoft Dynamics AX 2012 client. The business process owner first selects a workflow type and then configures the approvals, tasks, and other elements that control the flow of activities through the workflow.

Figure 8-5. The new graphical workflow editor.

Workflows are located in the Microsoft Dynamics AX 2012 client. A list page containing the workflows for a given module is located on the area page for the module under Setup > [module name] workflows.

A workflow instance is an activated workflow created by combining the workflow and the underlying AOT workflow elements on which the workflow is based (the workflow type, tasks, and approvals).

Workflow instances are located in the Microsoft Dynamics AX 2012 workflow runtime.

Work items are the actionable units of work that are created by the workflow instance at run time. When a user interacts with a workflow, he or she responds to a work item that has been generated from a task element, an approval element, or a manual decision. Work items are displayed in the Unified worklist web part and in the Microsoft Dynamics AX 2012 client.

Figure 8-6 shows the components of the workflow runtime and their interaction.

Figure 8-6. Workflow runtime.

The workflow runtime includes the following components:

Figure 8-7 shows the logical control flow the workflow runtime uses to process a workflow activation message.

Figure 8-7. Logical workflow runtime control flow used to process a workflow activation message.

As an example of how these components interact at run time, the following sequence explains what happens when a user clicks Submit to activate a workflow on a record in Microsoft Dynamics AX 2012:

Figure 8-8 shows the logical workflow runtime control flow to process a workflow started message.

Figure 8-8. Processing a workflow started message.

The flow in Figure 8-8 builds on the flow in Figure 8-7. A workflow started message is currently posted to the message queue and is ready for processing as follows:

Another way to visualize how the key workflow concepts and architecture come together is to look at the interaction patterns of approval and task elements at run time. Four main types of interactions can occur: workflow events, acknowledgments (of events), provider callbacks, and infrastructure callbacks.

Figure 8-9 shows the logical workflow interactions for approvals.

Figure 8-9. Logical approval workflow interactions.

In Figure 8-9, the outermost box represents the workflow itself. Nested inside are the approval (element) and within that, a single step. (An approval can contain multiple steps.) The smaller rectangular boxes represent events or outcomes. The symbols in the legend represent the four interaction types, which are positioned in Figure 8-9 where that type of interaction occurs. When the workflow starts, an event and an acknowledgment occur. Acknowledgments confirm that the workflow runtime received and processed a preceding event. A similar event and acknowledgment occur for the start of the approval element. When a step starts, callbacks invoke the workflow providers to resolve the users for assignment and the due dates for the corresponding work items. The work items are then created through an infrastructure callback, and the workflow instance waits for the corresponding acknowledgments from the work items. Acknowledgments for work items are triggered when users take action on their assigned work items. After the step (or steps) complete, the outcome is determined based on the completion policies of the step, and the corresponding event is raised for that outcome. The workflow instance then waits for acknowledgment that the workflow runtime has processed the event that is associated with the outcome. Finally, the completion of the workflow itself raises an event.

Task interactions are similar to approvals, except that no steps and outcomes are unique for each task. Figure 8-10 shows the logical workflow interactions for tasks.

Figure 8-10. Logical task workflow interactions.

As a developer, once you understand the workflow requirements that the business process owner provides, you must create the corresponding workflow artifacts, dependent workflow artifacts, and business logic. You create these in the AOT by using the Microsoft Dynamics AX 2012 client. You write the business logic in X++.

Table 8-1 lists each workflow artifact and the steps you need to perform when creating it. The artifacts are listed in order of dependency.

Table 8-2 identifies the dependent workflow artifacts that are referenced in Table 8-1.

A state model defines a set of states and the transitions that are permitted between the states for a given record type, along with an initial state and a final state. State models exist to provide a prescriptive life cycle for the data they are associated with. The current state value is often stored in a field on a record. For example, the PurchReqTable table (the header for a purchase requisition) has a status field that is used to track the approval state of a purchase requisition. The business logic for purchase requisitions is coded to respect the meaning of each state and the supported state transitions so that a purchase requisition record can’t be converted into a purchase order before the state is approved.

The simplest way to add and manage the state on a record is to use a single field to store the current state, but you have to determine the approach that makes the most sense. You would then create a static X++ class that implements the business logic that governs the state transition. Conceptually, you can think of this class as a StateManager class. All existing business logic that performs the state transitions should be refactored to use this single, central class to perform the state transitions, in effect isolating the state transition logic into a single class. From a workflow perspective, state transitions always occur at either the beginning or the conclusion of a workflow element. This is why all workflow tasks and workflow approvals have EventHandlers that can be used to invoke a StateManager class. Figure 8-12 shows the dependency chain between an event handler and the workflow document state.

Figure 8-12. State management dependency chain.

When you decide to enable a workflow for a table in Microsoft Dynamics AX 2012 and determine that the table has a state that must be managed, you must refactor all business logic to respect the state model that you define to avoid unpredictable results. Create operations should always create a record with the initial state (for the state model). Update operations must respect the current state and fail if the state isn’t as expected. For example, it shouldn’t be possible to change the business justification of a purchase requisition after it has been submitted for approval. Managing the state of the record during each update so that the current state is verified and the next logical state is updated is typically implemented in the update method on the table by calling the StateManager class. If it returns a value of true, perform the update. If not, throw an exception and cancel the operation. Figure 8-13 shows a simple state model for a record.

Figure 8-13. A simple state model for approvals.

In Figure 8-13, the initial state is NotSubmitted. When a record is submitted to workflow, the state changes to Submitted. After the workflow is activated, the state becomes PendingApproval. If a workflow participant selects the Request Change action, the state changes to ChangeRequested. After all approvals are submitted, the final state is Approved.

You use workflow categories to associate a workflow type with a module. This association restricts the list of types that are shown when the business process owner edits a workflow for a particular module, preventing a list of all workflow types from being displayed. For example, if a user is in the Accounts Payable module, the user sees only the workflow types that are bound to Accounts Payable. The mechanism behind this grouping is a simple metadata property on the workflow type called Workflow category. This property allows you to select an element from the module enum (AOTData DictionaryBase enumsModuleAxapta).

With this mechanism, it is easy for ISVs and partners who create their own modules to extend the module enum and thus have workflow types that can be associated with that module. Note that a workflow category can be associated with only one module.

The purpose of a workflow is to automate all or part of a business process. To do this, it must be possible to define various rules for the document that is being processed by workflow. In Microsoft Dynamics AX 2012, these rules are called conditions. A business process owner creates conditions when modeling the workflow. For example, conditions can be used to determine whether a purchase requisition is approved automatically (without any human intervention). Figure 8-14 shows a simple condition defined in the graphical workflow editor.

Figure 8-14. A simple condition defined in the graphical workflow editor.

When a business process owner defines a condition by using the graphical workflow editor, he or she needs to make sure that users have a way to select the fields from the workflow documents they want to use. On the surface, this seems simple, but two requirements complicate the task. First, not all the fields in a table might make sense to the business process owner, and therefore only a subset of the fields should be exposed. Second, it must be possible to use calculated fields (also called derived data). The workflow document class meets these two requirements by functioning as a thin wrapper around an AOT query that defines the available fields and by providing a mechanism for defining calculated fields.

The AOT query enables developers to define a subset of fields from one or more related tables. By adding nested data sources in a query, you can model complex data structures. However, the most common usage is to model a header-line pattern. At design time, when the business process owner is editing a workflow, the AOT query is used by the condition editor to determine which fields to display to the business process owner.

The workflow infrastructure uses a prescriptive pattern to support calculated fields by using parm methods that are defined within the workflow document class. These methods must be prefixed with parm and must implement a signature of (CompanyId, TableId, RecId). The workflow infrastructure then, at run time, calls the parm method and uses the return value in the condition evaluation. This design enables developers to implement calculated fields in parm methods on the workflow document class.

Creating a workflow document class involves creating an X++ class that extends WorkflowDocument. You must override the getQueryName method to return the name of the workflow document query. Figure 8-15 shows a sample X++ class that extends WorkflowDocument.

Figure 8-15. A sample X++ class that extends from the workflow document.

Creating a parm method involves adding a method to the workflow document class and then adding X++ code to calculate or otherwise determine the value to be returned, as shown in Figure 8-16.

Figure 8-16. A parm method within a workflow document class that returns the approval amount (which is calculated).

Workflow display menu items enable users to navigate directly to the Microsoft Dynamics AX 2012 client form (or Enterprise Portal webpage) from which they can select one of the available workflow actions. A user is prompted to participate in a workflow when he or she receives a work item from the workflow at run time. When viewing the work item, the user can click Go To <Label>. This button is automatically mapped to the workflow display menu item, and the button text (<Label>) is the label of the root table of the workflow document query.

This design enables developers to create task-based forms that are focused on the particular task at hand, rather than having to create monolithic forms that assume the user knows where in the process he or she is acting and which fields and buttons to use.

Workflows in Microsoft Dynamics AX 2012 are always explicitly activated; either a user does something in the Microsoft Dynamics AX 2012 client or in Enterprise Portal that causes workflow processing to start, or the execution of business logic starts a workflow. (Once you understand how users activate a workflow, you can use this knowledge to activate workflows through business logic.)

For the first activation approach to work, the workflow infrastructure must have a way to communicate information to the user about what to do. For example, it might be relevant to instruct the user to submit the purchase requisition for review and approval at the appropriate time. The requirements to communicate with users throughout the workflow life cycle gave Microsoft an opportunity to standardize the way users interact with workflow in both the Microsoft Dynamics AX 2012 client and Enterprise Portal, including activating a workflow, and this resulted in the development of workflow common UI controls. The workflow common UI controls include the yellow workflow message bar (highlighted in Figure 8-17) and the workflow action button, labeled Submit.

Figure 8-17. A purchase requisition ready to be submitted to workflow for processing.

The workflow common UI controls appear on the Purchase requisition form because that form has been enabled for workflow. To enable workflow in a form, you set the WorkflowEnabled property on the form to Yes in the Properties window, which is shown in Figure 8-18. You must also set the WorkflowDataSource property to one of the data sources on the form. The selected data source must be the same as the root data source that is used in the query referenced by the workflow document. Finally, you can set the WorkflowType property to constrain the form to use a specific workflow type.

Figure 8-18. Design properties for a Microsoft Dynamics AX 2012 form, including those for workflow.

If workflow is enabled for a form, the workflow common controls automatically appear in three cases:

The workflow common control uses the algorithm shown in Figure 8-19 to determine which workflow to use.

After a workflow has been identified, it’s easy for the workflow common UI controls to obtain the SubmitToWorkflow action menu item. This action menu item is then dynamically added to the form, along with the yellow workflow message bar.

If you look at the SubmitToWorkflow action menu item for the PurchReqApproval workflow type, you’ll notice that it is bound to the PurchReqWorkflow class. When you click the Submit button, the action menu items call the main method on the class it is bound to; thus, the code that activates the workflow is called from the main method. In this case, the call to the workflow activation API has been isolated within the submit method.

Figure 8-19. Workflow activation logic flowchart.

In Figure 8-20, notice how the Workflow::activatefromWorkflowType method is used. You can use two additional APIs to activate workflows: Workflow::activatefromWorkflowConfiguration and Workflow::activateFromWorkflowSequenceNumber.

Figure 8-20. The Submit method for the purchase requisition workflow.

For information about how to use these APIs, see the Microsoft Dynamics AX 2012 developer documentation on MSDN: http://msdn.microsoft.com/en-us/library/cc586793.aspx.

Understanding how to activate a workflow is important, but it is equally important to understand how to prevent a workflow from being activated. For example, you don’t want a user to submit a record to workflow before it is in a state to be submitted. An override method on the table or form, canSubmitToWorkflow, addresses this requirement. The canSubmitToWorkflow method returns a Boolean value. A value of true indicates that the record can be submitted to workflow. When the workflow data source on the form is initialized or when the record changes, this method is called; if it returns true, the Submit button is enabled. Typically, you should update the state of the document after invoking the workflow activation API so that you can correctly denote whether a document has been submitted to workflow. (In Figure 8-20, the purchase requisition is transitioned to the In Review state.)