{"title":"The ConfigurationDialog page type (preview)","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-page-type-configuration-dialog/","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-page-type-configuration-dialog, 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-page-type-configuration-dialog","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 to use the `ConfigurationDialog` page type to create focused configuration dialogs for managing agent settings in Dynamics 365 Business Central.","date":"2026-05-03","meta":{"topic":"overview"},"outline":[{"level":1,"title":"The ConfigurationDialog page type (preview)","slug":"the-configurationdialog-page-type-preview","at":0,"chars":20399},{"level":2,"title":"Snippet support","slug":"snippet-support","at":1412,"chars":271},{"level":2,"title":"Properties of the ConfigurationDialog page type","slug":"properties-of-the-configurationdialog-page-type","at":1683,"chars":922},{"level":2,"title":"Layout areas of the ConfigurationDialog page type","slug":"layout-areas-of-the-configurationdialog-page-type","at":2605,"chars":3090},{"level":3,"title":"The AgentSetupPart","slug":"the-agentsetuppart","at":2803,"chars":387},{"level":3,"title":"Groups and fields","slug":"groups-and-fields","at":3190,"chars":327},{"level":3,"title":"Cards that have toggle controls","slug":"cards-that-have-toggle-controls","at":3517,"chars":2178},{"level":4,"title":"Add a toggle to a card","slug":"add-a-toggle-to-a-card","at":3714,"chars":1981},{"level":2,"title":"Actions in the ConfigurationDialog page","slug":"actions-in-the-configurationdialog-page","at":5695,"chars":500},{"level":3,"title":"System actions","slug":"system-actions","at":5843,"chars":352},{"level":2,"title":"Example","slug":"example","at":6195,"chars":11052},{"level":3,"title":"Understanding the example","slug":"understanding-the-example","at":13396,"chars":3851},{"level":4,"title":"Embedded parts","slug":"embedded-parts","at":13515,"chars":374},{"level":4,"title":"Cards with toggle controls","slug":"cards-with-toggle-controls","at":13889,"chars":1336},{"level":4,"title":"Assist-edit pattern for complex settings","slug":"assist-edit-pattern-for-complex-settings","at":15225,"chars":803},{"level":4,"title":"Temporary buffer records","slug":"temporary-buffer-records","at":16028,"chars":324},{"level":4,"title":"Change tracking and conditional enablement","slug":"change-tracking-and-conditional-enablement","at":16352,"chars":347},{"level":4,"title":"Validation and applying settings","slug":"validation-and-applying-settings","at":16699,"chars":548},{"level":2,"title":"Key features and best practices","slug":"key-features-and-best-practices","at":17247,"chars":2712},{"level":3,"title":"Assist-edit for complex settings","slug":"assist-edit-for-complex-settings","at":17282,"chars":850},{"level":4,"title":"Validation flow","slug":"validation-flow","at":17700,"chars":252},{"level":4,"title":"System actions","slug":"system-actions-1","at":17952,"chars":180},{"level":3,"title":"Temporary tables","slug":"temporary-tables","at":18132,"chars":617},{"level":3,"title":"Validation","slug":"validation","at":18749,"chars":351},{"level":3,"title":"System action enablement","slug":"system-action-enablement","at":19100,"chars":388},{"level":3,"title":"Instructional text","slug":"instructional-text","at":19488,"chars":471},{"level":2,"title":"Related information","slug":"related-information","at":19959,"chars":440}],"text":"# The ConfigurationDialog page type (preview)\n[This article is prerelease documentation and is subject to change.]\n> IMPORTANT\n > This is a preview feature. Preview features might have restricted functionality and are subject to supplemental terms of use<https://www.microsoft.com/en-us/business-applications/legal/supp-powerplatform-preview/>.\n > The AI development toolkit is available in sandbox environments only. The Agent SDK for AL is available in sandbox environments and, starting from version 28.1, also in production environments.\n > This article is primarily intended for product owners, domain experts, consultants, and developers who want to experiment with AI capabilities in Business Central.\nThe ConfigurationDialog page type is a specialized page type that enables developers to create focused configuration dialogs for setting up and managing application settings, preferences, and configurations for agents. This page type provides a streamlined user experience with a modal dialog interface, system actions for saving or canceling changes, and support for temporary data sources.\n> IMPORTANT\n> The ConfigurationDialog page type is intended specifically for agent development scenarios. Use this page type when building configuration interfaces for agents and AI-powered capabilities in Business Central. See Integrate with the Tasks AL API (preview)<../ai/ai-development-toolkit-tasks-api>.\n## Snippet support\nType the shortcut tpage and then choose the Page of type Configuration Dialog, which creates the basic layout for a ConfigurationDialog page object when using the AL Language extension for Microsoft Dynamics 365 Business Central in Visual Studio Code.\n## Properties of the ConfigurationDialog page type\nThe ConfigurationDialog page type has some specific properties that characterize the dialog.\nProperty|Description\nPageType|Must be set to ConfigurationDialog for this specific page type. See properties/devenv-pagetype-property.\nSourceTableTemporary|Must be set to true to use a temporary table as the data source, allowing you to collect settings before committing them to the database. See properties/devenv-sourcetabletemporary-property.\nExtensible|Must be set to false for this page type. See properties/devenv-extensible-property.\nInstructionalText|Provides guidance to users about what the configuration dialog is for and what they need to do. See properties/devenv-instructionaltext-property.\nRefreshOnActivate|When set to true, the page refreshes its data when it becomes active again after a user navigates away. See properties/devenv-refreshonactivate-property.\n## Layout areas of the ConfigurationDialog page type\nThe ConfigurationDialog page type uses the Content area, which provides space for fields, groups, and parts that organize configuration options.\n### The AgentSetupPart\nWithin the Content area, you can use the page part AgentSetupPart that encapsulates specific configuration functionality.\n```al\npart(AgentSetupPart; \"Agent Setup Part\")\n{\n    ApplicationArea = All;\n    UpdatePropagation = Both;\n}\n```\n> IMPORTANT\n> The AgentSetupPart must be used as the first element in the layout. And no other parts are accepted in this layout.\n### Groups and fields\nYou can organize fields into groups to structure related settings:\n Groups - Organize related fields together with captions and instructional text\n Fields - Individual configuration options with validation and assist-edit capabilities\n Nested groups - Create hierarchical organization of related settings\n### Cards that have toggle controls\nEach root-level group in the Content area represents a card in the configuration dialog. Cards can have a toggle control at the top by using a specific pattern:\n#### Add a toggle to a card\n1. Place a boolean field as the first field in the group.\n2. Set `ShowCaption = false` on that field.\n3. The group's caption appears at the top of the card with a toggle on the right side.\n```al\ngroup(MonitorIncomingCard)\n{\n    Caption = 'Monitor incoming information';\n    InstructionalText = 'The agent will read messages in these channels:';\n\n    // Boolean field as first child creates a toggle for the card\n    field(\"Monitor incoming inquiries\"; Rec.\"Incoming Monitoring\")\n    {\n        ShowCaption = false;\n        ToolTip = 'Specifies if the agent should monitor incoming inquiries.';\n    }\n\n    // Other fields in the card...\n}\n```\nSub-groups can also have toggles using the same pattern. Place a boolean field with `ShowCaption = false` as the first child of a nested group:\n```al\ngroup(MonitorIncomingCard)\n{\n    Caption = 'Monitor incoming information';\n\n    field(\"Monitor incoming inquiries\"; Rec.\"Incoming Monitoring\")\n    {\n        ShowCaption = false;\n    }\n\n    // Nested group with its own toggle\n    group(MailboxGroup)\n    {\n        Caption = 'Mailbox';\n\n        field(MailEnabled; Rec.\"Email Monitoring\")\n        {\n            ShowCaption = false;\n            ToolTip = 'Specifies if the agent should monitor incoming mail.';\n        }\n\n        field(Mailbox; MailboxName)\n        {\n            Caption = 'Account';\n            ToolTip = 'Specifies the email account that the agent monitors.';\n            Editable = false;\n            ShowMandatory = true;\n        }\n    }\n}\n```\nThis pattern creates a visual hierarchy:\n The outer card has a toggle controlling the entire \"Monitor incoming information\" feature\n The nested Mailbox group has its own toggle for email-specific monitoring\n Other fields within each group provide detailed configuration\n> TIP\n> Use InstructionalText on groups to provide helpful guidance. While it's not specific to ConfigurationDialog, it's useful for guiding users through card-based configuration.\n## Actions in the ConfigurationDialog page\nThe ConfigurationDialog page type primarily uses system actions to provide a consistent user experience.\n### System actions\nSystem actions in a ConfigurationDialog provide the primary interaction points for users to complete or cancel the configuration process. They are:\n OK - Saves the configuration and closes the dialog\n Cancel - Discards changes and closes the dialog\nThe triggers for these actions can't be defined as they're defined by the platform.\n## Example\nThe following example demonstrates a simplified configuration dialog for setting up an agent. It shows the key patterns of the ConfigurationDialog page type, including embedded parts, cards with toggles, drill-down fields for complex settings, and managing multiple buffer records.\n```al\npage 50100 \"Agent Configuration\"\n{\n    PageType = ConfigurationDialog;\n    Extensible = false;\n    ApplicationArea = All;\n    Caption = 'Configure agent';\n    InstructionalText = 'Configure which instructions the agent follows, its permissions, and how it appears to users.';\n    SourceTable = \"Agent Setup Record\";\n    SourceTableTemporary = true;\n    RefreshOnActivate = true;\n\n    layout\n    {\n        area(Content)\n        {\n            // Reusable part for agent preview/settings\n            part(AgentSetupPart; \"Agent Setup Part\")\n            {\n                ApplicationArea = All;\n                UpdatePropagation = Both;\n            }\n\n            // Basic agent information card\n            group(AgentDetails)\n            {\n                Caption = 'About the agent';\n\n                field(AgentName; AgentNameVar)\n                {\n                    Caption = 'Name';\n                    ToolTip = 'Specifies the unique name of the agent.';\n\n                    trigger OnValidate()\n                    begin\n                        IsUpdated := true;\n                        // Update the buffer and refresh the part\n                        AgentSetupBuffer.Validate(\"User Name\", AgentNameVar);\n                        AgentSetupBuffer.Modify(true);\n                        UpdateAgentSetupPart();\n                    end;\n                }\n\n                field(AgentDescription; Rec.Description)\n                {\n                    Caption = 'Description';\n                    MultiLine = true;\n                    ToolTip = 'Specifies the description of the agent.';\n\n                    trigger OnValidate()\n                    begin\n                        IsUpdated := true;\n                        // Notify the part about the change\n                        CurrPage.AgentSetupPart.Page.SetAgentSummary(Rec.Description);\n                        CurrPage.AgentSetupPart.Page.Update(false);\n                    end;\n                }\n\n                // Complex settings accessed via drill-down\n                field(Profile; ProfileDisplayName)\n                {\n                    Caption = 'Profile';\n                    ToolTip = 'Specifies the profile that is associated with the agent.';\n                    Editable = false;\n\n                    trigger OnAssistEdit()\n                    var\n                        AllProfile: Record \"All Profile\";\n                    begin\n                        if Page.RunModal(Page::\"Available Profiles\", AllProfile) = Action::LookupOK then begin\n                            TempUserSettings.\"Profile ID\" := AllProfile.\"Profile ID\";\n                            ProfileDisplayName := AllProfile.\"Profile ID\";\n                            IsUpdated := true;\n                        end;\n                    end;\n                }\n            }\n\n            // Card with toggle control\n            group(MonitorIncomingCard)\n            {\n                Caption = 'Monitor incoming information';\n                InstructionalText = 'The agent will read messages in these channels:';\n\n                // Boolean field as first child creates a toggle for the card\n                field(MonitorIncoming; Rec.\"Incoming Monitoring\")\n                {\n                    ShowCaption = false;\n                    ToolTip = 'Specifies if the agent should monitor incoming inquiries.';\n\n                    trigger OnValidate()\n                    begin\n                        IsUpdated := true;\n                    end;\n                }\n\n                // Nested group with its own toggle\n                group(MailboxGroup)\n                {\n                    Caption = 'Mailbox';\n\n                    field(MailEnabled; Rec.\"Email Monitoring\")\n                    {\n                        ShowCaption = false;\n                        ToolTip = 'Specifies if the agent should monitor incoming mail.';\n\n                        trigger OnValidate()\n                        begin\n                            IsUpdated := true;\n                        end;\n                    }\n\n                    field(Mailbox; MailboxName)\n                    {\n                        Caption = 'Account';\n                        ToolTip = 'Specifies the email account that the agent monitors.';\n                        Editable = false;\n                        ShowMandatory = true;\n\n                        trigger OnAssistEdit()\n                        begin\n                            // Open mailbox selection dialog\n                            if SelectMailbox(MailboxName) then\n                                IsUpdated := true;\n                        end;\n                    }\n                }\n            }\n        }\n    }\n\n    actions\n    {\n        area(SystemActions)\n        {\n            systemaction(OK)\n            {\n                Caption = 'Update';\n                ToolTip = 'Apply the changes to the agent setup.';\n                Enabled = IsUpdated;\n            }\n\n            systemaction(Cancel)\n            {\n                Caption = 'Cancel';\n                ToolTip = 'Discards the changes and closes the setup page.';\n            }\n        }\n    }\n\n    trigger OnOpenPage()\n    begin\n        if Rec.IsEmpty() then begin\n            Rec.Init();\n            Rec.Insert();\n        end;\n\n        // Initialize buffer records\n        AgentSetupBuffer.Init();\n        AgentSetupBuffer.Insert();\n\n        UpdateControls();\n    end;\n\n    trigger OnQueryClosePage(CloseAction: Action): Boolean\n    begin\n        if CloseAction = CloseAction::Cancel then\n            exit(true);\n\n        // Validate required fields\n        if AgentNameVar = '' then\n            Error('You must specify an agent name.');\n\n        if ProfileDisplayName = '' then\n            Error('You must select a profile.');\n\n        // Apply all settings\n        ApplySettings();\n        exit(true);\n    end;\n\n    local procedure UpdateControls()\n    begin\n        // Refresh the part with current buffer data\n        CurrPage.AgentSetupPart.Page.SetAgentSetupBuffer(AgentSetupBuffer);\n        CurrPage.AgentSetupPart.Page.Update(false);\n    end;\n\n    local procedure UpdateAgentSetupPart()\n    begin\n        CurrPage.AgentSetupPart.Page.SetAgentSetupBuffer(AgentSetupBuffer);\n        CurrPage.AgentSetupPart.Page.SetAgentSummary(Rec.Description);\n        CurrPage.Update(false);\n    end;\n\n    local procedure ApplySettings()\n    var\n        AgentSetup: Codeunit \"Agent Setup\";\n    begin\n        // Apply all collected settings to the database\n        AgentSetup.UpdateAgent(AgentSetupBuffer);\n        AgentSetup.SetProfile(AgentSetupBuffer.\"User Security ID\", TempUserSettings);\n    end;\n\n    var\n        AgentSetupBuffer: Record \"Agent Setup Buffer\" temporary;\n        TempUserSettings: Record \"User Settings\" temporary;\n        AgentNameVar: Text[50];\n        ProfileDisplayName: Text;\n        MailboxName: Text;\n        IsUpdated: Boolean;\n}\n```\n### Understanding the example\nThis example demonstrates the essential patterns of ConfigurationDialog for agent setup:\n#### Embedded parts\n```al\npart(AgentSetupPart; \"Agent Setup Part\")\n{\n    ApplicationArea = All;\n    UpdatePropagation = Both;\n}\n```\nThe page embeds a reusable part that provides consistent agent preview and configuration UI. The part is updated using:\n```al\nCurrPage.AgentSetupPart.Page.SetAgentSetupBuffer(AgentSetupBuffer);\nCurrPage.AgentSetupPart.Page.Update(false);\n```\n#### Cards with toggle controls\nStart typing group in the context of a ConfigurationDialog page, which creates the basic layout for a GroupToogle layout.\nThe example demonstrates how to create cards with toggle controls using a boolean field with `ShowCaption = false` as the first field:\n```al\ngroup(MonitorIncomingCard)\n{\n    Caption = 'Monitor incoming information';\n    InstructionalText = 'The agent will read messages in these channels:';\n\n    // Boolean field as first child creates a toggle\n    field(MonitorIncoming; Rec.\"Incoming Monitoring\")\n    {\n        ShowCaption = false;\n    }\n    // ... other fields\n}\n```\nThis pattern creates a card with:\n The group's caption displayed at the top (\"Monitor incoming information\")\n A toggle control on the right side of the card\n Instructional text below the caption\n The card's fields shown beneath\nNested groups can also have toggles:\n```al\ngroup(MailboxGroup)\n{\n    Caption = 'Mailbox';\n\n    field(MailEnabled; Rec.\"Email Monitoring\")\n    {\n        ShowCaption = false;  // Creates a toggle for this nested group\n    }\n\n    field(Mailbox; MailboxName)\n    {\n        Caption = 'Account';\n        // ... field configuration\n    }\n}\n```\nThis creates a visual hierarchy where users can switch on/off features at different levels, providing granular control over configuration options.\n#### Assist-edit pattern for complex settings\nInstead of crowding the main page with many fields, complex settings like profile selection use noneditable fields with OnAssistEdit triggers:\n```al\nfield(Profile; ProfileDisplayName)\n{\n    Editable = false;\n\n    trigger OnAssistEdit()\n    var\n        AllProfile: Record \"All Profile\";\n    begin\n        if Page.RunModal(Page::\"Available Profiles\", AllProfile) = Action::LookupOK then begin\n            TempUserSettings.\"Profile ID\" := AllProfile.\"Profile ID\";\n            ProfileDisplayName := AllProfile.\"Profile ID\";\n            IsUpdated := true;\n        end;\n    end;\n}\n```\nThis pattern:\n Keeps the main configuration page focused and uncluttered\n Opens specialized lookup pages for selection\n Returns to the main page after the user makes a selection\n#### Temporary buffer records\nThe page manages temporary records to collect settings before applying them:\n```al\nvar\n    AgentSetupBuffer: Record \"Agent Setup Buffer\" temporary;\n    TempUserSettings: Record \"User Settings\" temporary;\n```\nThis allows validation across all settings before committing changes to the database.\n#### Change tracking and conditional enablement\nThe IsUpdated variable tracks whether the user made any changes:\n```al\ntrigger OnValidate()\nbegin\n    IsUpdated := true;\n    // ... update logic\nend;\n```\nSystem actions can be conditionally enabled based on this state:\n```al\nsystemaction(OK)\n{\n    Caption = 'Update';\n    Enabled = IsUpdated;\n}\n```\n#### Validation and applying settings\nThe OnQueryClosePage trigger validates all required fields and applies settings only when the user confirms:\n```al\ntrigger OnQueryClosePage(CloseAction: Action): Boolean\nbegin\n    if CloseAction = CloseAction::Cancel then\n        exit(true);\n\n    // Validate required fields\n    if AgentNameVar = '' then\n        Error('You must specify an agent name.');\n\n    if ProfileDisplayName = '' then\n        Error('You must select a profile.');\n\n    // Apply all settings\n    ApplySettings();\n    exit(true);\nend;\n```\n## Key features and best practices\n### Assist-edit for complex settings\nUse noneditable fields with OnAssistEdit triggers to handle complex settings:\n```al\nfield(ComplexSetting; SettingLabel)\n{\n    Editable = false;\n\n    trigger OnAssistEdit()\n    begin\n        // Open specialized lookup or dialog\n    end;\n}\n```\nThis pattern keeps the main configuration page focused while providing access to detailed settings through lookups or specialized dialogs.\n#### Validation flow\n Field validation - OnValidate triggers update the IsValid state\n Page validation - OnQueryClosePage performs final validation before applying changes\n System action enablement - The OK button is enabled only when `IsValid = true`\n#### System actions\n```al\nsystemaction(OK)\n{\n    Caption = 'Create';\n    Enabled = IsValid;\n}\n```\nThe OK button is customized with a meaningful caption and conditional enablement.\n### Temporary tables\nUsing `SourceTableTemporary = true` is mandatory with ConfigurationDialog pages. You can manage temporary buffer records to organize settings:\n```al\nvar\n    AgentSetupBuffer: Record \"Agent Setup Buffer\" temporary;\n    TempUserSettings: Record \"User Settings\" temporary;\n```\nThis allows you to:\n Collect configuration settings without immediately affecting the database\n Validate all settings together before applying changes\n Manage related settings across multiple temporary tables\n Cancel the configuration without leaving partial data\n Provide a better user experience with immediate feedback\n### Validation\nConfiguration dialogs should validate user input at multiple points:\n Field-level validation - In OnValidate triggers for immediate feedback\n Page-level validation - In OnQueryClosePage before applying changes\n Cross-field and cross-buffer validation - In dedicated procedures that check relationships between fields and buffer records\n### System action enablement\nYou can control when system actions are enabled based on change tracking:\n```al\nvar\n    IsUpdated: Boolean;\n\ntrigger OnValidate()\nbegin\n    IsUpdated := true;\nend;\n\nsystemaction(OK)\n{\n    Caption = 'Update';\n    ToolTip = 'Apply the configuration changes.';\n    Enabled = IsUpdated;\n}\n```\nThis provides clear feedback to users about whether changes are made.\n### Instructional text\nUse InstructionalText at both page and group levels to guide users:\n Page-level instructional text explains the overall purpose\n Group-level instructional text provides context for related fields\nWriting clear and concise instructions improves usability. To guide users well, you can learn best practices for crafting effective instructional text. See Write effective instructions for an agent (preview)<../ai/ai-development-toolkit-instructions>.\n## Related information\nIntegrate with the Tasks AL API (preview)<../ai/ai-development-toolkit-tasks-api>\nAI development toolkit overview (preview)<../ai/ai-development-toolkit-overview>\ndevenv-page-types-and-layouts\ndevenv-page-object\nproperties/devenv-pagetype-property\nproperties/devenv-sourcetable-property\nproperties/devenv-sourcetabletemporary-property\nproperties/devenv-extensible-property\nproperties/devenv-instructionaltext-property"}