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
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|
|UpdateEntity||Use a PUT request to update an entity.||UpdateEntityRequest|
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.
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.
|Create as custom activity||You can create an entity that is an activity by setting the
|Entity Names||There are two types of names, and both must have a customization prefix:
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
|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
In both cases string attribute must be formatted as
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.
|Business Process flows||Set
|Notes||To create an entity relationship with the
With the Organization service, use the CreateEntityRequest or UpdateEntityRequest
With the Web API set the EntityMetadata.
|Activities||To create an entity relationship with the
With the Organization service use the CreateEntityRequest or UpdateEntityRequest
With the Web API, set the EntityMetadata.
|Connections||To enable creating connection records to associate this entity with other connection entities set the
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.
|Allow Quick Create||Use
Activity entities do not support quick create forms.
|Primary Image||If an entity has an image attribute you can enable or disable displaying that image in the application using
|Change display text||The managed property
|Edit the entity Description||The managed property
|Enable for use while offline||Use
|Enable the Outlook Reading Pane||Note:
To enable or disable the ability of Office 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
|Enable Duplicate Detection||Use
|Enable SharePoint Integration||Use
|Enable Dynamics 365 for phones||Use
|Dynamics 365 for tablets||Use
If the entity is available for Dynamics 365 for tablets you can use
|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
|Add or Remove Views||As long as the managed property
|Add or Remove Charts||As long as the managed property
|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||
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.