Customize entity metadata

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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 provided in the SDK package. Download the Microsoft Dynamics CRM SDK package.More information: Browse the metadata for your organization

This topic is about how to work with entities programmatically. See TechNet: Create and edit entities for information about working with entities in the application.

In This Topic

Options available when you create a custom entity

Enable entity capabilities

Editable entity properties

Entity metadata messages

Messages supported by custom entities

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 EntityMetadata.IsActivity property. For more information, see Custom activities.

Entity Names

There are two types of names, and both must have a customization prefix:

  • EntityMetadata.LogicalName: Name that is the version of the entity name that is set in all lowercase letters.

  • EntityMetadata.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 EntityMetadata.OwnershipType property to set this. Use the OwnershipTypes enumeration 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

Use CreateEntityRequest.PrimaryAttribute to set this. Each entity has a StringAttributeMetadata attribute that uses StringFormat.Text as the primary attribute. 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 the EntityMetadata. IsBusinessProcessEnabled to true in order to enable the entity for business process flows.

Notes

Use the CreateEntityRequest or UpdateEntityRequest.HasNotes property 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.

Activities

Use the CreateEntityRequest or UpdateEntityRequest.HasActivities property to create an entity relationship with the ActivityPointer entity so that all the activity type entities can be associated with this entity.

Connections

Set the EntityMetadata.IsConnectionsEnabled property to enable creating connection records to associate this entity with other connection entities.

Queues

Use the EntityMetadata.IsValidForQueue property to add support for queues. When you enable this option, you can also set the EntityMetadata.AutoRouteToOwnerQueue property to automatically move records to the owner’s default queue when a record of this type is created or assigned.

E-mail

Set the EntityMetadata.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 EntityMetadata.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 EntityMetadata.AutoCreateAccessTeams to enable the entity for access teams. See Help & Training: About team templatesfor 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 EntityMetadata.IsRenameable prevents the display name from being changed in the application. You can still programmatically change the labels by updating the EntityMetadata.DisplayName and EntityMetadata.DisplayCollectionName properties.

Edit the entity Description

The managed property EntityMetadata.IsRenameable prevents the entity description from being changed in the application. You can still programmatically change the labels by updating the EntityMetadata.Description property.

Enable for use while offline

Use EntityMetadata.IsAvailableOffline to enable or disable the ability of Microsoft Dynamics 365 for Microsoft Office Outlook with Offline Access users to take data for this entity offline.

Enable the Outlook Reading Pane

Note

The EntityMetadata.IsReadingPaneEnabled property is For internal use only.

To enable or disable the ability of Microsoft Dynamics 365 for Outlook users to view data for this entity, use the Microsoft Outlook reading pane. You must set this property in the application.

Enable Mail Merge

Use EntityMetadata.IsMailMergeEnabled to enable or disable the ability to generate Microsoft Office Word merged documents that use data from this entity.

Enable Duplicate Detection

Use EntityMetadata.IsDuplicateDetectionEnabled to enable or disable duplicate detection for the entity. For more information, see Detect duplicate data.

Enable SharePoint Integration

Use EntityMetadata.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 EntityMetadata.IsVisibleInMobile to enable or disable the ability of Microsoft Dynamics 365 for phones users to see data for this entity.

Dynamics 365 for tablets

Use EntityMetadata.IsVisibleInMobileClient to enable or disable the ability of Microsoft Dynamics 365 for tablets users to see data for this entity.

If the entity is available for Dynamics 365 for tablets you can use EntityMetadata.IsReadOnlyInMobileClient to specify that the data for the record is read-only.

Enable Auditing

Use EntityMetadata.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. For more information, see Edit the site map.

Add or Remove Attributes

As long as the managed property EntityMetadata.CanCreateAttributes allows for creating attributes, you can use the CreateAttributeRequest message to add attributes. For more information, see Customize entity attribute metadata.

Add or Remove Views

As long as the managed property EntityMetadata.CanCreateViews 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 EntityMetadata.CanCreateCharts allows for creating charts and the EntityMetadata.IsEnabledForCharts entity property is true, you can use SavedQueryVisualization 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 the icons for an entity.

Use custom Help

EntityMetadata.EntityHelpUrlEnabled controls whether custom help is enabled for the entity. More information: Add custom help content.

Help URL

EntityMetadata.EntityHelpUrl controls what resource is displayed for help content for the entity if custom help is enabled. More information: Add custom help content.

Can Change Hierarchical Relationship

EntityMetadata.CanChangeHierarchicalRelationship controls whether the hierarchical state of entity relationships included in your managed solutions can be changed. More information:

Entity metadata messages

The following table lists the messages that you can use to create, retrieve, update and delete entity metadata.

Message name

Description

CreateEntityRequest

Creates a custom entity.

DeleteEntityRequest

Deletes a custom entity.

RetrieveAllEntitiesRequest

Retrieves the metadata for all entities.

RetrieveEntityRequest

Retrieves the metadata for an entity.

UpdateEntityRequest

Updates the metadata for an entity.

RetrieveMetadataChangesRequest

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.

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

Use the Organization service with Dynamics 365 metadata
Introduction to entities in Microsoft Dynamics 365
Browse the metadata for your organization
Customize entity attribute metadata
Customize entity relationship metadata
Detect duplicate data
Enable document management for entities
Configure entities and attributes for auditing
Edit the site map
View data with visualizations (charts)
Which entities are customizable?
Create a custom entity
Retrieve, update, and delete entities
Create and update an entity than can be emailed
Create a custom activity entity
Modify the icons for an entity
Modify the messages for an entity
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 privilege information to a file

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright