{"title":"Walkthrough: Implementing New Workflow Events and Responses","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-walkthrough-workflow-events-responses/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-walkthrough-workflow-events-responses, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-walkthrough-workflow-events-responses","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how you can extend the native workflows by adding workflow events and responses in code to support additional business scenarios.","date":"2022-02-11","meta":{"topic":"article"},"outline":[{"level":1,"title":"Walkthrough: Implementing New Workflow Events and Responses","slug":"walkthrough-implementing-new-workflow-events-and-responses","at":0,"chars":20965},{"level":2,"title":"Workflow event","slug":"workflow-event","at":3457,"chars":4547},{"level":3,"title":"To create a workflow event code that identifies the workflow event","slug":"to-create-a-workflow-event-code-that-identifies-the-workflow-event","at":3775,"chars":925},{"level":3,"title":"To add the workflow event code to the Workflow Event table","slug":"to-add-the-workflow-event-code-to-the-workflow-event-table","at":4700,"chars":982},{"level":3,"title":"To publish an event that the workflow event subscribes to","slug":"to-publish-an-event-that-the-workflow-event-subscribes-to","at":5682,"chars":560},{"level":3,"title":"To raise the event","slug":"to-raise-the-event","at":6242,"chars":694},{"level":3,"title":"To subscribe to the event and implement the workflow event","slug":"to-subscribe-to-the-event-and-implement-the-workflow-event","at":6936,"chars":1068},{"level":2,"title":"Workflow response","slug":"workflow-response","at":8004,"chars":7401},{"level":3,"title":"To create a workflow response code that identifies the workflow response","slug":"to-create-a-workflow-response-code-that-identifies-the-workflow-response","at":8274,"chars":407},{"level":3,"title":"To add the workflow response code to the Workflow Response table","slug":"to-add-the-workflow-response-code-to-the-workflow-response-table","at":8681,"chars":2077},{"level":3,"title":"To implement the workflow response","slug":"to-implement-the-workflow-response","at":10758,"chars":546},{"level":3,"title":"To enable that the workflow response can be executed","slug":"to-enable-that-the-workflow-response-can-be-executed","at":11304,"chars":1244},{"level":3,"title":"To add a new workflow response option","slug":"to-add-a-new-workflow-response-option","at":12548,"chars":2857},{"level":2,"title":"Register workflow event/response combinations","slug":"register-workflow-eventresponse-combinations","at":15405,"chars":1671},{"level":3,"title":"To register workflow event/response combinations needed for the new workflow response","slug":"to-register-workflow-eventresponse-combinations-needed-for-the-new-workflow-response","at":15650,"chars":1426},{"level":2,"title":"Register workflow event hierarchies","slug":"register-workflow-event-hierarchies","at":17076,"chars":1632},{"level":3,"title":"To register workflow event hierarchies needed for the new workflow event","slug":"to-register-workflow-event-hierarchies-needed-for-the-new-workflow-event","at":17314,"chars":1394},{"level":2,"title":"Create table relations","slug":"create-table-relations","at":18708,"chars":1855},{"level":3,"title":"To create table relations between entities that are processed when the new workflow event and response are used in workflows","slug":"to-create-table-relations-between-entities-that-are-processed-when-the-new-workflow-event-and-response-are-used-in-workflows","at":19009,"chars":1554},{"level":2,"title":"Related information","slug":"related-information","at":20563,"chars":402}],"text":"# Walkthrough: Implementing New Workflow Events and Responses\nIf a business scenario requires a workflow event or a workflow response that is not supported in a Business Central solution, you must implement it by extending the application code.\nIn the Workflow page, 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. See /across-set-up-workflows in the business functionality content.\nThe following procedure describes how to add a new workflow event and a new workflow response and then register the involved object relations, so that the new elements can be used in workflows. You can then share your code as an app or a per-tenant extension, for example. The workflow administrator can then select the new workflow event and response from the Workflow page to incorporate them in new or existing workflow steps.\n> IMPORTANT\n> 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.\n> NOTE\n> This topic refers to two types of events:\n > Workflow event: An occurrence in the application that users in the client can select from the Workflow page to define workflow steps. See Workflows in Dynamics 365 Business Central</across-workflow> in the business functionality content.\n > Event: The declaration of the occurrence or change in the application. Workflow events typically subscribe to events. See devenv-events-in-al.\nThe development work involved in creating a new workflow event and a related workflow response consists of the following tasks, as a minimum:\n1. Create a workflow event\n 1. Create a workflow event code that identifies the workflow event\n 2. Add the workflow event code to the Workflow Event table\n 3. Create and publish an event that the workflow event subscribes to\n 4. Raise the event\n 5. Subscribe to the event and implement the workflow event\n2. Create a workflow response\n 1. Create a workflow response code that identifies the workflow response\n 2. Add the workflow response code to the Workflow Response table\n 3. Implement the workflow response\n 4. Enable that the workflow response can be executed\n 5. Add a new workflow response option\n3. Register workflow event/response combinations needed for the new workflow response\n4. Register workflow event hierarchies needed for the new workflow event\n5. Creating table relations between entities used when the new workflow event and response are used\n> NOTE\n> 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. The purpose of the walkthrough is simply to illustrate the process.\n## Workflow event\nIn this section, we'll 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.\nEach subsection takes you through the discrete steps.\n### To create a workflow event code that identifies the workflow event\n1. Create a new .al file, such as MyWorkflowEvents.codeunit.al, and add a 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 MyWorkflowEvents.\n2. Add a method in the codeunit. Optionally, use the shortcut tprocedure. Name the method to reflect that it is used to identify the workflow event, such as MyWorkflowEventCode, and make it take 128 characters of code as a parameter.\n> TIP\n> The terminology can be a bit confusing here. This method is not an AL event. It's a method that declares the workflow event, and it will subscribe to an AL event that, when triggered, will trigger the workflow event.\nYour MyWorkflowEvents.codeunit.al file now looks like this:\n```al\ncodeunit 50101 MyWorkflowEvents\n{\n    procedure MyWorkflowEventCode(): code[128]\n    begin\n    end;\n}\n```\n### To add the workflow event code to the Workflow Event table\n1. Create another method in the codeunit. Name it to reflect that it is used to add the workflow event to the library, such as AddMyWorkflowEventsToLibrary.\n This method will subscribe to the OnAddWorkflowEventsToLibrary method in the `Workflow Event Handling` codeunit in the base application, so you must set the attributes/devenv-eventsubscriber-attribute attribute, and you must add code that handles the event.\nThe following code illustrates the new method in the MyWorkflowEvents codeunit:\n```al\n    [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Event Handling\", 'OnAddWorkflowEventsToLibrary', '', true, true)]\n    procedure AddMyWorkflowEventsToLibrary()\n    var\n        WorkflowEventHandling: Codeunit \"Workflow Event Handling\";\n    begin\n        WorkflowEventHandling.AddEventToLibrary(MyWorkflowEventCode(), Database::\"Purchase Header\", 'My workflow event description', 0, false);\n    end;\n\n```\n### To publish an event that the workflow event subscribes to\n1. Create another codeunit, such as MyEvents.codeunit.al, and add a method that publishes your event. Name the method to reflect that it is used as the publisher event, such as OnAfterPostPurchaseHeader.\n ```al\n codeunit 50102 MyEvents\n {\n     [IntegrationEvent(false, false)]\n     procedure OnAfterPostPurchaseHeader(PurchaseHeader: Record \"Purchase Header\")\n     begin\n     end;\n }\n ```\n Select the event type that is relevant for the workflow event, such as Integration. See devenv-event-types.\n### To raise the event\n1. Create an object or an extension object to add the code that will raise the event that triggers the workflow event, such as the `Purch.-Post` codeunit.\n The following code raises the event by extending the `Purchase Order`page object in a new file, MyPurchOrder.PageExt.al.\n ```al\n pageextension 50100 WFW_PurchaseOrder extends \"Purchase Order\"\n  {\n      layout\n      {\n          modify(Status)\n          {\n              trigger OnBeforeValidate();\n              var\n                  MyEvents: Codeunit MyEvents;\n              begin\n                  MyEvents.OnAfterPostPurchaseHeader(Rec)\n              end;\n          }\n      }\n  }\n ```\n See devenv-raising-events.\n### To subscribe to the event and implement the workflow event\n1. Go back to the MyWorkflowEvents.codeunit.al file and add another method in the MyWorkflowEvents codeunit. Name the new method to reflect that it is used to subscribe to and implement the workflow event, such as RunWorkflowOnAfterPostPurchaseHeader.\nThe following code illustrates the new workflow event that subscribes to your previously created event:\n```al\n [EventSubscriber(ObjectType::Codeunit, Codeunit::MyEvents, 'OnAfterPostPurchaseHeader', '', true, true)]\n local procedure RunWorkflowOnAfterPostPurchaseHeader(var PurchaseHeader: Record \"Purchase Header\")\n var\n     WorkflowManagement: Codeunit \"Workflow Management\";\n begin\n     WorkflowManagement.HandleEvent(MyWorkflowEventCode, PurchaseHeader);\n end;\n```\nAnother task that you can perform at this point is to specify which filter fields appear in the Workflow Event Conditions page.\nSee devenv-subscribing-to-events.\nYou have now created a new workflow event. Next, we'll create a new workflow response that relates to the workflow event.\n## Workflow response\nCreate a new .al file, such as MyWorkflowResponses.codeunit.al, with 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.\n### To create a workflow response code that identifies the workflow response\n1. Add a new codeunit that will be used for the new workflow responses. Name it to reflect that it handles your new responses, such MyWorkflowResponses.\n2. Add a method in the codeunit. Name the method to reflect that it is used to identify the workflow response, such as MyWorkflowResponseCode with a return value of code (128).\n### To add the workflow response code to the Workflow Response table\n1. Add another method in the codeunit that will be the event subscriber. Name it to reflect that it is used to add the workflow response to the library, such as AddMyWorkflowResponsesToLibrary and set it to subscribe to the OnAddWorkflowResponsesToLibrary` method in the `Workflow Response Handling` codeunit.\n ```al\n  [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Event Handling\", 'OnAddWorkflowEventPredecessorsToLibrary', '', false, false)]\n  local procedure AddWorkflowEventHierarchiesToLibrary(EventFunctionName: Code[128])\n  begin\n  end;\n ```\n2. Add a local variable for the codeunit:\n ```al\n [...]\n var\n WorkflowResponseHandling: Codeunit \"Workflow Response Handling\";\n ```\n3. In the method, write code that registers the response, so that you end up with something like the following code.\n ```al\n  [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Response Handling\", 'OnAddWorkflowResponsesToLibrary', '', true, true)]\n  local procedure AddMyWorkflowResponsesToLibrary()\n  var\n      WorkflowResponseHandling: Codeunit \"Workflow Response Handling\";\n  begin\n      WorkflowResponseHandling.AddResponseToLibrary(MyWorkflowResponseCode, Database::\"Purchase Header\", 'Send a notification.', 'GROUP 0');\n      End\n  end;\n ```\n> NOTE\n> In the #to-add-a-new-workflow-response-option section, you will change the GROUP value to 50100. This way, you'll be able to see the workflow in action.\nThe codeunit now looks something like this:\n```al\ncodeunit 50103 MyWorkflowResponses\n{\n    procedure MyWorkflowResponseCode(): code[128]\n    begin\n    end;\n\n    [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Response Handling\", 'OnAddWorkflowResponsesToLibrary', '', true, true)]\n    local procedure AddMyWorkflowResponsesToLibrary()\n    var\n        WorkflowResponseHandling: Codeunit \"Workflow Response Handling\";\n    begin\n        WorkflowResponseHandling.AddResponseToLibrary(MyWorkflowResponseCode, Database::\"Purchase Header\", 'Send a notification.', 'GROUP 0');\n    end;\n}\n```\n### To implement the workflow response\n1. Create another method in the codeunit. Name it to reflect that it is used to implement the workflow response, such as MyWorkflowResponse, that takes a parameter based on the Purchase Header table.\n2. In the method, write code that handles the response, so that you end up with something like the following code.\n ```al\n procedure MyWorkflowResponse(PurchaseHeader: Record \"Purchase Header\")\n begin\n     Message('Status change on: %1 %2', PurchaseHeader.\"Document Type\", PurchaseHeader.\"No.\");\n end;\n ```\n### To enable that the workflow response can be executed\n1. Create another method in the codeunit that subscribes to the OnExecuteWorkflowResponse event on the `Workflow ResponseHandling`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.\n2. In the event subscriber method, write code that enables the response, so that you end up with something like the following code.\n ```al\n [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Response Handling\", 'OnExecuteWorkflowResponse', '', true, true)]\n procedure ExecuteMyWorkflowResponses(ResponseWorkflowStepInstance: Record \"Workflow Step Instance\"; var ResponseExecuted: Boolean; var Variant: Variant; xVariant: Variant)\n var\n     WorkflowResponse: record \"Workflow Response\";\n begin\n     if WorkflowResponse.GET(ResponseWorkflowStepInstance.\"Function Name\") then\n         case WorkflowResponse.\"Function Name\" of\n             MyWFResponseCode:\n                 BEGIN\n                     MyWorkflowResponse(Variant);\n                     ResponseExecuted := TRUE;\n                 END;\n         END;\n end;\n ```\nYou'll update this method in step 8 in the next section.\n### To add a new workflow response option\n1. Create a table extension object<devenv-table-ext-object> that extends table 1523, Workflow Step Argument, such as MyWorkflowStepArgument.TableExt.al.\n2. Add a field that reflects your new response option, such as My New Response Option.\n ```al\n tableextension 50100 WFW_WorkflowStepArgument extends \"Workflow Step Argument\"\n {\n     fields\n     {\n         field(50100; \"My New Response Option\"; Text[100])\n         {\n         }\n     }\n }\n ```\n3. Create a page extension object<devenv-page-ext-object> that extends page 1523, Workflow Response Options, such as MyworkflowStepArgument.PageExt.al.\n4. Add a group and a control for the new field.\n ```al\n pageextension 50101 WFW_WorkflowResponseOptions extends \"Workflow Response Options\"\n {\n     layout\n     {\n         addlast(content)\n         {\n             group(Group50100)\n             {\n                 Visible = Rec.\"Response Option Group\" = 'GROUP 50100';\n                 ShowCaption = false;\n\n                 field(MyNewResponseOption; Rec.\"My New Response Option\")\n                 {\n                     ApplicationArea = All;\n                 }\n             }\n         }\n     }\n }\n ```\n Here, the Visibility property of the group is set to `\"Response Option Group\" = 'GROUP 50100'`, but you can set it to another value.\n5. Go back to MyWorkflowResponses.codeunit.al and the ´AddMyWorkflowResponsesToLibrary` method.\n6. In the method code, change `'GROUP 0'` to `'GROUP 50100'`.\n ```al\n [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Response Handling\", 'OnAddWorkflowResponsesToLibrary', '', true, true)]\n local procedure AddMyWorkflowResponsesToLibrary()\n var\n     WorkflowResponseHandling: Codeunit \"Workflow Response Handling\";\n begin\n     WorkflowResponseHandling.AddResponseToLibrary(MyWorkflowResponseCode, Database::\"Purchase Header\", 'Send a notification.', 'GROUP 50100');\n end;\n ```\n7. To use the new option in the MyWorkflowResponse method, proceed to add a local parameter and a local variable and show a message as the response.\n ```al\n  local procedure MyWorkflowResponse(PurchaseHeader: Record \"Purchase Header\"; WorkflowStepInstance: Record \"Workflow Step Instance\")\n  var\n      WorkflowStepArgument: Record \"Workflow Step Argument\";\n  begin\n      if WorkflowStepArgument.Get(WorkflowStepInstance.Argument) then;\n\n      Message('Status change on: %1 %2.\\%3', PurchaseHeader.\"Document Type\", PurchaseHeader.\"No.\", WorkflowStepArgument.\"My New Response Option\")\n  end;\n ```\n8. In the ExecuteMyWorkflowResponses method, make the following code change:\n Change from this code: `MyWorkflowResponse(Variant);`\n Change to this code: `MyWorkflowResponse(Variant,ResponseWorkflowStepInstance);`\n You have now created the actual workflow event and response. Proceed to perform various tasks that enable them to be used in workflows.\n## Register workflow event/response combinations\nIn this section, you'll add new workflow event/response combinations to table 1509 WF Event/Response Combination so that they appear correctly in the Workflow Events and Workflow Responses pages.\n### To register workflow event/response combinations needed for the new workflow response\n1. Open the codeunit that you created in the #workflow-response section, `My Workflow Responses`.\n2. Create another method in the codeunit that subscribes to the OnAddWorkflowResponsePredecessorsToLibrary event on the `Workflow Response Handling` codeunit . Name it to reflect that it is used to add the workflow event/response combinations to table 1509 WF Event/Response Combination, such as AddMyWorkflowEventResponseCombinationsToLibrary.\n ```al\n [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Response Handling\", 'OnAddWorkflowResponsePredecessorsToLibrary', '', false, false)]\n local procedure AddMyworkflowEventOnAddWorkflowResponsePredecessorsToLibrary(ResponseFunctionName: Code[128])\n var\n     MyWorkflowEvents: Codeunit MyWorkflowEvents;\n     WorkflowResponseHandling: Codeunit \"Workflow Response Handling\";\n begin\n     Case ResponseFunctionName of\n         MyWorkflowResponseCode():\n             WorkflowResponseHandling.AddResponsePredecessor(MyWorkflowResponseCode(), MyWorkflowEvents.MyWorkflowEventCode());\n     End\n end;\n ```\n In the method, write code that registers event/response combinations that you want to support in your application, using a CASE statement, such as the code in the example above.\n You can also do this work from the user interface on page 1507 Workflow-Event-Response-Combinations.\n## Register workflow event hierarchies\nIn this section, you'll add new workflow event/event combinations to table 1509 WF Event/Response Combination so that the workflow events appear in the correct hierarchy in the Workflow Events page.\n### To register workflow event hierarchies needed for the new workflow event\n1. Go back to the MyWorkflowEvents.codeunit.al file with the codeunit that you created in the #to-create-a-workflow-event-code-that-identifies-the-workflow-event section, `My Workflow Events`.\n2. Create another method in the codeunit that subscribes to the OnAddWorkflowEventPredecessorsToLibrary event on the `Workflow Event Handling` codeunit. Name it to reflect that it is used to add the workflow event hierarchies to table 1509 WF Event/Response Combination, such as AddWorkflowEventHierarchiesToLibrary.\n ```al\n [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Event Handling\", 'OnAddWorkflowEventPredecessorsToLibrary', '', false, false)]\n local procedure AddWorkflowEventHierarchiesToLibrary(EventFunctionName: Code[128])\n var\n     WorkflowEventHandling: codeunit \"Workflow Event Handling\";\n begin\n     Case EventFunctionName of\n         MyWorkflowEventCode():\n             //WorkflowEventHandling.AddEventPredecessor(MyWorkflowEventCode(), WorkflowEventHandling./*[Add your predecessor event code]*/);\n             ;\n     End\n end;\n ```\n In the method, write code that registers event hierarchies that you want to support in your application, using a CASE statement, such as the code in the example above.\n You can also do this work from the user interface on page 1506 Workflow-Event-Hierarchies.\n## Create table relations\nWorkflows events can be executed on different types of records. To keep track of these, you must define relations between the involved records. In this section, you'll create relationships between the entities that are used when the new workflow event and response are used.\n### To create table relations between entities that are processed when the new workflow event and response are used in workflows\n1. Got back to the MyWorkflowEvents.codeunit.al file with the codeunit that you created in the #to-create-a-workflow-event-code-that-identifies-the-workflow-event section, `My Workflow Events`.\n2. Create another method in the codeunit that subscribes to the OnAddWorkflowTableRelationsToLibrary event on the `Workflow Event Handling` codeunit. Name it to reflect that it is used add workflow table relations in table 1505 Workflow Table Relation, such as AddWorkflowTableRelationsToLibrary.\n ```al\n [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Workflow Event Handling\", 'OnAddWorkflowTableRelationsToLibrary', '', false, false)]\n local procedure AddWorkflowTableRelationsToLibrary()\n var\n     WorkflowSetup: Codeunit \"Workflow Setup\";\n begin\n     WorkflowSetup.InsertTableRelation(Database::\"Purchase Header\", 1, Database::\"Approval Entry\", 2);\n end;\n ```\n In the method, write code that registers table relations that you want to support in your application, such as the example above.\n You can also do this work from the user interface on page 1509 Workflow Table-Relations.\nYou 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 page to define new or edit existing workflows. See /across-set-up-workflows in the business functionality content.\n## Related information\nWorkflows in Dynamics 365 Business Central</across-workflow>\n/across-set-up-workflows\ndevenv-events-example\ndevenv-events-in-al\nPage Extension Object<devenv-page-ext-object>\nTable Extension Object<devenv-table-ext-object>\ndevenv-codeunit-object\ndevenv-table-object\nGet Started with AL<devenv-get-started>\nDevelopment and Administration for Dynamics 365 Business Central<../index>"}