navigateTo (Client API reference)

Navigates to the specified entity list, entity record, or HTML web resource.

Note

This method is supported only on Unified Interface.

Syntax

Xrm.Navigation.navigateTo(pageInput,navigationOptions).then(successCallback,errorCallback);

Parameters

Name Type Required Description
pageInput Object Yes

Input about the page to navigate to. The object definition changes depending on the type of page to navigate to: entity list, entity record, dashboard, or HTML web resource.

----------------------------------------------------------------

entity list

The object contains the following attributes:

  • pageType: String. Specify "entitylist".
  • entityName: String. The logical name of the entity to load in the list control.
  • viewId: (Optional) String. The ID of the view to load. If you don't specify it, navigates to the default main view for the entity.
  • viewType: (Optional) String. Type of view to load. Specify "savedquery" or "userquery".

----------------------------------------------------------------

entity record

The object contains the following attributes:

  • pageType: String. Specify "entityrecord".
  • entityName: String. Logical name of the entity to display the form for.
  • entityId: (Optional) String. ID of the entity record to display the form for. If you don't specify this value, the form will be opened in create mode.
  • createFromEntity: (Optional) Lookup. Designates a record that will provide default values based on mapped attribute values. The lookup object has the following String properties: entityType, id, and name (optional).
  • data: (Optional) Object. A dictionary object that passes extra parameters to the form. Invalid parameters will cause an error.
    For information about passing parameters to a form, see Set field values using parameters passed to a form and Configure a form to accept custom querystring parameters.
  • formId: (Optional) String. ID of the form instance to be displayed.
  • isCrossEntityNavigate: (Optional) Boolean. Indicates whether the form is navigated to from a different entity using cross-entity business process flow.
  • isOfflineSyncError: (Optional) Boolean. Indicates whether there are any offline sync errors.
  • processId: (Optional) String. ID of the business process to be displayed on the form.
  • processInstanceId: (Optional) String. ID of the business process instance to be displayed on the form.
  • relationship: (Optional) Object. Define a relationship object to display the related records on the form. The object has the following attributes.              
    NameTypeDescription
    attributeName String Name of the attribute used for relationship.
    name String Name of the relationship.
    navigationPropertyName String Name of the navigation property for this relationship.
    relationshipType Number Relationship type. Specify one of the following values:
    • 0:OneToMany
    • 1:ManyToMany
    roleType Number Role type in relationship. Specify one of the following values:
    • 1:Referencing
    • 2:AssociationEntity
  • selectedStageId: (Optional) String. ID of the selected stage in business process instance.

----------------------------------------------------------------

HTML web resource

The object contains the following attributes:

  • pageType: String. Specify "webresource".
  • webresourceName: String. The name of the web resource to load.
  • data: (Optional) String. The data to pass to the web resource.

----------------------------------------------------------------

dashboard

The object contains the following attributes:

  • pageType: String. Specify "dashboard".
  • dashboardId: String. The ID of the dashboard to load. If you don't specify the ID, navigates to the default dashboard.
navigationOptions Object No

Options for navigating to a page: whether to open inline or in a dialog. If you don't specify this parameter, page is opened inline by default. The object contains the following attributes:

  • target: Number. Specify 1 to open the page inline; 2 to open the page in a dialog. Also, rest of the attributes (width, height, and position) are valid only if you have specified 2 in this attribute (open page in a dialog).

    NOTE: Entity lists can only be opened inline; entity records and web resources can be opened either inline or in a dialog.

  • width: (Optional) Number or Object. The width of dialog. To specify the width in pixels, just type a numeric value. To specify the width in percentage, specify an object of type SizeValue with the following properties:
    • value: Number. The numerical value.
    • unit: String. The unit of measurement. Specify "%" or "px". Default value is "px".
  • height: (Optional) Number or Object. The height of dialog. To specify the height in pixels, just type a numeric value. To specify the width in percentage, specify an object of type SizeValue with the following properties:
    • value: Number. The numerical value.
    • unit: String. The unit of measurement. Specify "%" or "px". Default value is "px".
  • position: (Optional) Number. Specify 1 to open the dialog in center; 2 to open the dialog on the side. Default is 1 (center).
  • title: (Optional) String. The dialog title on top of the center or side dialog.
successCallback function No

A function to execute on successful navigation to the page when navigating inline and on closing the dialog when navigating to a dialog.
errorCallback Function No

A function to execute when the operation fails.

Return Value

Returns a promise. The value passed when the promise resolves is dependent on the target:

  • inline: Promise resolves right away, and does not return any value.
  • dialog: Promise resolves when the dialog is closed. An object is passed only if the pageType = entityRecord and you opened the form in create mode. The object has a savedEntityReference array with the following properties to identify the entity record created:
    • entityType: The logical name of the entity.
    • id: A string representation of a GUID value for the record.
    • name: The primary attribute value of the record displayed or created.

Example

Example 1: Open account entity list

var pageInput = {
    pageType: "entitylist",
    entityName: "account"
};
Xrm.Navigation.navigateTo(pageInput).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

Example 2: Open an existing account entity record within a dialog

var pageInput = {
    pageType: "entityrecord",
    entityName: "account",
    entityId: "5a57f2c3-5672-ea11-a812-000d3a339706" //replace with actual ID
};
var navigationOptions = {
    target: 2,
    height: {value: 80, unit:"%"},
    width: {value: 70, unit:"%"},
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

Example 3: Open an account form in the create mode within a dialog

var pageInput = {
    pageType: "entityrecord",
    entityName: "account"    
};
var navigationOptions = {
    target: 2,
    height: {value: 80, unit:"%"},
    width: {value: 70, unit:"%"},
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success(result) {
            console.log("Record created with ID: " + result.savedEntityReference[0].id + 
            " Name: " + result.savedEntityReference[0].name)
            // Handle dialog closed
    },
    function error() {
            // Handle errors
    }
);

Example 4: Open an HTML web resource in a dialog

var pageInput = {
    pageType: "webresource",
    webresourceName: "new_sample_webresource.htm"
};
var navigationOptions = {
    target: 2,
    width: 500, // value specified in pixel
    height: 400, // value specified in pixel
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

Xrm.Navigation