Walkthrough: Implementing New Workflow Events and Responses

  • Article

If a business scenario requires a workflow event or a workflow response that is not supported in a Microsoft Dynamics NAV solution, you must implement it by customizing the application code.

In the Workflow window, the workflow administrator creates a workflow by listing the involved steps on the lines. Each step consists of a workflow event, moderated by event conditions, and a workflow response, customized by response options. You define workflow steps by filling fields on workflow lines from fixed lists of event and response values representing scenarios that are supported by the application code. For more information, see How to: Create Workflows in Application Help.

The following procedure describes how to add a new workflow event and a new workflow response to the application code and then register the involved object relations, so that the new elements can be used in workflows. The workflow administrator can then select the new workflow event and response from the Workflow window to incorporate them in new or existing workflow steps.

Important

To ensure that custom workflow records are upgraded correctly, you must add new workflow events, workflow responses, and workflow table relations to dedicated extension points, as described in this procedure. During an upgrade to the next version, the libraries of workflow events, responses, and table relations are removed and then recreated with the latest content from Microsoft. By adding your custom workflow records using subscriptions to the Microsoft-provided extension points, you ensure that your custom record library gets recreated after an upgrade.

Note

This topic refers to two types of events:

  • Workflow Event: An occurrence in the application that users can select from the Workflow window to define workflow steps. For more information, see Workflow in Application Help.

  • Event: The declaration of the occurrence or change in the application. Workflow events typically subscribe to events. For more information, see Events in Microsoft Dynamics NAV.

The development work involved in creating a new workflow event and a related workflow response consists of the following tasks, as a minimum:

  1. Creating a workflow event

    1. Creating a workflow event code that identifies the workflow event

    2. Adding the workflow event code to the Workflow Event table

    3. Creating and publishing an event that the workflow event subscribes to

    4. Raising the event

    5. Subscribing to the event and implement the workflow event

  2. Creating a workflow response

    1. Creating a workflow response code that identifies the workflow response

    2. Adding the workflow response code to the Workflow Response table

    3. Implementing the workflow response

    4. Enabling that the workflow response can be executed

    5. Adding a new workflow response option

  3. Registering workflow event/response combinations needed for the new workflow response

  4. Registering workflow event hierarchies needed for the new workflow event

  5. Creating table relations between entities used when the new workflow event and response are used

  6. Adding a FactBox that shows how a record participates in a workflow

Note

Data and code samples in this procedure refer loosely to a workflow step of sending a notification when a purchase header is posted. However, the procedure alone does not result in a complete solution.

To follow similar steps in a data-driven demo script with screenshots, see the “Build Your Own Workflow Event” demo script, which is available on the Microsoft Dynamics NAV 2016 readiness landing page.

Creating a Workflow Event

Create a code to identify the workflow event, add the workflow event to the library, create an event that the workflow event subscribes to, raise the event, and then subscribe to the event and implement the workflow event.

To create a workflow event code that identifies the workflow event

  1. Create a new codeunit that will be used for new workflow events. Name it to reflect that it is used to identify the new workflow event, such as My Workflow Events. For more information, see How to: Create a Codeunit.

  2. Create a global function in the codeunit. Name the function to reflect that it is used to identify the workflow event, such as MyWorkflowEventCode. For more information, see How to: Add a Function to a Codeunit.

  3. Open the C/AL Locals window to add a local return value. For more information, see C/AL Locals.

  4. On the Return Value tab, fill the fields as described in the following table.

    Return Type Length

    Code

    128

To add the workflow event code to the Workflow Event table

  1. Create another function in the codeunit. Name it to reflect that it is used to add the workflow event to the library, such as AddMyWorkflowEventsToLibrary.

  2. In the Properties window, fill the fields as described in the following table.

    Property Value

    Event

    Subscriber

    EventPublisherObject

    Codeunit Workflow Event Handling

    EventFunction

    OnAddWorkflowEventsToLibrary

  3. Open the C/AL Locals window to add a local variable.

  4. On the Variables tab, fill the fields as described in the following table.

    Name DataType Subtype

    WorkflowEventHandling

    Codeunit

    Workflow Event Handling

  5. In the function, write code that handles the event, such as the following code.

    WorkflowEventHandling.AddEventToLibrary(MyWorkflowEventCode,DATABASE::”Purchase Header”,’A purchase header is posted.’,0,FALSE);

