How to Navigate to and from Generative Pages using Client API in Model-Driven Apps/ Dynamics 365

If you are looking for any of the information below, the post should help you.

  1. “Generative Pages in Dynamics 365: Navigate to and from them using the Client API”
  2. “How to open a Generative Page as a dialog and return data back to your form”
  3. “Pass context in and get values back from Generative Pages using the Client API”
  4. “Navigating to and from Generative Pages using the Client API in Model-Driven Apps / Dynamics 365”

Hello everyone and welcome to my blog. Generative pages are one of the newest additions to model-driven apps, letting you build rich, AI-assisted custom pages without hand-coding every bit of the UI. But a page is only useful if you can get to it and get data back out of it. In today’s blog, let’s look at how to navigate to and from a generative page using the client API, including passing context in and returning a value back to your form.

Quick note before we dive in – if you are new to generative pages and want to understand what they are and how to build one in the first place, I would suggest starting with my post on what generative pages are and how to create one. Once you are comfortable with that, this post picks up right where it leaves off.

Everything here uses the familiar Xrm.Navigation.navigateTo method, so if you have ever opened a custom page from script, you will feel right at home.

First, grab your generative page ID

Every navigation call needs the id of the generative page you want to open. To find it:

  1. Open the model-driven app containing the generative page in the app designer.
  2. Select the generative page in the pages list.
  3. In the properties pane, copy the GUID shown in the Generative page field.

The scenario

Let’s make this concrete. Say we are on the Account form and we want a button that opens a generative “Account Selector” page as a dialog. The user picks an account on that page, and when they are done, the selected account should flow straight back into a lookup field on our form. That is the full round trip – navigate to the page with some context, and navigate back with a result. Let’s build it piece by piece.

Part 1: Navigating to a generative page

The simplest call opens the page inline as a full page. You pass a pageInput object with pageType set to “generative” and your page id, plus a navigationOptions object where target: 1 means open inline.

var pageInput = {
    pageType: "generative",
    pageId: "<genPageID>"
};

var navigationOptions = {
    target: 1   // 1 = open inline (full page)
};

Xrm.Navigation.navigateTo(pageInput, navigationOptions)
    .then(function () {
        // Called when the page opens
    })
    .catch(function (error) {
        // Handle error
    });

Now let’s level up to our scenario. We want to open the page as a centered dialog and pass in some context – the current account record, plus a custom data object with any extra values the page needs. Note the two ways of passing input: entityName and recordId for record context, and the free-form data object for custom key-value pairs.

function openAccountSelector(executionContext) {
    var formContext = executionContext.getFormContext();

    var pageInput = {
        pageType: "generative",
        pageId: "<genPageID>",
        entityName: "account",
        recordId: formContext.data.entity.getId().replace(/[{}]/g, ""),
        data: { view: "summary" }   // custom values your page expects
    };

    var navigationOptions = {
        target: 2,                        // 2 = dialog
        position: 1,                      // 1 = centered (use 2 for a side dialog)
        width: { value: 70, unit: "%" },
        height: { value: 80, unit: "%" },
        title: "Select an account"
    };

    Xrm.Navigation.navigateTo(pageInput, navigationOptions);
}

Important: passing entityName, recordId or data only works if the target generative page has been set up to accept those input parameters. I have linked the Microsoft doc on configuring input parameters at the bottom of this post.

Part 2: Navigating back and returning a value

Opening the page is only half the story. The real power is getting a value back. Inside the generative page, once the user makes their selection, you store the value you want to return using dataApi.setPageOutput() and then close the dialog with Xrm.Navigation.navigateBack().

// This runs INSIDE the generative page component
async function handleSelection(accountId, accountName) {
    // Store the value to hand back to the calling script
    dataApi.setPageOutput({
        action: "selected",
        accountId: accountId,
        accountName: accountName
    });

    // Close the dialog and return control to the caller
    const xrm = window.Xrm;
    await xrm.Navigation.navigateBack();
}

A small but important tip – inside a generative page’s React component, the Xrm object is not directly in scope, so you access it via window.Xrm (in TypeScript you will see this written as (window as any).Xrm). And always use navigateBack rather than fiddling with the browser URL or window.location.

Back on the calling side, we await the navigateTo promise. When the dialog closes, it resolves with an object whose returnValue property holds whatever you stashed with setPageOutput. Here is our complete form command handler that reads the result and drops the selected account into a lookup field:

async function openAccountSelector(executionContext) {
    var formContext = executionContext.getFormContext();

    var result = await Xrm.Navigation.navigateTo(
        {
            pageType: "generative",
            pageId: "<genPageID>"
        },
        {
            target: 2,
            position: 1,
            width: { value: 70, unit: "%" },
            height: { value: 80, unit: "%" },
            title: "Select an account"
        }
    );

    var output = result && result.returnValue;

    if (output && output.action === "selected") {
        var attribute = formContext.getAttribute("new_selectedaccountid");
        if (attribute) {
            attribute.setValue([{
                id: output.accountId,
                name: output.accountName,
                entityType: "account"
            }]);
        }
    }
}

Notice that returning a value does not automatically update your form – you have to apply it yourself, which is exactly what the setValue call above does. If your form logic needs to react immediately to the change, call attribute.fireOnChange() after setting the value.

Navigating from one generative page to another

You are not limited to going back to a form. From inside a generative page you can also open another generative page, again via window.Xrm:

const xrm = window.Xrm;
xrm.Navigation.navigateTo({
    pageType: "generative",
    pageId: targetPageId,
    entityName: "account",
    recordId: selectedRecordId,
    data: { view: "summary" }
});

A few things to keep in mind

  • This navigation method is supported only on the Unified Interface.
  • Input parameters (entityName, recordId, data) only flow through if the target page is configured to accept them.
  • Returning a value through the navigateTo promise works for dialogs, but not for app side panes. A side pane stays open independently of the calling script.
  • If the user closes the dialog with Cancel or the close button without setting an output, returnValue comes back as undefined – so always null-check it like we did above.
  • You can also open a generative page in a side pane using Xrm.App.sidePanes.createPane() – I covered the side panes API in a separate post if you want to combine the two.

Final thoughts

Generative pages are still very new, but the navigation story is already quite complete – you can open them inline, as centered or side dialogs, or in a side pane, pass in record and custom context, and cleanly return a value back to your form. That round trip is what turns a generative page from a nice standalone screen into a proper part of your business process. Give it a try on one of your forms and let me know how it goes.

For the complete set of examples and the parameter setup, refer to Microsoft’s documentation:

Hope this helped. You will also like the below posts.

Debajit Dutta


Discover more from Debajit's Power Apps & Dynamics 365 Blog

Subscribe to get the latest posts sent to your email.

Leave a Comment

Your email address will not be published. Required fields are marked *

Discover more from Debajit's Power Apps & Dynamics 365 Blog

Subscribe now to keep reading and get access to the full archive.

Continue reading