The objectives of this chapter are to:
Explain what workflow is and what it’s designed to do, how it works, and why it’s architected the way it is in Microsoft Dynamics AX 2009.
Provide an overview of the most useful workflow concepts from a development perspective.
Explain how to implement the artifacts that are required to build a workflow template.
Very few of us would deny the importance or significance of the processes that drive the businesses and organizations that we work for and interact with on a daily basis. Business processes represent the key activities that, when carried out, are meant to achieve a specific goal of value to the business or organization:
Think of a manufacturing operation in which business process activities include the initiation, design, development, quality assurance testing, and delivery of a saleable (and hopefully profitable) range of goods.
Think of sales process activities for manufactured items, including marketing, locating prospects, providing quotes, converting quotes to orders and prospects to customers, shipping the product, invoicing, and obtaining payment.
Finally, think about some of the supporting business processes that are concerned with hiring new employees and managing employee expenses, which contribute to the business or organization in tangible ways.
Viewing activities in terms of the business processes that encompass them affords businesses and organizations the opportunity to systematically define, design, execute, evaluate, and improve the way that these activities are performed. This systematic approach is extremely valuable, even critical, given that today’s businesses and organizations have to react to the increasingly rapid rate of change we’re witnessing in business and industry, and the ever-expanding influence of globalization.
Enterprise resource planning (ERP) suites, such as Dynamics AX, exist to automate business processes and to provide the capability to adapt these processes to the specific needs of businesses and organizations over time. Before Dynamics AX 2009, no standard workflow infrastructure existed, and each company had to write specific business logic to implement everyday activities, such as approvals. The Dynamics AX 2009 release includes a built-in workflow infrastructure precisely to make it easier for businesses and organizations to automate and manage business processes.
Fundamentally, workflows consist of one or more workflow activities that represent the items of work to be completed. Additionally, the concept of flows that connect the activities and govern the sequence of execution (referred to as the structure of a workflow) is key. The behavior of workflows is determined by their type. Figure 9-1 illustrates the major types of workflow and identifies where the emphasis of the workflow infrastructure is in Dynamics AX 2009.
A major distinction exists between human workflows and system workflows. (For more information, see the following "Types of Workflow" sidebar.) Workflow in Dynamics AX 2009 is primarily designed to support structured human workflows. The structured human workflows that are shipped with the product include expense approval, requisition review and approval, and the approval of financial journals. Whereas the built-in workflows focus on structured human workflows that obtain approvals, you can also create workflows that contain tasks for humans to complete or a mixture of structured and unstructured tasks along with an approval. Customers, partners, and independent software vendors (ISVs) can create additional workflows to supplement those in the product. The workflows included in Dynamics AX 2009 will be augmented in future releases.
Note
The main difference between business processes and workflows (as these terms are often used interchangeably) is their scope, level of abstraction, and purpose. Business processes represent the broad set of activities that a business or organization needs to carry out, and their interrelationships. Business processes are implementation independent and can combine manual as well as automated activities. Workflows are the automated parts of a business process that coordinate various human or system (or both) activities to achieve a particular outcome, and they are implementation specific. Therefore, workflows are used to implement parts of a business process.
Because existing Dynamics AX modules use approvals extensively, the workflow infrastructure in Dynamics AX 2009 is primarily intended to support structured human workflows. Focusing on this type of workflow lays the groundwork for enabling businesses and organization to more easily automate, analyze, and improve high-volume workflows across their ERP system.
Each structured human workflow in Dynamics AX 2009 acts on a single document type. The reason for this is that data is the key currency of ERP systems (think of the broad categories of data that exist in an ERP system: master data, transaction data, and reference data), and processes that operate within those systems are largely data-driven.
Here are some of the key tasks that you can do with structured human workflows in Dynamics AX 2009:
Define the activities that need to take place based on the business process that is being automated.
Sequence tasks, approvals, and subworkflows to reflect the order in which activities need to be completed in a business or an organization.
Set up a condition that is used to determine which workflow to use in a given situation.
Decide how to assign the activity to people.
Specify the text that is displayed in the user interface for the various activities to help people understand what they need to do.
Define a set of outcomes for an activity that someone can select from.
Select which notifications to send, when to send the notifications, and who should receive the notifications.
Establish how a workflow should be escalated if there is no timely response to an activity.
Four types of users interact with the workflow infrastructure in Dynamics AX 2009:
Business users
Developers
Administrators
End users (referred to as "users" in this book)
Business users and developers are primarily responsible for defining, designing, and developing workflows. Administrators and users interact with workflows that are executing.
Business users. understand the objectives of the business or organization within which they operate to the degree that they can envision how best to structure the various activities within their areas of responsibility. Business users therefore configure workflows that have already been implemented and work with developers to enable other modules or create new workflow templates in existing modules.
Developers. work with the business users to design and implement any underlying code that is required to support workflows that are being developed.
Administrators. are responsible for setting up and maintaining the development and production environments, for ensuring that the workflow infrastructure is configured correctly, for monitoring workflows as they execute, and for taking actions that are needed to resolve any issues with workflows.
Users. interact with workflows when needed, including taking a particular action (such as approving or rejecting), entering comments, viewing workflow history, and so on.
There is a relationship between the workflow infrastructure in Dynamics AX 2009 and Windows Workflow Foundation, which is part of the .NET Framework 3.5. Windows Workflow Foundation provides many fundamental capabilities that are used by the workflow infrastructure in Dynamics AX 2009. As a low-level infrastructure component, however, Windows Workflow Foundation has no direct awareness of or integration with Dynamics AX 2009. In Figure 9-2, the workflow infrastructure (labeled A) is an abstraction layer that sits above Windows Workflow Foundation (labeled B) and allows workflows that are specific to Dynamics AX to be designed, implemented, and configured in Dynamics AX 2009 and then executed by using Windows Workflow Foundation.
Figure 9-2. Relationship between the Dynamics AX 2009 workflow infrastructure and Windows Workflow Foundation
In the following list, each numbered item refers to the corresponding part of Figure 9-2.
The developer designs and implements workflow elements and business logic in the Application Object Tree (AOT).
The business user configures workflows in the Dynamics AX 2009 client.
The workflow runtime bridges both the Dynamics AX 2009 workflow infrastructure and Windows Workflow Foundation; it instantiates and then executes workflow configurations. (The administrator manages the runtime environments.)
Users interact with workflow user interface controls both in the Dynamics AX 2009 client and in Enterprise Portal.
You can use the Dynamics AX 2009 workflow infrastructure to automate aspects of a business process that are part of a larger business process automation effort. There is no single, correct approach to this undertaking, but at a high level, you can follow the steps listed here to figure out and understand your existing business processes, then to determine how these business processes should function, and finally to automate them by using workflow.
Map out existing business processes. This effort is often referred to as developing the as-is model.
Analyze the as-is model to determine whether obvious improvements can be made to existing processes; these improvements are represented in another business process model, which is often referred to as the to-be model.
Design the way in which you’re going to implement the to-be business process model—or the changes to the as-is model suggested by the to-be model. In this step, you might decide which parts of the to-be business process need to be automated with workflow and which parts should remain manual.
For the parts of the business process model in which workflow is going to be used—and for the parts you want to automate—define the workflow document and design one or more workflows. This step centers on the workflow document that the workflow will act over.
The developer implements the workflows.
The business user configures and enables the workflows, causing workflow instances to be created when a record for the workflow document is submitted.
The major advantage of the workflow infrastructure in Dynamics AX 2009 is that it provides a significant amount of functionality out of the box, meaning that custom workflows don’t have to be written. Businesses and organizations will have more time to focus on improving their processes instead of writing and rewriting business logic. Additionally, the Dynamics AX 2009 workflow is continually being enhanced in response to feedback from customers, partners, and ISVs to provide even more value in subsequent releases, making the investment in workflow increasingly valuable over time.
From your perspective as a Dynamics AX developer, workflow is something that you work with to help the users in your business or organization in their efforts to improve efficiency. The ultimate goal for workflow in Dynamics AX 2009 is to make it as easy as possible for business users to fully configure workflows themselves, freeing developers to work on other activities. Currently, developers and business users work together to create and customize workflows, which consumes time and resources for both parties.
As a Dynamics AX developer, you need to understand a number of key concepts to successfully help business users implement workflows.
The workflow document, sometimes referred to as the Business Document, is the focal point for workflows in Dynamics AX 2009. Every workflow template 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 is operating on. A query 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 one.
Note
The workflow document and workflow document class are located in the AOT in the Dynamics AX 2009 client.
Workflow in Dynamics AX 2009 incorporates the use of an expression builder to enable conditions to be defined that control the behavior of an executing workflow. The expression builder uses the workflow document to enumerate all the fields that can be referenced in conditions. Calculated fields are not supported on queries in Dynamics AX 2009. Therefore, to make derived data available within conditions, you add parm methods to the workflow document class, into which X++ code can be introduced 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 whether a workflow template is associated to a specific module. (Without these categories, you could see all workflows in the context of every module in Dynamics AX 2009.) For example, a workflow category named ExpenseManagement, which is mapped to the Expense Management module, comes with Dynamics AX 2009. All workflows associated to this module are visible in the Dynamics AX 2009 client within the Expense Management module. If you add a new module to Dynamics AX 2009, you must create a new module and then a new workflow category that references that module.
The workflow template is the primary building block used to create workflows. The developer defines the workflow template in AOTWorkflowWorkflow Templates. Defining the workflow template involves setting the various properties (including workflow document and workflow category). The business user later references this workflow template when creating a workflow configuration.
Event handlers are well-defined integration points that enable you to execute 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 http://msdn.microsoft.com/en-us/library/cc588240.aspx.
Workflow in Dynamics AX 2009 uses both display and action menu items. Display menu items are used to navigate to either a form in the Dynamics AX 2009 client or to a Web page in Enterprise Portal that displays the details of the record being processed by workflow. Action menu items are used for each possible action a user can take in relation to a workflow. They also provide another integration point for developers to integrate custom code. For more information about the menu items that are used in the workflow infrastructure, see http://msdn.microsoft.com/en-us/library/cc602158.aspx and http://msdn.microsoft.com/en-us/library/cc604521.aspx.
The elements of a workflow represent the activities that can be configured within a workflow. The business user configures these elements; the developer creates them. An element can be a task, an approval, or a subworkflow.
Approvals are specialized tasks that allow sequencing of multiple steps and use a fixed set of outcomes.
Tasks are generic workflow elements that represent a single unit of work. The developer defines the possible outcomes for each task.
Subworkflows are workflows that are invoked from other workflows.
The workflow structure is made up of sequences of workflow elements.
Workflow in Dynamics AX 2009 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 three providers in workflow: due date, participant, and hierarchy. For more information about workflow providers, including where they are used, see http://msdn.microsoft.com/en-us/library/cc519521.aspx.
The business user creates the workflow configurations using the workflow configurations form in the Dynamics AX 2009 client. The business user first selects a workflow template and then configures the approvals and tasks that control the flow of activities through the workflow.
A workflow instance is an activated workflow created by combining the workflow configuration and the underlying AOT workflow elements on which the workflow configuration is based (the workflow template, tasks, and approvals).
Work items are the actionable units of work that are created by the workflow instance at run time. When a user interacts with workflow, he or she is responding to a work item that has been generated from a task or approval element. Work items are surfaced in the Dynamics Unified Worklist Web part and in the Dynamics AX 2009 client.
Microsoft designed the workflow infrastructure based on a set of assumptions and goals relating to the functionality it wanted to deliver. Two assumptions were the most significant:
Business logic (X++) invoked by workflow would always be executed in the Application Object Server (AOS).
Workflows would be managed by Windows Workflow Foundation in .NET Framework 3.5, which operates in a managed environment.
The first assumption reflects the fact that most business logic resides and is executed in the AOS. The second assumption was based on the opportunity to use existing Microsoft technology for executing workflows in Dynamics AX 2009 instead of designing and implementing this functionality from scratch. The choice, however, required finding a suitable host for Windows Workflow Foundation, because it wasn’t possible to host by using the unmanaged AOS. In the end, Microsoft decided to host Windows Workflow Foundation by using Internet Information Services (IIS 6.0) and to establish a mechanism for communicating back and forth between AOS and IIS. Two workflow runtimes are the result of this decision: one in AOS, and another in IIS.
These primary goals influenced the architecture:
To create an extensible/pluggable model for workflow integration (including events and providers), because the workflow infrastructure had to be flexible enough to address potentially unknown future requirements.
To achieve reliable and durable communication between the AOS and IIS runtimes given that they would exist in separate processes.
To secure communication between the runtimes given that they would be communicating across process boundaries.
To minimize the performance impact on transactional X++ business logic to invoke workflow runtime services. For example, if workflow activation is triggered from saving a document, no adverse performance side-effects should result for doing this in the same physical transaction (ttsbegin/ttscommit) as the save operation.
To build in scalability that accommodates the growth in use of workflow in Dynamics AX over time, and to provide options, such as multimachine deployments, to attain such scalability.
In the following section, we expand on the capabilities of each of the workflow runtimes.
Figure 9-3 shows the parts of the AOS workflow runtime.
The AOS runtime includes the following parts:
Workflow Application Framework. A thin API that exposes the underlying workflow functionality to the rest of Dynamics AX 2009.
Communication. Manages the communication to IIS through CLR interop calls to the Web services that are exposed by the IIS workflow runtime. It then exposes the entry points for .NET Business Connector calls back into the AOS workflow runtime from IIS.
Messaging. Manages and processes workflow messages. Messages are processed on the AOS by a server-bound batch job.
Tracking. Manages the tracking information that is stored during workflow execution.
Work items. Manages the work items that are created when tasks and approvals get assigned to individual users.
Expressions. The condition evaluation engine that evaluates the Boolean expressions defined in a workflow configuration. Such Boolean expressions include workflow activation conditions, approval/task autocomplete conditions, approval step preconditions, and hierarchy stop and filter conditions.
Configuration. Manages the workflow configurations that are created using the workflow configuration form or the workflow configuration API.
Metadata. Manages the metadata for the workflow artifacts in the AOT. These artifacts include workflow categories, tasks, approvals, and templates.
Figure 9-4 shows the IIS workflow runtime.
These are the parts of the IIS workflow runtime:
Workflow Web services. Entry point into the IIS workflow runtime for calls originating from the AOS through workflow message processing.
Workflow Message and Instance Manager. Manages the correlation of incoming messages to running workflow instances and the activation of new workflow instances.
Workflow activities and services. Dynamics AX 2009 extensions, called custom activities, to the activity model in Windows Workflow Foundation. These extensions provide logic tailored to Dynamics AX 2009 and provide the run-time semantics for the workflow elements that are exposed in the workflow configuration (approvals, tasks, subworkflows).
Windows Workflow Foundation. The workflow framework provided in .NET Framework 3.5.
.NET Business Connector facade. Abstracts the workflow runtime away from the AOS. This thin abstraction surfaces a set of services and proxy classes that enable communication from the IIS workflow runtime back into the AOS through .NET Business Connector.
Figure 9-5 shows the logical interaction between the IIS and AOS workflow runtimes. Three main elements are involved: the client (which represents both the Dynamics AX 2009 client and Enterprise Portal), the AOS workflow runtime, and the IIS workflow runtime.
The IIS workflow runtime consists of the following parts:
Workflow Web services. These act as the interface to the IIS workflow runtime. Web service calls are made from the messaging batch job to the IIS workflow runtime by using these services.
Windows Workflow Foundation and extensions. The core of the IIS runtime is Windows Workflow Foundation and the Dynamics AX 2009 extensions, or custom activities, of the framework.
.NET Business Connector. The Dynamics AX integration component, used in this case to complete the request round-trip back to the AOS runtime.
The AOS workflow runtime consists of the following parts:
Workflow Application Framework. A thin API that exposes the underlying workflow functionality to the rest of the application.
Workflow runtime services. The collective set of workflow subsystems hosted by the AOS to facilitate workflow processing.
Message queue. The workflow runtime in the AOS interacts with the IIS runtime by exchanging messages, and the message queue in the AOS is used to stage workflow messages before being processed by the messaging batch job.
Application code. The X++ code that is invoked by workflow, for example, in event handlers and providers.
Messaging batch job. A server-bound batch job that is dedicated to periodically processing messages in the message queue and sending requests to the IIS workflow runtime.
As an example of how these elements interact at run time, the following list explains what happens when a user clicks Submit to activate workflow processing on a record in Dynamics AX 2009:
The Submit action invokes the Workflow Application Framework to post an activation message for the selected workflow configuration. This causes a message to be inserted into the message queue, the purpose of which is to instantiate the workflow in the IIS workflow runtime.
The message is processed by the messaging batch job, and the request is dispatched to the Workflow Web services on the IIS workflow runtime.
The Workflow Web services process the request and invoke the Windows Workflow Foundation activation API.
After a workflow instance is activated, a workflow-started message is dispatched from the IIS workflow runtime to the AOS workflow runtime using a Dynamics AX 2009 custom activity, which calls through .NET Business Connector. The state of the workflow instance is persisted to the Dynamics AX database together with the posting of the workflow-started message. The activation message is also removed/dequeued at this time.
The workflow-started message is then processed by the workflow messaging batch job, which invokes the WorkflowStarted event handler for the corresponding workflow template.
After the WorkflowStarted event handler has been invoked, an acknowledgment message is posted to the message queue, to be sent back to the IIS workflow runtime to continue execution of the workflow instance. The workflow-started message is also removed/dequeued at this time.
This communication metaphor is repeated throughout the life cycle of a given workflow instance for all types of workflow messages.
One 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.
Workflow event. A callback to the AOS to post a message, save the workflow instance, and remove/dequeue the originating message. The workflow then waits for the corresponding message to be processed. The AOS processes the message by invoking the event handler on the corresponding workflow template, task, or approval. Then the AOS posts the acknowledgment message.
Acknowledgment. An acknowledgment message responds to every event processed by the AOS. Upon receiving the acknowledgment, the IIS workflow runtime loads the workflow instance from the Dynamics AX database and resumes the instance from where it left off.
Provider callback. A call from the IIS workflow runtime into the AOS workflow runtime to retrieve users or due dates. Workflow providers are integration points for developers to inject custom code for resolving users and due dates. A provider callback is a synchronous call from the IIS workflow runtime back into an X++ workflow provider hosted in the AOS.
Infrastructure callback. A call from the IIS workflow runtime back into the AOS workflow runtime to perform infrastructure-related activities. One example is to create work items for each user returned from a call to a participant provider.
Figure 9-6 shows the logical workflow interactions for approvals.
In Figure 9-6, 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 9-6 where that type of interaction occurs. When the workflow starts, an event and an acknowledgment occur. Acknowledgments confirm that the AOS workflow runtime received and processed a preceding event initiated in the IIS workflow runtime. The same event and acknowledgment occur for the start of the approval element. When a step starts, there are callbacks for the workflow providers, which are invoked at this point. (Typically, the participant provider is executed to obtain workflow participants, and the due date provider is executed to determine due dates for work items.) The work items are then created via an infrastructure callback, and the workflow waits for the corresponding acknowledgment for each work item that was created. Acknowledgments for work items are triggered when users take action on assigned work items. After the step (or steps) completes, the outcome is determined based on the completion policies of the step, and the corresponding event is raised for that outcome. The workflow then waits for acknowledgment that the AOS processed the outcome’s event. Finally, the completion of the workflow itself raises an event.
The task interactions are similar to approvals, except no steps and outcomes can be unique per task. Figure 9-7 shows the logical workflow interactions for tasks.
In summary, the logical workflow interaction figures in this section clarify when event handlers fire during the life of a workflow and when a workflow needs to call out to providers.
In this section, we describe the workflow life cycle, shown in Figure 9-8, and explain the design phase of the life cycle in detail.
The workflow life cycle has three phases:
Design. Business users decide what parts of a business process that traverses Dynamics AX 2009 need to be automated and then design a workflow to achieve this automation, leveraging their understanding of the business processes and the organization. They can collaborate with developers in this phase, or they might just communicate the workflow requirements to the developers, who then create the necessary artifacts in Dynamics AX 2009. The artifacts enable the workflow that the business users will later configure.
Configure. After the necessary artifacts are in place, business users configure the workflow in Dynamics AX 2009. If this work is carried out on a test system, after successfully testing the workflow, the administrator deploys the related artifacts and workflow configuration to the live or production system.
Run. Users interact with Dynamics AX 2009 as part of their day-to-day work, and in the course of doing so, might submit workflow documents to the workflow for processing as well as interact with workflows that are already activated.
This cycle is repeated when the workflow that has been designed, configured, and deployed needs to change in some way, for example, because of a change in a business process or in the organization.
As a developer, once you understand the workflow requirements the business user has provided, you must create the corresponding workflow artifacts, dependent workflow artifacts, and business logic. You create all these in the AOT by using the Dynamics AX 2009 client. You write the business logic in X++.
Table 9-1 lists each workflow artifact and the steps you need to perform when creating it. The artifacts are explicitly listed in order of dependency.
Table 9-1. Workflow Artifacts
Steps | |
|---|---|
Workflow category | Define the module within which the workflow template is enabled. For more information, see the "Key Workflow Concepts" section earlier in this chapter. |
Approval | Define the approval workflow document. Define approval event handlers for Started and Canceled. Define approval workflow providers for Participant, DueDate, and Hierarchy. Define approval menu items for Document, DocumentWeb, Resubmit, ResubmitWeb, Delegate, and DelegateWeb. Enable or disable approval outcomes. Define approval outcome menu items for Action and ActionWeb. Define approval outcome event handler. Define the DocumentPreviewFieldGroup. |
Task | Define the task workflow document. Define task event handlers for Started and Canceled. Define task workflow providers for Participant, DueDate, and Hierarchy. Define task menu items for Document, DocumentWeb, Resubmit, ResubmitWeb, Delegate, and DelegateWeb. Add/remove task outcomes. Define task outcome menu items for Action and ActionWeb. Define task outcome event handler. Define the DocumentPreviewFieldGroup. |
Workflow template | Define the workflow document. Define event handlers for workflow Started, Completed, ConfigDataChanged, and Canceled. Define menu items for SubmitToWorkflow, SubmitToWorkflowWeb, Cancel, and CancelWeb. Define the workflow category. (Select from the existing categories.) Define required approvals and tasks, and sequencing of required approvals and tasks. Enable or disable activation conditions for workflow configurations based on the template. For information about creating workflow templates, see http://msdn.microsoft.com/en-us/library/cc641259.aspx. |
Table 9-2 identifies the dependent workflow artifacts that are referenced in Table 9-1.
Table 9-2. Dependent Workflow Artifacts
Description | |
|---|---|
Workflow document query | Defines the data in Dynamics AX 2009 that a workflow acts on, and exposes certain fields that the business user uses for constructing conditions in the workflow configuration form. The query is defined under the AOTQueries node, and it is required for all workflows. |
Workflow document class | References the workflow document query and any calculated fields to be made available when constructing conditions. This X++ class is created under the AOTClasses node. It is required because workflow templates and elements must bind to a workflow document class. For information about derived data, see the "Key Workflow Concepts" section earlier in this chapter. |
SubmitToWorkflow class | This X++ class is the menu item class for the SubmitToWorkflow menu item that displays the Submit To Workflow dialog box in the Dynamics AX 2009 user interface. The Submit To Workflow dialog box allows the user to enter comments associated with the submission. The SubmitToWorkflow class then activates the workflow. If state is being managed in the record that has been submitted to workflow, this class can be used to update the state of the record. This class is created under the AOTClasses node. |
State model | A defined set of states and state transitions (supported changes from one state to another) used to track the status of workflow document records during their life cycle. For example, a document can have the following states: Not Submitted, Submitted, ChangeRequested, or Approved. There is currently no state model infrastructure in Dynamics AX, so you have to implement any state model that is required. For more information, see the "State Model" section following this table. |
Event handlers | Event handler code consists of business logic that is written in X++ and then referenced in the workflow template, the approval element, approval outcomes, the task element, and task outcomes. If a workflow document has an associated state model, you must write event handler code to transact workflow document records through the state model when being processed by using workflow. Event handler X++ code is created under the AOTClasses node. |
Action and display menu items | For information about menu items, see the "Key Workflow Concepts" section earlier in this chapter. Both types of menu item are created under the AOTMenu Items or AOTWebWeb Menu Items node. For more information about the menu items used in the workflow infrastructure, see: |
Custom workflow providers | If the functionality of the workflow providers shipped with Dynamics AX 2009 isn’t adequate for a given set of requirements, you can develop your own workflow provider. Custom workflow provider X++ classes are created under the AOTClasses node and then referenced in one or more workflow elements. For more information about workflow providers, including where they are used, see http://msdn.microsoft.com/en-us/library/cc519521.aspx. |
canSubmitToWorkflow method | This method is required on each Dynamics AX 2009 client form that is enabled for workflow, and it is used to inform the workflow common controls that the record in the form is ready to be submitted to the workflow. |
A state model defines a set of states and the transitions that are permitted between the different states for a given record type, along with an initial state and a final state. The reason state models exist is to provide a very prescriptive life cycle for whatever data they are associated to. 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 has been 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 state on a record is to use a single field on the record to store the current state, but you have to determine what approach makes the most sense. You would then create a static X++ class that implements the state transition business logic. Conceptually, you can think of this class as the StateManager class. All the 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 the beginning or conclusion of a workflow element. This is why all workflow tasks and workflow approvals have EventHandlers that can be used to invoke the StateManager class. Figure 9-9 shows the dependency chain between an event handler and the workflow document state.
After you decide to enable a workflow for a table in Dynamics AX 2009, and that the table has state that must be managed, you must refactor all the business logic to respect the state model that you define to avoid getting 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 would typically be implemented in the update method on the table by calling the StateManager class; if it returns true, go ahead and do the update. If not, throw an exception and abort. Figure 9-10 shows a simple state model for a record.
In Figure 9-10, 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.
Workflow categories are used to associate a workflow template to a module. This association restricts the list of templates that are shown when you’re configuring a workflow for a particular module. To avoid showing a long list of all the workflow templates in the system, you group the templates by module using workflow categories. For example, if a user is in the Accounts Payable module, the user sees only the workflow templates bound to Accounts Payable. The mechanism behind this grouping is a simple metadata property on the workflow template 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 templates that can be associated to that module. Note that a workflow category can only be associated to 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 over the document that is being processed by workflow. In Dynamics AX 2009, these rules are referred to as conditions. A business user creates conditions in workflow when configuring the workflow. Conditions can be used, for example, to decide whether a purchase requisition should be approved automatically (without any human intervention). Figure 9-11 shows a simple condition defined in the workflow configuration form.
When a business user is configuring a condition by using the workflow configuration form, he or she needs to make sure the users have a way to select the fields from the workflow documents they want to use. On the surface, this configuration seems simple, but two requirements complicate the task. First, the user must be able to filter the available fields because not all the fields in a table might make sense to the business user. Second, it must be possible to use calculated fields (also referred to as 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 quite complex data structures, but most commonly the nested query is used to model a header-line pattern. At design time, when the business user is configuring a workflow, the AOT query is simply used by the condition editor to figure out which fields to display to the business user.
The workflow infrastructure uses a prescriptive pattern to support calculated fields 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.
Note
When the expression builder constructs the list of fields, it uses the labels of the table fields as the display name for the fields. The display name for calculated fields is defined by the extended data type label of the return types. For enums, this is defined by the enum element label.
Creating a workflow document class involves creating an X++ class that extends from WorkflowDocument. You must override getQueryName to return the name of the workflow document query. Figure 9-12 shows 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 you can see in Figure 9-13.
The workflow display menu items enable users to navigate directly to the Dynamics AX 2009 client form (or Enterprise Portal Web page) upon 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 Dynamics AX 2009 are always explicitly activated; either a user does something in the Dynamics AX 2009 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 approach to activation 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 provided Microsoft an opportunity to standardize the way users interact with workflow in both the Dynamics AX 2009 client and Enterprise Portal, including activating a workflow, and this resulted in the development of workflow common controls. The workflow common controls include the yellow workflow message bar (highlighted in Figure 9-14) and the workflow action button, labeled Submit.
The workflow common controls appear on the purchase requisition form because it has been enabled for workflow. To enable workflow in a form, you must set the WorkflowEnabled property on the form to Yes in the Properties tab of the Design dialog box, which is shown in Figure 9-15. You must also set the WorkflowDataSource 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.
If workflow has been enabled in a form, the workflow common controls automatically appear in three cases:
When the currently selected document can be submitted to workflow (the canSubmitToWorkflow form method returns true).
When the current user is the originator of a workflow that has acted on the currently selected document.
When the current user has been assigned to a work item on which he or she must take an action. The workflow common control uses the algorithm shown in Figure 9-16 to decide which workflow configuration to use.
After a workflow configuration has been identified, the workflow template is also known because there is a one-to-one relationship between a workflow configuration and a workflow template. When the workflow template is known, it’s easy for the workflow common controls to obtain the SubmitToWorkflow action menu item. This action menu item is then dynamically added to the form, together with the yellow workflow message bar.
If you look at the SubmitToWorkflow action menu item for the PurchReqApproval workflow template, you 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.
In Figure 9-17, notice how the Workflow::activatefromWorkflowTemplate method is used. You can use two additional APIs to activate workflows: Workflow::activatefromWorkflowConfiguration and Workflow::activateFromWorkflowSequenceNumber.
For information about how to use these APIs, see the Dynamics AX 2009 developer documentation on MSDN: http://msdn.microsoft.com/en-us/library/cc642844.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 forms, canSubmitToWorkflow, addresses this requirement. The canSubmitToWorkflow method returns a Boolean. 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, and if it returns false, the Submit button is disabled. Typically, you should update the state of the document after invoking the workflow activation API so that you can correctly denote when a document has or has not been submitted to workflow. (In Figure 9-17, the purchase requisition is transitioned to the submitted state.)