To create and publish an event that the workflow event subscribes to

  1. Create a function in the codeunit where you want to raise the event, such as the Purch.-Post codeunit. Name the function to reflect that it is used as the publisher event, such as OnAfterPostPurchaseHeader.

  2. In the Properties window, fill the fields as described in the following table.

    Property Value

    Event

    Publisher

    EventType

    Select the event type that is relevant for the workflow event, such as Integration. For more information, see Event Types.

  3. Open the C/AL Locals window to add a local parameter.

  4. On the Parameters tab, fill the fields as described in the following table.

    Name DataType Subtype

    Purchase Header

    Record

    Purchase Header

For more information, see Publishing Events.

To raise the event

  1. Go to the code in your solution where you want to raise the event, such as the Purch.-Post codeunit.

  2. In the function, write code that raises the event, such as the following code.

    OnAfterPostPurchaseHeader(PurchaseHeader);

For more information, see Raising Events.

To subscribe to the event and implement the workflow event

  1. Create another function in the codeunit where you created the identification code, MyWorkflowEventCode. Name the function to reflect that it is used to subscribe to and implement the workflow event, such as RunWorkflowOnAfterPostPurchaseHeader.

  2. In the Properties window, fill the fields as described in the following table.

    Property Value

    Event

    Subscriber

    EventPublisherObject

    Select the object that contains the definition of the added event, such as the Purch.-Post codeunit.

    EventFunction

    OnAfterPostPurchaseHeader

  3. Choose Yes to overwrite your local parameters with the event parameters.

  4. Open the C/AL Locals window to add a local variable.

  5. On the Variables tab, fill the fields as described in the following table.

    Name DataType Subtype

    WorkflowManagement

    Codeunit

    Workflow Management

  6. In the function, write code that handles the event, such as the following code.

    WorkflowManagement.HandleEvent(MyWorkflowEventCode,PurchaseHeader);

Another task that you can perform at this point is to specify which filter fields appear in the Event Conditions window. For more information, see Dynamic Request Page Entity.

For more information, see Subscribing to Events.

You have now created a new workflow event. Proceed to create a new workflow response that relates to the workflow event.

Creating a Workflow Response

Create a code to identify the workflow response, add the workflow response code to the library, implement the workflow response, and then enable that the workflow response can be executed.

To create a workflow response code that identifies the workflow response

  1. Create a new codeunit that will be used for the new workflow responses. Name it to reflect that it handles your new responses, such My Workflow Responses.

  2. Create a function in the codeunit. Name the function to reflect that it is used to identify the workflow response, such as MyWorkflowResponseCode.

  3. Open the C/AL Locals window to add a local return value.

  4. On the Return Value tab, fill the fields as described in the following table.

    Return Type Length

    Code

    128

To add the workflow response code to the Workflow Response table

  1. Create another function in the codeunit. Name it to reflect that it is used to add the workflow response to the library, such as AddMyWorkflowResponsesToLibrary.

  2. In the Properties window, fill the fields as described in the following table.

    Property Value

    Event

    Subscriber

    EventPublisherObject

    Codeunit Workflow Response Handling

    EventFunction

    OnAddWorkflowResponsesToLibrary

  3. Open the C/AL Locals window to add a local variable.

  4. On the Variables tab, fill the fields as described in the following table.

    Name DataType Subtype

    WorkflowResponseHandling

    Codeunit

    Workflow Response Handling

  5. In the function, write code that registers the response, such as the following code.

    WorkflowResponseHandling.AddResponseToLibrary(MyWorkflowResponseCode,DATABASE::"Purchase Header",'Send a notification.','GROUP 0')

    Note

    In the “To add a new workflow response option” procedure, you will change the GROUP value to, for example, 50000.

To implement the workflow response

  1. Create another function in the codeunit. Name it to reflect that it is used to implement the workflow response, such as MyWorkflowResponse.

  2. Open the C/AL Locals window to add a local parameter.

  3. On the Parameters tab, fill the fields as described in the following table.

    Name DataType Subtype

    Purchase Header

    Record

    Select the relevant record, such as Purchase Header table.

  4. In the function, write code that handles the response, such as the following code.

    CODEUNIT.RUN(CODEUNIT::"Purch.-Post",PurchaseHeader);

To enable that the workflow response can be executed

  1. Create another function in the codeunit. Name it to reflect that it is used to enable the new workflow response to be executed alongside existing workflow responses, such as ExecuteMyWorkflowResponses.

  2. In the Properties window, fill the fields as described in the following table.

    Property Value

    Event

    Subscriber

    EventPublisherObject

    Codeunit Workflow Response Handling

    EventFunction

    OnExecuteWorkflowResponse

  3. Choose Yes to overwrite your local parameters with the event parameters.

  4. In the function, write code that enables the response, such as the following code.

    IF WorkflowResponse.GET(ResponseWorkflowStepInstance."Function Name") THEN
  CASE WorkflowResponse."Function Name" OF
    MyWFResponseCode:
      BEGIN
        MyWorkflowResponse(Variant);
        ResponseExecuted := TRUE;
      END;
  END;

To add a new workflow response option

  1. Open table 1523, Workflow Step Argument, in design mode.

  2. Add a field that reflects your new response option, such as My New Response Option. For more information, see How to: Add Fields to a Table.

  3. Open page 1523, Workflow Response Options, in design mode.

  4. Add a group and a control for the new field.

  5. For the Visibility property of the group, enter, for example, "Response Option Group" = 'GROUP 50000'.

  6. Open the AddMyWorkflowResponsesToLibrary function.

  7. In the function code, change ‘GROUP 0’ to ‘GROUP 50000’.

  8. To make sure that the new workflow response is updated, delete the Send a notification. response from the Workflow Response table.

    To use the new option in the MyWorkflowResponse function, proceed to add a local parameter and a local variable.

  9. Open the C/AL Locals window to add a local parameter and a local variable.

  10. On the Parameters tab, fill the fields as described in the following table.

    Name DataType Subtype

    WorkflowStepInstance

    Record

    Workflow Step Instance

  11. On the Variables tab, fill the fields as described in the following table.

    Name DataType Subtype

    WorkflowStepArgument

    Record

    Workflow Step Argument

  12. In the function, write code that enables the response, such as the following code:

    IF WorkflowStepArgument.GET(WorkflowStepInstance.Argument) THEN;

    You now have access to your new field on the Workflow Step Argument table that you can use as a workflow response option.

  13. In the ExecuteMyWorkflowResponses function, make the following code change:

    Change from this code: MyWorkflowResponse(Variant);

    Change to this code: MyWorkflowResponse(Variant,ResponseWorkflowStepInstance);

You have now created the actual workflow event and response. Proceed to perform various tasks that enable them to be used in workflows.

Registering Workflow Event/Response Combinations Needed for the New Workflow Response

Add new workflow event/response combinations to the WF Event/Response Combination table so that they appear correctly in the Workflow Events and Workflow Responses windows.

To register workflow event/response combinations needed for the new workflow response

  1. Open the codeunit that you created in the “To create a workflow response” procedure, My Workflow Responses.

  2. Create another function in the codeunit. Name it to reflect that it is used to add the workflow event/response combinations to the WF Event/Response Combination table, such as AddMyWorkflowEventResponseCombinationsToLibrary.

  3. In the Properties window, fill the fields as described in the following table.

    Property Value

    Event

    Subscriber

    EventPublisherObject

    Codeunit Workflow Response Handling

    EventFunction

    OnAddWorkflowResponsePredecessorsToLibrary

  4. Choose Yes to overwrite your local parameters with the event parameters.

  5. Open the C/AL Locals window to add two local variables.

  6. On the Variables tab, fill the fields as described in the following table.

    Name DataType Subtype

    MyWorkflowEvents

    Codeunit

    My Workflow Events

    WorkflowResponseHandling

    Codeunit

    Workflow Response Handling

  7. In the function, write code that registers event/response combinations that you want to support in your application, using a CASE statement, such as the following code.

    CASE ResponseFunctionName OF
  MyWorkflowResponseCode:
    WorkflowResponseHandling.AddResponsePredecessor(MyWorkflowResponseCode,MyWorkflowEvents.MyWorkflowEventCode);
END;

You can also do this work from the user interface. For more information, see Workflow Event/Response Combinations.

Registering Workflow Event Hierarchies Needed for the New Workflow Event

