openForm (Client API reference)

Applies to Dynamics 365 (online), version 9.x

Opens an entity form or a quick create form.

Syntax

Xrm.Navigation.openForm(entityFormOptions,formParameters).then(successCallback,errorCallback);

Parameters

                             

NameTypeRequired Description
entityFormOptionsObjectYes Entity form options for opening the form. The object contains the following attributes:
  • cmdbar: (Optional) Boolean. Indicates whether to display the command bar. If you do not specify this parameter, the command bar is displayed by default.
  • 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).
  • entityId: (Optional) String. ID of the entity record to display the form for.
  • entityName: (Optional) String. Logical name of the entity to display the form for.
  • formId: (Optional) String. ID of the form instance to be displayed.
  • height: (Optional) Number. Height of the form window to be displayed in pixels.
  • navBar: (Optional) String. Controls whether the navigation bar is displayed and whether application navigation is available using the areas and subareas defined in the sitemap. Valid values are: "on", "off", or "entity".
    • on: The navigation bar is displayed. This is the default behavior if the navBar parameter is not used.
    • off: The navigation bar is not displayed. People can navigate using other user interface elements or the back and forward buttons.
    • entity: On an entity form, only the navigation options for related entities are available. After navigating to a related entity, a back button is displayed in the navigation bar to allow returning to the original record.
  • openInNewWindow: (Optional) Boolean. Indicates whether to display form in a new window.
  • windowPosition: (Optional) Number. Specify one of the following values for the window position of the form on the screen:
    • 1:center
    • 2:side
  • 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.
  • useQuickCreateForm: (Optional) Boolean. Indicates whether to open a quick create form. If you do not specify this, by default false is passed.
  • width: (Optional) Number. Width of the form window to be displayed in pixels.
formParameters Object No 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
successCallback Function No A function to execute when:
  • The record is saved in the quick create form.
  • The record is saved in the quick create form for a new record created using Save & New. This only applies to Unified Interface.

This function is passed an object as a parameter. The object has a savedEntityReference array with the following properties to identify the record(s) displayed or 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.

NOTE:

  • On web client:
    • The successCallback function is not executed when you open a form for an existing or new record.
    • The successCallback function is executed only when you save a record in a quick create form that was opened using the openForm method.
    • When you open a quick create form and create a record, the savedEntityReference array will contain a single item.
  • On Unified Interface:
    • The successCallback function is not executed when you open a form for an existing or new record.
    • The successCallback function is executed only when you save a record in a quick create form that was opened using the openForm method.
    • When you open a quick create form and create a record, the savedEntityReference array will contain a single item.
    • When you open a quick create form, and create multiple records by clicking Save & New, the savedEntityReference array will contain multiple items, each item representing the record created using the quick create form.
errorCallback Function No A function to execute when the operation fails.

NOTE: On Unified Interface, the errorCallback function will be executed only if you are opening a quick create form.

Remarks

You must use this method to open entity or quick create forms instead of the deprecated Xrm.Utility.openEntityForm and Xrm.Utility.openQuickCreate methods.

Examples

Example 1: Open an entity form for existing record

The following sample code opens a contact form to display an existing contact record:

var entityFormOptions = {};
entityFormOptions["entityName"] = "contact";
entityFormOptions["entityId"] = "8DA6E5B9-88DF-E311-B8E5-6C3BE5A8B200"

// Open the form.
Xrm.Navigation.openForm(entityFormOptions).then(
    function (success) {
        console.log(success);
    },
    function (error) {
        console.log(error);
    });

Example 2: Open an entity form for new record

The following sample code opens a contact form with some pre-populated values to create a new record:

var entityFormOptions = {};
entityFormOptions["entityName"] = "contact";

// Set default values for the Contact form
var formParameters = {};
formParameters["firstname"] = "Sample";
formParameters["lastname"] = "Contact";
formParameters["fullname"] = "Sample Contact";
formParameters["emailaddress1"] = "contact@adventure-works.com";
formParameters["jobtitle"] = "Sr. Marketing Manager";
formParameters["donotemail"] = "1";
formParameters["description"] = "Default values for this record were set programmatically.";

// Open the form.
Xrm.Navigation.openForm(entityFormOptions, formParameters).then(
    function (success) {
        console.log(success);
    },
    function (error) {
        console.log(error);
    });

Example 3: Open a quick create form

The following sample code opens a quick create contact form with some pre-populated values:

var entityFormOptions = {};
entityFormOptions["entityName"] = "contact";
entityFormOptions["useQuickCreateForm"] = true;

// Set default values for the Contact form
var formParameters = {};
formParameters["firstname"] = "Sample";
formParameters["lastname"] = "Contact";
formParameters["fullname"] = "Sample Contact";
formParameters["emailaddress1"] = "contact@adventure-works.com";
formParameters["jobtitle"] = "Sr. Marketing Manager";
formParameters["donotemail"] = "1";
formParameters["description"] = "Default values for this record were set programmatically.";

// Open the form.
Xrm.Navigation.openForm(entityFormOptions, formParameters).then(
    function (success) {
        console.log(success);
    },
    function (error) {
        console.log(error);
    });

Xrm.Navigation