Customize entity forms

Forms provide the user interface (UI) that people use to create, view, or edit entity records. Use the form designer in the customization tools to create and edit entity forms. More information: Create and design forms for information about tasks related to working with forms in the application.

This topic will provide information necessary to create or edit forms programmatically.

Access form definitions

Entity forms are stored in the SystemForm entity along with dashboards and visualizations. There are two ways that you can inspect the form definitions for an entity:

  • Include the entity in an unmanaged solution and export the solution.

  • Query the SystemForm entity

View FormXML from an exported entity

Only definitions of system entity forms that have been customized are included in exported managed solution. To view the definition of a system entity form, you must either change it in some way, or create a new form by saving the existing form with a new name.

After you export the solution, extract the contents and view the customizations.xml file. You’ll find the definition of the forms in ImportExportXml > Entities > Entity > FormXml. In the <FormXml> node, you’ll find each type of form is grouped in a <forms> element with the type attribute specifying the type of form.

Form properties

The following table describes key SystemForm entity attributes and the corresponding data included in the XML elements exported with the solution.

SystemForm property FormXML element Description
AncestorFormId <ancestor> Unique identifier of the parent form. This is set when you create a new form by using Save As for an existing form or by using CopySystemFormRequest.
CanBeDeleted <CanBeDeleted> Information that specifies whether this component can be deleted.This managed property is only applied if the form was created by importing a managed solution.
Description <Descriptions> Description is a string and <Descriptions> contains any localized labels for the description of the form.

The localized labels can be retrieved using the RetrieveLocLabelsRequest.
FormActivationState <FormActivationState> Specifies the state of the form.

Only forms of type “main” can be deactivated.

Valid Values:

- 0: Inactive
- 1: Active
FormId <formid> Unique identifier of the form
FormPresentation <FormPresentation> Specifies whether this form is in the updated UI layout in Dynamics 365 for Customer Engagement.
FormXml <form> XML representation of the form layout.
IntroducedVersion <IntroducedVersion> Version of the solution that the form was added in.
IsAIRMerged N/A Specifies whether this form is merged with the updated UI layout in Dynamics 365 for Customer Engagement.
IsCustomizable <IsCustomizable> Information that specifies whether this component can be customized.

This managed property is only applied if the form was created by importing a managed solution.
IsDefault N/A Information that specifies whether the form or the dashboard is the system default.
Name <LocalizedNames> Name is a string and <LocalizedNames> contains any localized labels for the name of the form.

The localized labels can be retrieved using the RetrieveLocLabelsRequest.
ObjectTypeCode The form is a decedent of the Entity element. The ObjectTypeCode value is the entity logical name.
Type <forms> element type attribute Valid values for forms are:

- 2: main
- 5: mobile
- 6: quick
- 7: quickCreate

Create and edit forms

You can only create new forms for an entity where EntityMetadata. CanCreateForms allows it.

You can create new forms using either a CreateRequest or the CopySystemFormRequest. When using CopySystemFormRequest or using Save As in the form editor, note that there is no inheritance between forms. Therefore, changes to the base form aren’t automatically applied to any forms created from it.

Editing the form definitions from an exported managed solution and then re-importing the solution is a supported method to edit entity forms. When manually editing forms we strongly recommend you use an XML editor that allows for schema validation. More information: Edit the Customizations XML File with Schema Validation

See also

Customize Microsoft Dynamics 365 Customer Engagement
Create and design forms
SystemForm Entity
Create or edit how business rules are initiated
Form XML Schema