Introduction to entities in Microsoft Dynamics 365
Updated: November 29, 2016
Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
The entities are used to model and manage business data in Microsoft Dynamics 365. For example, entities such as account, campaign, and incident (case) can be used to track and support sales, marketing, and service activities. An entity has a set of attributes and each attribute represents a data item of a particular type. For example, the account entity has Name, Address, and OwnerId attributes. Conceptually, an entity is like a database table, and the entity attributes correspond to the table columns. Creating an entity record (or, simply a record) in Microsoft Dynamics 365 is like adding a row in a database table. The entities are divided into three categories: system, business, and custom. As a developer working with business data, you will use business and custom entities. System entities are used by Microsoft Dynamics 365 to handle all internal processes, such as workflows and asynchronous jobs. You cannot delete or customize system entities.
Business entities are part of the Microsoft Dynamics 365 default installation and they appear in the customization user interface. An account, contact, and letter are examples of business entities. After installation, you can add custom entities to Microsoft Dynamics 365 to address specific business needs of the organization. In a Microsoft Dynamics 365Solution, you can set business and custom entities and attributes to be either customizable or non-customizable. You can modify a customizable entity by renaming it, adding new attributes, or changing various settings, such as duplicate detection or queue support settings. You cannot modify a non-customizable entity. For more information about customization, unmanaged and managed solutions, and managed properties, see Package and distribute extensions using solutions.
If you are using the early-bound programming model, an entity is represented by a class, such as the Account class that represents the account entity. Entity attributes are represented by class properties. This class is generated by the CrmSvcUtil tool. For more information, see Use the early bound entity classes in code. Alternatively, you can write programs that work with entity data by using a dynamic approach. For more information, see Use the late bound entity class in code.
In the Microsoft Dynamics 365 SDK documentation, the term “entity attribute” is used interchangeably with the term “attribute” and the term “property” (class property).
The metadata for a Microsoft Dynamics 365 organization contains the definitions for the entities, attributes, and the relationships between the entities. For more information, see The metadata and data models in Microsoft Dynamics 365. As a developer there are many cases where it is useful to be able to find all the metadata for an organization. There are a number of ways you can find and reference the metadata:
You can use the Entity Metadata Browser to view entities and their properties in Microsoft Dynamics 365. For details, see Browse the metadata for your organization.
The SDK package contains this same information in an Microsoft Office Excel spreadsheet. You can find this in the file SDK\Tools\EntityMetadata.xlsx.
You can generate the metadata for your organization using these samples:
You can create the following types of the relationships between entities: one-to-many, many-to-one, and many-to-many. The records for a many-to-many relationships are stored in an intersect entity. After a relationship is defined, use the AssociateRequest message or the Associate method to create a link between the specified records, and use the DisassociateRequest message or the Disassociate method to remove a link between the specified records.
In the one-to-many and many-to-one relationships, some actions on the parent entity record affect the child entity records. The actions that have cascading behavior include: Assign, Delete, Merge, Share, Unshare and Reparent. For more information, see Entity relationship behavior.
Entities, attributes, and relationships have several different names. The following table lists the various names that are used in the metadata.
The name that is displayed to the user.
Display Collection Name
A plural version of the display name. This only applies to entities.
The unique name of the entity or attribute. This name is all lowercase.
The schema name is specified upon creation. It must be unique. It is used to create the logical name. This name should be in Pascal case. The schema name is used to create the class for the entity when using early bound programming.
For a custom entity, attribute, and relationship created in the context of a solution, the customization prefix in the logical and schema names is defined in the Publisher.CustomizationPrefix attribute. For a custom entity created programmatically, set the customization prefix to a string that is between two and eight characters in length, all alphanumeric characters starting with a letter. It cannot start with “mscrm”. For more information about entity metadata customization and naming conventions, see Customize entity metadata.
Each entity supports several different actions, for example create or delete a record, or assign a record to another user or team. Not all actions are allowed on all entity types or attributes. For each attribute, the metadata defines whether a given action is supported. For example, an attribute’s properties, such as IsValidForCreate, IsValidForRead and IsValidForUpdate tell you if you can create, retrieve or update the attribute. More information: Valid operations on attributes.
To perform an action, you call one of the methods in IOrganizationService. For example, to create a record in Microsoft Dynamics 365, you can use the IOrganizationService.Create method or the IOrganizationService.Execute method with the corresponding CreateRequest message. You must have the necessary privileges and access rights to perform these actions. For more information, see The security model of Microsoft Dynamics 365.
The following table lists the actions that are allowed on business and custom entity records and the methods and messages that you can use to perform these actions.
Method and/or Message
Creates a record of a specific entity type, including custom entities.
Modifies the contents of a record.
Deletes a record.
Retrieves a record.
Retrieves a collection of records.
Changes ownership of a record. Valid for user-owned or team-owned entities.
Grants, modifies or revokes access to a record to another user or team. Valid for user-owned or team-owned entities.
Creates links between a record and a collection of records where there is a relationship between the entities.
Removes links between a record and a collection of records where there is a relationship between the entities.
Set the state of a record.
To perform this action, the caller must have Create message privileges. Access rights do not apply to the Create action, but they do apply to the record after it has been created.
To own a record or to retrieve the newly created record, a user or team must also have read privileges and access rights on the new record. For example, if you have create privileges for accounts, you can create an account record and assign it to another user or team. However, unless you also have read privilege for accounts, and access rights on the new record, you cannot create an account and be the owner of that new account.
To perform this action, the caller must have Update message privileges and access rights on the entity records that are being updated.
When you update a record, only the attributes for which you specify data or for which you specify null are updated. All other values remain the same. Also, if you specify data for attributes that are not valid for update, they are ignored.
To perform this action, the caller must have Delete message privileges and access rights on the entity records being deleted.
The cascading rules determine whether related records are deleted at the same time. For more information, see Entity relationship behavior.
Typically, you should only delete records that you entered by mistake. For some record types, you can deactivate or close the record instead of deleting it. Not all record types can be deleted.
To perform this action, the caller must have Retrieve message privileges and access rights on the entity records retrieved.
To perform this action, the caller must have Retrieve message privileges and access rights on the entity records retrieved.
To retrieve a collection of records based on the query parameters, you can either use a query expression or FetchXML query language. Query expressions let you build a query tree by using a class hierarchy. The methods that use a query expression return a collection of strongly typed records. FetchXML lets you build a query by using an XML language. FetchXML returns an XML string. Therefore, you must do more data manipulation to use the query results. For more information, see Retrieve data with queries using SDK assemblies.
For user-owned or team-owned entities, you assign a record to a new owner. For more information, see Entity ownership. To perform this action, the caller must have Assign message privileges and access rights on the entity records.
The cascading rules determine whether related records are assigned to another user at the same time. For more information, see Entity relationship behavior.
When a record is assigned to another user or team, the previous owner still has access to this record if the ShareToPreviousOwnerOnAssign attribute is set to true. However, the previous owner will no longer have ownership of the record.
For user-owned or team-owned entities, you can share a record with other users or teams. To perform this action, the caller must have GrantAccess message privileges, ModifyAccess message privileges, and RevokeAccess message privileges and access rights on the entity records.
The cascading rules determine whether related records are shared at the same time. For more information, see Entity relationship behavior
Sharing is the way Microsoft Dynamics 365 users can give other users access to customer information as needed. For example, a salesperson might decide to share an opportunity with another salesperson so that they can both track the progress of an important sale.
A user must have share rights to share customer-related records, such as contacts, accounts, opportunities, cases, and orders, with any other user in Microsoft Dynamics 365. When a record is shared, you can specify the rights to grant for the shared record.
The following list describes the rules for sharing records:
Anyone with share privileges on a record can share it with additional users or teams.
Anyone with share privileges on a record can set access rights for that record. These access rights control how a user who shares a record can access that record.
Access on a shared record can be set to any access right, for example, read or write.
Access rights on a shared record can be different for each user that the record is shared with.
A record can be shared with the same security principal only one time. A user can share a record if they have share privileges on that record.
Anyone with share privileges on a business record can modify the access rights for users who have the record shared.
Anyone with share privileges on a business record can remove sharing for a specified user who has the record shared.
Anyone with share privileges on a business record can remove sharing for all users with whom the record was previously shared.
To perform this action, the caller must have Associate message privileges and access rights on the records that are being updated.
Associate creates multiple associations in one transaction between the specified record and each record in the specified collection for the relationship specified.
For a one-to-many relationship, this method sets the ReferencingAttribute in the related record to the ID of the specified record.
For a many-to-many relationship, this method creates a record in the intersect table for the relationship, which contains the ID of both the referenced and referencing records. The intersect table name is defined in the IntersectEntityName property for the relationship.
To perform this action, the caller must have Disassociate message privileges and access rights on the records that are being updated.
Disassociate reverses the associate operation, by updating the referenced and referencing records and deleting the intersect record where appropriate. For more information, see Associate.
There are several types of entity ownership. Most entities, including custom entities, are owned by the organization, by a user, or a team. There are some business entities that do not have an owner, such as discount type (discount list), where the ownership is defined by its parent entity discount. The type of ownership defines some of the operations that can be performed on a record. Ownership for an entity is defined in the metadata property OwnershipType. The following table lists the ownership properties.
Contains data involving something that belongs to or that can be viewed by the whole organization. Organization-owned entities cannot be assigned or shared. For example, products are owned by the organization. These entities have an attribute named organizationid.
Entities that belong to a business unit. These entities have an attribute named owningbusinessunit.
User or Team Owned
Assigned to a user or to a team. These entities contain data that relates to customers, such as accounts or contacts. Security can be defined according to the business unit for the user or team. These entities have attributes named owningteam and owninguser.
These entities are not owned by another entity.
Additional Information about User or Team Ownership
You can use the AssignRequest message to change the ownership of a record. For more information, see Assign. You can use the ReassignObjectsOwnerRequest or ReassignObjectsSystemUserRequest message to do bulk reassignment of all records for an owner.
By limiting ownership to users or teams, you restrict access to data to authorized users in the organization. However, you can expand data access to additional users and teams by sharing an entity record with them. You can also assign a record to another user or team. Configuring security for user-owned or team-owned entities gives you more access levels for the security roles than for organization-owned entities. The security roles for organization-owned entities have two access levels: None and Global. The user-owned or team-owned entities have five access levels: Global, Deep, Local, Basic, and None.
Most business entities have two properties to track the state of a record. These are StateCode, which is called Status in the Web application and StatusCode, which is called Status Reason in the Web application. The StateCode and StatusCode attribute values are linked. The StateCode attribute is used internally to represent the status of the entity. The StatusCode attribute is used to display this value to the end user. The set of valid state codes for an entity is not customizable, but the status codes are customizable. For the case entity and custom entities, you can define additional criteria for valid transitions between statuses. For more information, see Customize entity attribute metadata and Define custom state model transitions.
Certain system entities have image attributes. You can add image attributes to custom entities. When an entity has an image attribute, you can set the PrimaryImageAttribute property to control whether the image will be shown in the application. When the image is shown in the application users of the web application can upload pictures for the entity record. The following system entities have image attributes. Those marked with an asterisk are enabled by default to show them in the application.
More information: Image data attributes.
Administration and security entities
Use metadata to generate entity diagrams
Define custom state model transitions
Key to entity diagrams
Model your business data in Microsoft Dynamics 365
Customize entity relationship metadata
Entity relationship behavior
The metadata and data models in Microsoft Dynamics 365
Use the Organization service with Dynamics 365 metadata
Package and distribute extensions using solutions
Organization service entities
The security model of Microsoft Dynamics 365
Sample: Set and retrieve entity images
Sample: Assign a record to a team
Sample: Share records using GrantAccess, ModifyAccess and RevokeAccess messages
Sample: Merge two records
Sample: Validate record state and set the state of the record
Sample: Rollup records related to a specific record
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright