{"title":"The PromptDialog page type","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-page-type-promptdialog/","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-promptdialog, 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-promptdialog","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":"The PromptDialog page type allows you to integrate copilot capabilities into your custom scenarios.","date":"2026-10-02","meta":{"topic":"overview"},"outline":[{"level":2,"title":"Snippet support","slug":"snippet-support","at":684,"chars":257},{"level":2,"title":"Properties of the PromptDialog page type","slug":"properties-of-the-promptdialog-page-type","at":941,"chars":1380},{"level":2,"title":"Areas of the PromptDialog page type","slug":"areas-of-the-promptdialog-page-type","at":2321,"chars":2160},{"level":3,"title":"Actions in the PromptDialog page","slug":"actions-in-the-promptdialog-page","at":2997,"chars":1484},{"level":2,"title":"Example","slug":"example","at":4481,"chars":10723},{"level":2,"title":"Nudging users with prompt actions","slug":"nudging-users-with-prompt-actions","at":15204,"chars":387},{"level":2,"title":"Related information","slug":"related-information","at":15591,"chars":488}],"text":"The PromptDialog page type is a specialized page type introduced in Business Central runtime 12.1. It enables developers to integrate generative AI capabilities into their custom scenarios, providing a seamless Copilot experience with signature visuals and built-in safety controls. This page type is designed to facilitate user interaction with AI-driven features, offering structured input and output areas, predefined prompt guides, and system actions tailored for Copilot functionality. In this article, you'll learn about the properties, layout areas, actions, and implementation details of the PromptDialog page type, along with a comprehensive example to help you get started.\n## Snippet support\nType the shortcut tpage and then choose the Page of type Prompt Dialog, which creates the basic layout for a PromptDialog page object when using the AL Language extension for Microsoft Dynamics 365 Business Central in Visual Studio Code.\n## Properties of the PromptDialog page type\nThe PromptDialog page type has some specific properties that characterize the dialog and must be set for this specific experience.\nProperty|Description\nPageType|The PageType property must be set to PromptDialog for this specific page type.\nPromptMode|The PromptMode property value is by default Prompt, which is the starting prompt mode. The PromptMode property can be changed at runtime. The other options are; <br> - Generate, which triggers generating the output of the copilot interaction, and <br>- Content, which shows the output of the copilot interaction.<br> You can programmatically set this property by setting the variable CurrPage.PromptMode before the page is opened.\nIsPreview|The IsPreview property adds a specific note in the UI to indicate that the feature is in preview. It's by default set to false.\nImage|To identify and ensure consistency in the UI for a generative AI experience, the Image property for the action invoking it, should be set to Sparkle. If there are multiple copilot options to choose from in the UI, the Image property can be set to `Image = SparkleFilled;` to make a specific action more prominent. To view a list of images, see Available icons<https://aka.ms/bcicons>.\nTo find links to the properties related to the PromptDialog page type, see the #related-information section in this article.\n## Areas of the PromptDialog page type\nThe PromptDialog page type has the following layout area types that characterize the dialog. To enable the full copilot experience, you must use the Prompt, Content, and PromptOptions areas. The page must have a `area(Prompt)` with one or more controls that accept user input to have the PromptDialog page start with a prompt.)\nArea|Description\nPrompt|The Prompt area is the input to copilot, and accepts any control, except repeater controls.\nContent|The Content area is the output of copilot, and accepts any control, except repeater controls.\nPromptOptions|The PromptOptions area is the input options, and only accepts option fields.\n### Actions in the PromptDialog page\nUnlike other page types, PromptDialog pages can only specify two action areas; SystemActions and PromptGuide. The SystemActions area defines the Copilot experience with options for generating and accepting generated content. The PromptGuide adds help to the user by providing predefined text prompt \"guides\" that users can select to use as input to generate content, rather than having to write that up themselves. The PromptGuide menu is only rendered in the web client when the PromptMode of the PromptDialog page is set to Prompt.\nAction|Description\nSystemActions|The SystemActions area only allows you to define a fixed set of actions called system actions, which are only supported by this page type. These system actions are Generate, Regenerate, Attach, Ok and Cancel.\nPromptGuide|The PromptGuide action area represents a list of predefined text prompt \"guides\", which users can select to use as input to generate content, rather than creating their own prompt from scratch. The prompt guide menu is only rendered in the web client when the PromptMode of the PromptDialog page is set to Prompt.\nThe following illustration shows an example of how the PromptDialog page with the Prompt, Content, SystemActions, and PromptGuide areas is implemented in Business Central for the Analyze Bank Account Reconciliation prompt dialog. You identify the prompt guide by the ![Prompt guide icon that opens a prompt guide.] icon of a prompt dialog page.\n## Example\nThe following example describes a page, which is a PromptDialog page, set with the PromptDialog option. The `Extensible = false;` is a mandatory setting, to ensure that the page isn't extended so that customers can trust the AI experience implemented.\nUse the IsPreview property to indicate to your customers that you're using the feature in preview, and that the feature might change in the future as you gather feedback. The IsPreview property adds a specific note in the UI to indicate that the feature is in preview. It's by default set to false.\nThe page is divided into two main areas: Prompt and Content.\n In the Prompt area, the field ProjectDescriptionField is bound to the variable InputProjectDescription and is a multiline text field where the user can describe the project they want to create with Copilot.\n The Content area contains fields that display the job's short description, full details, and the customer's name. The CustomerNameField has two triggers: OnAssistEdit and OnValidate. The OnAssistEdit trigger is used to select a customer from the existing customer records. The OnValidate trigger is used to validate the customer name and number. There's also a part named ProposalDetails, which is used to display the structure of the job proposal.\nThe actions section defines actions that the user can perform on this page. There are several actions defined under the PromptGuide area, such as OrganizeCampaign, FurnishOffice, SetUpConferenceRooms, and OrganizeWorkshop. Each action sets the InputProjectDescription to a predefined text.\nThe SystemActions area contains system actions like Generate, OK, Cancel, and Regenerate. These actions generate the project structure, save the project, discard the project, and regenerate the project respectively.\nThe OnQueryClosePage trigger saves the job proposal when the page is closed with the OK action.\nThe RunGeneration procedure generates the job proposal based on the user's input. It uses the `Generate Job Proposal` codeunit to generate the proposal and updates the fields in the Content area with the generated data.\nThe FindCustomerNameAndNumber procedure finds a customer based on the input customer name. It sets a filter on the `Search Name` field of the Customer record and tries to find a customer that matches the input name. If a customer is found, it updates the CustomerName and CustomerNo variables with the customer's name and number.\n```al\npage 54320 \"Copilot Job Proposal\"\n{\n    PageType = PromptDialog;\n    Extensible = false;\n    Caption = 'Draft new project with Copilot';\n    DataCaptionExpression = InputProjectDescription;\n    IsPreview = true;\n\n    layout\n    {\n        // This is the input section that accepts user input to generate content\n\n        area(Prompt)\n        {\n            field(ProjectDescriptionField; InputProjectDescription)\n            {\n                ApplicationArea = All;\n                ShowCaption = false;\n                MultiLine = true;\n                InstructionalText = 'Describe the project you want to create with Copilot';\n            }\n        }\n\n        // This is the output section that displays the generated content\n\n        area(Content)\n        {\n            field(\"Job Short Description\"; JobDescription)\n            {\n                ApplicationArea = All;\n                Caption = 'Project Short Description';\n            }\n            field(\"Job Full Details\"; JobFullDescription)\n            {\n                ApplicationArea = All;\n                MultiLine = true;\n                Caption = 'Details';\n            }\n            field(CustomerNameField; CustomerName)\n            {\n                ApplicationArea = All;\n                Caption = 'Customer Name';\n                ShowMandatory = true;\n\n                trigger OnAssistEdit()\n                var\n                    Customer: Record Customer;\n                begin\n                    if not Customer.SelectCustomer(Customer) then\n                        Clear(Customer);\n\n                    CustomerName := Customer.Name;\n                    CustomerNo := Customer.\"No.\";\n                end;\n\n                trigger OnValidate()\n                begin\n                    FindCustomerNameAndNumber(CustomerName, false);\n                end;\n            }\n            part(ProposalDetails; \"Copilot Job Proposal Subpart\")\n            {\n                Caption = 'Job structure';\n                ShowFilter = false;\n                ApplicationArea = All;\n                Editable = true;\n                Enabled = true;\n            }\n        }\n    }\n    actions\n    {\n        // This is the prompt guide area which contains the predefined prompts that the user can select to use as input to generate content\n\n        area(PromptGuide)\n        {\n            action(OrganizeCampaign)\n            {\n                ApplicationArea = All;\n                Caption = 'Create a campaign';\n\n                trigger OnAction()\n                begin\n                    InputProjectDescription := 'Campaign on [social media] for [Customer] to [promote education].';\n                end;\n            }\n\n            // Group of actions\n\n            group(Furnishing)\n            {\n                action(FurnishOffice)\n                {\n                    ApplicationArea = All;\n                    Caption = 'Furnish an office';\n\n                    trigger OnAction()\n                    begin\n                        InputProjectDescription := '[Customer] needs to furnish [office] for [4 people].';\n                    end;\n                }\n\n                action(SetUpConferenceRooms)\n                {\n                    ApplicationArea = All;\n                    Caption = 'Set up work areas';\n\n                    trigger OnAction()\n                    begin\n                        InputProjectDescription := 'Design and set up [work areas] for [Customer].';\n                    end;\n                }\n            }\n\n            action(OrganizeWorkshop)\n            {\n                ApplicationArea = All;\n                Caption = 'Organize a workshop';\n\n                trigger OnAction()\n                begin\n                    InputProjectDescription := 'Organize a [workshop] for [Customer] about [sustainability].';\n                end;\n            }\n\n        }\n\n        // This is the system actions area which contains the options for generating and accepting generated content\n\n        area(SystemActions)\n        {\n            systemaction(Generate)\n            {\n                Caption = 'Generate';\n                ToolTip = 'Generate project structure with Dynamics 365 Copilot.';\n\n                trigger OnAction()\n                begin\n                    RunGeneration();\n                end;\n            }\n            systemaction(OK)\n            {\n                Caption = 'Keep it';\n                ToolTip = 'Save the Project proposed by Dynamics 365 Copilot.';\n            }\n            systemaction(Cancel)\n            {\n                Caption = 'Discard it';\n                ToolTip = 'Discard the Project proposed by Dynamics 365 Copilot.';\n            }\n            systemaction(Regenerate)\n            {\n                Caption = 'Regenerate';\n                ToolTip = 'Regenerate the Project proposed by Dynamics 365 Copilot.';\n\n                trigger OnAction()\n                begin\n                    RunGeneration();\n                end;\n            }\n        }\n    }\n\n    trigger OnQueryClosePage(CloseAction: Action): Boolean\n    var\n        SaveCopilotJobProposal: Codeunit \"Save Copilot Job Proposal\";\n    begin\n        if CloseAction = CloseAction::OK then\n            SaveCopilotJobProposal.Save(CustomerNo, CopilotJobProposal);\n    end;\n\n    // The code triggering the copilot interaction. This is where you call the Copilot API, and get the results back.\n\n    local procedure RunGeneration()\n    var\n        GenJobProposal: Codeunit \"Generate Job Proposal\";\n        InStr: InStream;\n        ProgressDialog: Dialog;\n        Attempts: Integer;\n    begin\n        ProgressDialog.Open(GeneratingTextDialogTxt);\n        GenJobProposal.SetUserPrompt(InputProjectDescription);\n\n        CopilotJobProposal.Reset();\n        CopilotJobProposal.DeleteAll();\n\n        for Attempts := 0 to 3 do\n            if GenJobProposal.Run() then begin\n                GenJobProposal.GetResult(CopilotJobProposal);\n\n                if not CopilotJobProposal.IsEmpty() then begin\n                    CopilotJobProposal.FindFirst();\n\n                    JobDescription := CopilotJobProposal.\"Job Short Description\";\n                    CopilotJobProposal.CalcFields(\"Job Full Description\");\n                    CopilotJobProposal.\"Job Full Description\".CreateInStream(InStr);\n                    InStr.ReadText(JobFullDescription);\n\n                    FindCustomerNameAndNumber(CopilotJobProposal.\"Job Customer Name\", true);\n\n                    CurrPage.ProposalDetails.Page.Load(CopilotJobProposal);\n                    exit;\n                end;\n            end;\n\n        if GetLastErrorText() = '' then\n            Error(SomethingWentWrongErr)\n        else\n            Error(SomethingWentWrongWithLatestErr, GetLastErrorText());\n    end;\n\n    local procedure FindCustomerNameAndNumber(InputCustomerName: Text; Silent: Boolean)\n    var\n        Customer: Record Customer;\n    begin\n        if InputCustomerName <> '' then begin\n            Customer.SetFilter(\"Search Name\", '%1', '*' + UpperCase(InputCustomerName) + '*');\n\n            if not Customer.FindFirst() then\n                if not Silent then\n                    Error(CustomerDoesNotExistErr);\n        end;\n\n        CustomerName := Customer.Name;\n        CustomerNo := Customer.\"No.\";\n    end;\n\n    var\n        GeneratingTextDialogTxt: Label 'Generating with Copilot...';\n        SomethingWentWrongErr: Label 'Something went wrong. Please try again.';\n        SomethingWentWrongWithLatestErr: Label 'Something went wrong. Please try again. The latest error is: %1';\n        CustomerDoesNotExistErr: Label 'Customer does not exist';\n        CustomerNo: Code[20];\n        CopilotJobProposal: Record \"Copilot Job Proposal\" temporary;\n        JobFullDescription: Text;\n        InputProjectDescription: Text;\n        JobDescription: Text[100];\n        CustomerName: Text[100];\n}\n```\nTo see the `Copilot Job Proposal` code example in a complete implementation, go to aka.ms/BCTech<https://github.com/microsoft/BCTech/blob/master/samples/AzureOpenAI/3-SuggestJob/DescribeJob/CopilotJobProposal.Page.al>. Learn more about building an AI capability in Build the copilot capability in AL<ai-build-capability-in-al>.\nLearn more about error handling in Error handling in prompt dialogs<devenv-page-prompt-error-handling>.\n## Nudging users with prompt actions\nWith the floating action bar, you can create prompt actions to promote AI capabilities in Business Central. A prompt action is a standard action that is rendered in a floating action bar on your pages, and it nudges users to use relevant Copilot built-in features. See Prompting using a floating action bar<devenv-page-prompting-floating-actionbar>.\n## Related information\ndevenv-page-types-and-layouts\ndevenv-page-object\nproperties/devenv-pagetype-property\nproperties/devenv-promptmode-property\nproperties/devenv-image-property\nproperties/devenv-ispreview-property\nproperties/devenv-sourcetable-property\nproperties/devenv-sourcetabletemporary-property\nproperties/devenv-extensible-property\nPrompting using a floating action bar<devenv-page-prompting-floating-actionbar>\nError handling in prompt dialogs<devenv-page-prompt-error-handling>"}