Customize entity metadata
Entities are defined by metadata. By defining or changing the entity metadata, you can control the capabilities of an entity. To view the metadata for your organization, use the metadata browser. Download the metadata browser.
More information: Browse the Metadata for Your Organization
This topic is about how to work with entities programmatically. See Create or edit entities (record types) for information about working with entities in the application.
Entities can be created using either the Organization service or the Web API. The following information can be applied to both.
- With the Organization service you will use the EntityMetadata class. More information: Create a custom entity and Retrieve, update, and delete entities
- With the Web API you will use the EntityMetadata EntityType. More information : Create and update entity definitions using the Web API.
Entity metadata operations
How you work with entity metadata depends on which service you use.
Since the Web API is a RESTful endpoint, it uses a different way to create, retrieve, update, and delete metadata. Use POST, GET, PUT, and DELETE HTTP verbs to work with metadata entitytypes. More information : Create and update entity definitions using the Web API.
One exception to this is the RetrieveMetadataChanges Function provides a way to compose a metadata query and track changes over time.
If working with Organization Service, use RetrieveMetadataChangesRequest class. This class contains the data that is needed to retrieve a collection of metadata records that satisfy the specified criteria. The RetrieveMetadataChangesResponse returns a timestamp value that can be used with this request at a later time to return information about how metadata has changed since the last request.
| Message | Web API | SDK Assembly |
|---|---|---|
| CreateEntity | Use a POST request to send data to create an entity. | CreateEntityRequest |
| DeleteEntity | Use a DELETE request to delete an entity. | DeleteEntityRequest |
| RetrieveAllEntities | Use GET request to retrieve entity data. | RetrieveAllEntitiesRequest |
| RetrieveEntity | RetrieveEntity Function | RetrieveEntityRequest |
| UpdateEntity | Use a PUT request to update an entity. | UpdateEntityRequest |
| RetrieveMetadataChanges Used together with objects in the Microsoft.Xrm.Sdk.Metadata.Query namespace to create a query to efficiently retrieve and detect changes to specific metadata. More information: Retrieve and Detect Changes to Metadata. |
RetrieveMetadataChanges Function | RetrieveMetadataChangesRequest |
Options available when you create a custom entity
The following table lists the options that are available when you create a custom entity. You can only set these properties when you create a custom entity.
| Option | Description |
|---|---|
| Create as custom activity | You can create an entity that is an activity by setting the IsActivity property when using the organization service or Web API respectively. For more information, see Custom Activities in Dynamics 365 Customer Engagement (on-premises). |
| Entity Names | There are two types of names, and both must have a customization prefix:LogicalName: Name that is the version of the entity name that is set in all lowercase letters.SchemaName: Name that will be used to create the database tables for the entity. This name can be mixed case. The casing that you use sets the name of the object generated for programming with strong types or when you use the REST endpoint.Note: If the logical name differs from the schema name, the schema name will override the value that you set for the logical name. When an entity is created in the application in the context of a specific solution, the customization prefix used is the one set for the Publisher of the solution. When an entity is created programmatically, you can set the customization prefix to a string that is between two and eight characters in length, all alphanumeric characters and it must start with a letter. It cannot start with “mscrm”. The best practice is to use the customization prefix defined by the publisher that the solution is associated with, but this is not a requirement. An underscore character must be included between the customization prefix and the logical or schema name. |
| Ownership | Use the OwnershipType property to set this. Use the OwnershipTypes enumeration or OwnershipTypes EnumType to set the type of entity ownership. The only valid values for custom entities are OrgOwned or UserOwned. For more information, see Entity Ownership. |
| Primary Attribute | With the Organization service, use CreateEntityRequest.PrimaryAttribute property to set this. With the Web API the JSON defining the entity must include one StringAttributeMetadata with the IsPrimaryName property set to true.In both cases string attribute must be formatted as Text. The value of this attribute is what is shown in a lookup for any related entities. Therefore, the value of the field should represent a name for the entity record. |
Enable entity capabilities
The following table lists entity capabilities. You can set these capabilities when you create an entity or you can enable them later. Once enabled, these capabilities cannot be disabled.
| Capability | Description |
|---|---|
| Business Process flows | Set IsBusinessProcessEnabled to true in order to enable the entity for business process flows. |
| Notes | To create an entity relationship with the Annotation entity and enable the inclusion of a Notes area in the entity form. By including Notes, you can also add attachments to records. With the Organization service, use the CreateEntityRequest or UpdateEntityRequest HasNotes property With the Web API set the EntityMetadata. HasNotes property. |
| Activities | To create an entity relationship with the ActivityPointer entity so that all the activity type entities can be associated with this entity.With the Organization service use the CreateEntityRequest or UpdateEntityRequest HasActivities property. With the Web API, set the EntityMetadata. HasActivities property. |
| Connections | To enable creating connection records to associate this entity with other connection entities set the IsConnectionsEnabled.Value property value to true. |
| Queues | Use the IsValidForQueue property to add support for queues. When you enable this option, you can also set the AutoRouteToOwnerQueue property to automatically move records to the owner’s default queue when a record of this type is created or assigned. |
Set the IsActivityParty property so that you can send e-mail to an e-mail address in this type of record. |
Editable entity properties
The following table lists entity properties that you can edit. Unless a managed property disallows these options, you can update them at any time.
| Property | Description |
|---|---|
| Allow Quick Create | Use IsQuickCreateEnabled to enable quick create forms for the entity. Before you can use quick create forms you must first create and publish a quick create form.Note: Activity entities do not support quick create forms. |
| Access Teams | Use AutoCreateAccessTeams to enable the entity for access teams. See About team templates for more information. |
| Primary Image | If an entity has an image attribute you can enable or disable displaying that image in the application using PrimaryImageAttribute. For more information see Entity Images. |
| Change display text | The managed property IsRenameable prevents the display name from being changed in the application. You can still programmatically change the labels by updating the DisplayName and DisplayCollectionName properties. |
| Edit the entity Description | The managed property IsRenameable prevents the entity description from being changed in the application. You can still programmatically change the labels by updating the Description property. |
| Enable for use while offline | Use IsAvailableOffline to enable or disable the ability of Dynamics 365 for Microsoft Office Outlook with Offline Access users to take data for this entity offline. |
| Enable the Outlook Reading Pane | Note: The IsReadingPaneEnabled property is For internal use only.To enable or disable the ability of Dynamics 365 for Outlook users to view data for this entity, use the Outlook reading pane. You must set this property in the application. |
| Enable Mail Merge | Use IsMailMergeEnabled to enable or disable the ability to generate Office Word merged documents that use data from this entity. |
| Enable Duplicate Detection | Use IsDuplicateDetectionEnabled to enable or disable duplicate detection for the entity. For more information, see Detect Duplicate Data in Dynamics 365 Customer Engagement (on-premises). |
| Enable SharePoint Integration | Use IsDocumentManagementEnabled to enable or disable SharePoint Server integration for the entity. For more information, see Enable Document Management for Entities. |
| Enable Dynamics 365 for phones | Use IsVisibleInMobile to enable or disable the ability of Dynamics 365 for phones users to see data for this entity. |
| Dynamics 365 for tablets | Use IsVisibleInMobileClient to enable or disable the ability of Dynamics 365 for tablets users to see data for this entity.If the entity is available for Dynamics 365 for tablets you can use IsReadOnlyInMobileClient to specify that the data for the record is read-only. |
| Enable Auditing | Use IsAuditEnabled to enable or disable auditing for the entity. For more information, see Configure Entities and Attributes for Auditing. |
| Change areas that display the entity | You can control where entity grids appear in the application Navigation Pane. This is controlled by the SiteMap. |
| Add or Remove Attributes | As long as the managed property CanCreateAttributes.Value allows for creating attributes, you can add attributes to the entity. For more information, see Customize Entity Attribute Metadata. |
| Add or Remove Views | As long as the managed property CanCreateViews.Value allows for creating views, you can use the SavedQuery entity to create views for an entity. |
| Add or Remove Charts | As long as the managed property CanCreateCharts.Value allows for creating charts and the IsEnabledForCharts entity property is true, you can use the SavedQueryVisualization Entity to create charts for an entity. For more information, see View Data with Visualizations (Charts). |
| Add or Remove Entity Relationships | There are several managed properties that control the types of entity relationships that you can create for an entity. For more information, see Customize Entity Relationship Metadata. |
| Change Icons | You can change the icons used for custom entities. For more information, see Modify Entity Icons. |
| Can Change Hierarchical Relationship | CanChangeHierarchicalRelationship.Value controls whether the hierarchical state of entity relationships included in your managed solutions can be changed. More information: |
Messages supported by custom entities
Custom entities support the same base messages as system entities. The set of messages available depends on whether the custom entity is user-owned or organization owned. For more information, see Actions on Entity Records.
See also
Extend the Metadata Model for Dynamics 365 Customer Engagement (on-premises)
Introduction to Entities in Dynamics 365 Customer Engagement (on-premises)
Browse the Metadata for Your Organization
Customize Entity Attribute Metadata
Entity Relationship Metadata
Detect Duplicate Data in Dynamics 365 Customer Engagement (on-premises)
Enable Document Management for Entities
Configure Entities and Attributes for Auditing
View Data using Charts (Visualizations)
Which Entities are Customizable?
Create a Custom Entity
Retrieve, Update and Delete Entities
Create and Update an Emailable Entity
Create a Custom Activity Entity
Modify Entity Icons
Modify Entity Messages
Sample: Create and Update Entity Metadata
Sample: Create a Custom Activity Entity
Sample: Create and Update an Emailable Entity
Sample: Dump Entity Metadata to a File
Sample: Dump Entity Privlege Information to a File