How to: Enable a State Model for a Workflow Document [AX 2012]

Workflow documents in a Microsoft Dynamics AX workflow must implement a state model to represent the state of a workflow, approval, or task for a workflow document in the application. For example, a workflow document in the NotSubmitted state can be changed to the Submitted state when a user clicks the Submit button. This section describes how to enable the state model for a workflow document by using a class or by creating a method on a table.

The following table contains recommended states. However, the needs of your application will determine what states are needed, validation type for state transitions, and how many states are needed. For more information, see Workflow Approval State Transitions post.

For the state of the	Use
Workflow document	NotSubmitted Submitted ChangeRequested Returned Completed

Typically, the workflow state should be persisted in the root table of your workflow document data source. To add workflow state to a table, create an enum in the BaseEnums node of the Application Object Tree (AOT) that contains the workflow states shown in the previous table. The first enum defined should be the NotSubmitted enum, and this will also be the default setting in the table. After the enum is defined, drag the enum to the Fields node of the workflow document data source table.

After a state model is defined, you can enable forms and lists to work with workflow. For more information, see How to: Enable a Form or List for Workflow post.

Note : Workflow state can be implemented in many ways. The following procedure shows one way of performing this task.

To create a state change manager class

1. In the AOT, expand the Classes node.

2. Right-click the Classes node, and then select New Class. A class group displays under the Classes node.

3. Right-click the new class, click Rename, and then enter a name for the class.

4. Right-click the new class and then click New Method. A method node named method1 displays under the Classes node.

5. Right-click method1 and then click Edit. Enter the following code for the started event method.

   X++

   public static void started(RecID _recID)
   {
       <insert method here>
   }
   

   
   
6. 
   

   Repeat steps 4 and 5 for the remaining states.

Example

The following code is part of the setWorkflowState on the PurchReqTable Table. This method sets the workflow state field in the table and updates the user interface with a user friendly status, and then updates the state in the database.

X++

static void setWorkflowState(RecId _purchReqRecId, PurchReqWorkflowState _purchReqWorkflowState)
{
    // Declare variables.
    PurchReqTable purchReqTable;

    ttsbegin;
 
    // Selects the record to be updated based on the recId and then
    // sets the workflow state. 
    purchReqTable = PurchReqTable::findRecId(_purchReqRecId, true);
    purchReqTable.State = _purchReqWorkflowState;

    // Based on the workflow state, the status in the user interface
    // is updated with a user friendly status.
    switch (_purchReqWorkflowState)
    {
        case PurchReqWorkflowState::Submitted:
            purchReqTable.Status = PurchReqStatus::Submitted;
            break;
        case PurchReqWorkflowState::NotSubmitted:
            purchReqTable.Status = PurchReqStatus::Draft;
            break;
        case PurchReqWorkflowState::Completed:
            purchReqTable.Status = PurchReqStatus::Completed;
            break;
        case PurchReqWorkflowState::Returned:
            purchReqTable.Status = PurchReqStatus::Rejected;
            break;
        case PurchReqWorkflowState::ChangeRequest:
            purchReqTable.Status = PurchReqStatus::ChangeRequested;
            break;
    }
 
    // Commits the state to the database. 
    purchReqTable.update();
 
    ttscommit;
}

Workflow Approval State Transitions [AX 2012]

Microsoft Dynamics AX workflow documents that are enabled for workflow approvals typically support at least five workflow states. The current workflow state of a workflow can be maintained in a table field associated with the workflow document. As the state of the document is changed, the state field in the table should be updated. This topic describes workflow approval states.

Workflow State

Workflow state determines what you can do with the workflow document as soon as it is available in the system. Workflow states are defined by developers and must be supported in queries and business logic for operations that are controlled by workflow. Workflow approvals typically use the following workflow states.

 

Workflow state	Use
NotSubmitted	The state of the document before it is submitted to workflow or if the workflow is canceled. This is the state of all documents before a workflow instance is instantiated for the document.
Submitted	The state of the document as soon as the workflow is activated and the document is submitted to workflow. This is a temporary state when the user activates a workflow, but the system has not yet processed the workflow for activation.
PendingApproval	The state of the document as soon as the approval starts and remains in this state until the approval is completed, returned for a change, or rejected.
ChangeRequested	The state of the document if a change is requested or the document is returned.
Approved	The state of the document when the approval is completed.

The following diagram illustrates a typical approval state transition model.

Here are some general guidelines for workflow state:

• Avoid creating your own workflow states unless you have a business justification for doing this.

• Consider refactoring existing approval states so that you can take advantage of the states listed here.