Workflow Events Overview

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

Workflow event handlers in Microsoft Dynamics AX enable you to run application-specific business logic at key points during workflow execution. Workflow events are implemented at the workflow level and the workflow element level. You can insert business logic at the following events in the workflow.

You can subscribe to workflow or workflow element level events by creating an X++ class that implements the appropriate workflow event handler interface. Then you can set the event handler property on the workflow type, approval, outcome, task, and automated task to point to that implementation.

The following sections explain the different types of event handlers and guidelines for using them throughout your workflow.

Workflow Level Event Handlers

At the workflow level, event handlers are provided for the workflow started, completed, canceled, and configuration data change events. For example, an event handler could transition a workflow that is canceled by the user from PendingApproval to NotSubmitted. Typically, the event handler stubs for workflow-level events are created by the Workflow wizard when you create a new workflow type. The following table lists the workflow-level events.

We recommend that you implement multiple event handler interfaces in a single class to reduce the number of classes shown in the Application Object Tree (AOT). For example, the following workflow event handler code example implements the Started, Canceled, and Completed event handlers in one class.

    public class WorkflowEventHandler implements
        WorkflowStartedEventHandler,
        WorkflowCanceledEventHandler,
        WorkflowCompletedEventHandler
    {
    }
    public void started(WorkflowEventArgs _workflowEventArgs)
    {
        // ToDo Insert code for the workflow started eventhandler;
    }
     
    public void canceled(WorkflowEventArgs _workflowEventArgs)
    {
        // ToDo Insert code for the workflow canceled eventhandler;
    }
     
    public void completed(WorkflowEventArgs _workflowEventArgs)
    {
        // ToDo Insert code for the workflow completed eventhandler;
    }

Element Level Event Handlers

Task, automated task, and approval event handlers are implemented at the workflow element level. Typically, the event handler stubs for element-level events are created by the Workflow wizard when you create a new workflow approval or workflow task. Event handlers are provided for the started, execution, canceled, approved, denied, rejected, request change, completed, and returned events. The following table lists the element-level events.

For tasks, you might only implement some of these event handlers. For example, the started event handler can be used to transition the workflow document state from NotSubmitted to Submitted.

For approvals, you should implement all of the event handlers and use them to transition the state of the business document. For more information, see Workflow Approval State Transitions.

We recommend that you implement multiple event handler interfaces in a single class to reduce the number of classes shown in the AOT. For example, the following approval event handler code example implements the Started, Completed, ChangeRequested, Returned, and Canceled event handlers in one class.

    Public class ApprovalEventHandler implements
        WorkflowElementStartedEventHandler,
        WorkflowElementCompletedEventhandler,
        WorkflowElementChangeRequestedEventHandler,
        WorkflowElementReturnedEventHandler,
        WorkflowElementCanceledEventHandler
    {
    }
    public void started(WorkflowElementEventArgs _workflowElementEventArgs)
    {
        // ToDo Insert code for the approval started eventhandler;
    }
     
    public void completed(WorkflowElementEventArgs _workflowElementEventArgs)
    {
        // ToDo Insert code for the approval completed eventhandler;
    }
     
    public void changeRequested(WorkflowElementEventArgs _workflowElementEventArgs)
    {
        // ToDo Insert code for the approval changeRequested eventhandler;
    }
    public void returned(WorkflowElementEventArgs _workflowElementEventArgs)
    {
        // ToDo Insert code for the approval returned eventhandler;
    }
     
    public void canceled(WorkflowElementEventArgs _workflowElementEventArgs)
    {
        // ToDo Insert code for the approval canceled eventhandler;
    }

Implementing Event Handlers

When the workflow infrastructure calls the event handlers at the workflow and the workflow element level, it passes WorkflowEventArgs or WorkflowElementEventArgs that contains the workflow context. The following example shows the workflow context for the WorkflowElementEventArgs.

class WorkflowElementEventArgs
    {
        WorkflowContext workflowContext;
    }
    public WorkflowContext parmWorkflowContext(
        WorkflowContext _workflowContext = workflowContext)
    {
        workflowContext = _workflowContext;
        return workflowContext;
    }

The workflow context consists of the following:

The following code example returns the record ID workflow context for a workflow element.

void started(WorkflowElementEventArgs _workflowElementEventArgs)
    {
        WorkflowContext workflowContext;
        ;
        workflowContext = _workflowElementEventArgs.parmWorkflowContext();
        // ToDo <Insert code for the event> (workflowContext.parmRecId());
    }

See also

Workflow Approval State Transitions

How to: Create a Workflow Event Handler

How to: Create a Workflow Task or Approval Event Handler

Announcements: New book: "Inside Microsoft Dynamics AX 2012 R3" now available. Get your copy at the MS Press Store.