Add new workflow event/event combinations to the WF Event/Response Combination table so that they workflow events appear in the correct hierarchy in the Workflow Events window.

To register workflow event hierarchies needed for the new workflow event

  1. Open the codeunit that you created in the “To create a workflow event” procedure, My Workflow Events.

  2. Create another function in the codeunit. Name it to reflect that it is used to add the workflow event hierarchies to the WF Event/Response Combination table, such as AddWorkflowEventHierarchiesToLibrary.

  3. In the Properties window, fill the fields as described in the following table.

    Property Value

    Event

    Subscriber

    EventPublisherObject

    Codeunit Workflow Event Handling

    EventFunction

    OnAddWorkflowEventPredecessorsToLibrary

  4. Choose Yes to overwrite your local parameters with the event parameters.

  5. Open the C/AL Locals window to add a local variable.

  6. On the Variables tab, fill the fields as described in the following table.

    Name DataType Subtype

    WorkflowEventHandling

    Codeunit

    Workflow Event Handling

  7. To make sure that the new workflow event is updated, delete the A purchase header is posted. event from the Workflow Event table.

  8. In the function, write code that registers event hierarchies that you want to support in your application, using a CASE statement, such as the following code.

    CASE EventFunctionName OF
  MyWorkflowEventCode:
    WorkflowEventHandling.AddEventPredecessor(MyWorkflowEventCode,WorkflowEventHandling.[your desired predecessor event code]);
END;

You can also do this work from the user interface. For more information, see Workflow Event Hierarchies.

Creating Table Relations Between Entities Used when the New Workflow Event and Response are Used

Workflows events can be executed on different types of records. To keep track of these, you must define relations between the involved records.

To create table relations between entities that are processed when the new workflow event and response are used in workflows

  1. Open the codeunit that you created in the “To create a workflow event” procedure, My Workflow Events.

  2. Create another function in the codeunit. Name it to reflect that it is used add workflow table relations in the Workflow - Table Relation table, such as AddWorkflowTableRelationsToLibrary.

  3. In the Properties window, fill the fields as described in the following table.

    Property Value

    Event

    Subscriber

    EventPublisherObject

    Codeunit Workflow Event Handling

    EventFunction

    OnAddWorkflowTableRelationsToLibrary

  4. Open the C/AL Locals window to add a local variable.

  5. On the Variables tab, fill the fields as described in the following table.

    Name DataType Subtype

    WorkflowSetup

    Codeunit

    Workflow Setup

  6. To make sure that the new workflow event is updated, delete the A purchase header is posted. event from the Workflow Event table.

  7. In the function, write code that registers table relations that you want to support in your application, such as the following code.

    WorkflowSetup.InsertTableRelation(DATABASE::”Purchase Header”,1,DATABASE::”Approval Entry”,2);

You can also do this work from the user interface. For more information, see Workflow - Table Relations.

Adding a FactBox that Shows How a Record Participates in a Workflow

Add a FactBox to relevant pages so that users can view when and how the new workflow event and response participate in workflows for records shown on the page.

To add a FactBox that shows how a record participates in a workflow

  1. Open, in design mode, the page from where users need to see related workflows that use the new workflow event and response.

  2. Add a FactBox. Name it WorkflowStatus. For more information, see How to: Add a FactBox to a Page.

  3. Open the C/AL Globals window to add a global variable.

  4. On the Variables tab, fill the fields as described in the following table.

    Name DataType Subtype

    ShowWorkflowStatus

    Boolean

  5. To make the FactBox visible, in the Properties window, fill the fields as described in the following table.

    Property Value

    Visible

    ShowWorkflowStatus

  6. On the page, add the following code to the OnAfterGetCurrentRecord function to make the FactBox find the workflow that relates to the record.

    ShowWorkflowStatus := CurrPage.WorkflowStatus.PAGE.SetFilterOnWorkflowRecord(RECORDID);

You have now enabled a new workflow scenario by implementing the required workflow event and response in the application code. The workflow administrator can now select the workflow event and workflow response from the Workflow window to define new or edit existing workflows. For more information, see How to: Create Workflows.

See Also

Tasks

How to: Create Workflows

Concepts

Workflow
Developer and IT Pro Help for Microsoft Dynamics NAV 2016

Other Resources

Workflow Event
Workflow Response
Events in Microsoft Dynamics NAV