1.5 Activating the Workflow
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 7) 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 8. 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 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 10, 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 10, the purchase requisition is transitioned to the submitted state.)
Note
If the canSubmitToWorkflow
method hasn’t been overridden, the workflow common controls won’t
appear on the form, leaving a reserved space at the top of the form
where the controls would normally appear. |
