Introduction to entities in Microsoft Dynamics CRM 2013

Article
06/01/2017

Applies To: Dynamics CRM 2013

The entities are used to model and manage business data in Microsoft Dynamics CRM. 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 CRM is like adding a record 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 CRM 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 CRM 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 CRM to address specific business needs of the organization. In a Microsoft Dynamics CRM Solution, 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.

Note

In the Microsoft Dynamics CRM SDK documentation, the term “entity attribute” is used interchangeably with the term “attribute” and the term “property” (class property).

In This Topic

Entity metadata

Actions on entity records

Entity ownership

Record state and status

Entity images

Entity metadata

The metadata for a Microsoft Dynamics CRM 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 CRM 2013. 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 CRM. 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.

Names used in entity metadata

Entities, attributes, and relationships have several different names. The following table lists the various names that are used in the metadata.

Name	Description
Display Name	The name that is displayed to the user.
Display Collection Name	A plural version of the display name. This only applies to entities.
Logical Name	The unique name of the entity or attribute. This name is all lowercase.
Schema Name	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.

Note

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.

Actions on entity records

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. To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also view the metadata for an uncustomized organization in the Excel file called EntityMetadata.xlsx included in the top-level folder of the SDK download.

To perform an action, you call one of the methods in IOrganizationService. For example, to create a record in Microsoft Dynamics CRM, 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 CRM 2013.

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.

Action	Description	Method and/or Message
Create	Creates a record of a specific entity type, including custom entities.	IOrganizationService.Create CreateRequest
Update	Modifies the contents of a record.	IOrganizationService.Update UpdateRequest
Delete	Deletes a record.	IOrganizationService.Delete DeleteRequest
Retrieve	Retrieves a record.	IOrganizationService.Retrieve RetrieveRequest
Retrieve multiple	Retrieves a collection of records.	IOrganizationService.RetrieveMultiple RetrieveMultipleRequest
Assign	Changes ownership of a record. Valid for user-owned or team-owned entities.	AssignRequest
Share	Grants, modifies or revokes access to a record to another user or team. Valid for user-owned or team-owned entities.	GrantAccessRequest ModifyAccessRequest RevokeAccessRequest
Associate	Creates links between a record and a collection of records where there is a relationship between the entities.	AssociateRequest
Disassociate	Removes links between a record and a collection of records where there is a relationship between the entities.	DisassociateRequest
Set State	Set the state of a record.	SetStateRequest

Create

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.

Update

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.

Delete

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.

Retrieve

To perform this action, the caller must have Retrieve message privileges and access rights on the entity records retrieved.

Retrieve multiple

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.

Assign

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 CRM 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.

Use the GrantAccessRequest to share a record. Use the ModifyAccessRequest to change how a record is shared. Use the RevokeAccessRequest to remove all sharing for the record.

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 CRM. 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.

Associate

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.

Disassociate

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.

Set State

To perform this action, the caller must have SetState message privileges and access rights on the records that are being updated. The SetStateRequest message updates the StateCode and StatusCode attributes of the entity record.

Entity ownership

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.

Ownership Type	Description
Organization Owned	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.
Business Owned	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.
None	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.

Note

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.

Record state and status

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 more information, see Customize entity attribute metadata.

Entity images

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.

Account *	KbArticle	Campaign
Incident	Competitor *	Connection
Contact *	Contract	TransactionCurrency
EmailServerProfile	Goal	Invoice
Lead *	Mailbox	OpportunityProduct
SalesOrder	Organization	Product *
Publisher *	Queue	Resource *
SalesLiterature	Territory	SystemUser *

The SchemaName of the entity image attribute is always EntityImage. When an image attribute is added to an entity some additional attributes are created to support it as shown in the following table.

Schema Name	Attribute Type Name	Description
EntityImage_Timestamp	BigIntType	The value represents when the image was last updated and is used to help make sure that the latest version of the image is downloaded and cached on the client.
EntityImage_URL	StringType	An absolute URL to display the entity image in a client. The URL is composed this way: `{0}/image/download.aspx?entity={1}&attribute={2}&id={3}&timestamp={4}` 0 : The organization URL 1 : The entity logical name 2 : The attribute logical name 3 : The EntityImageId value. 4 : The EntityImage_Timestamp value For example: https://myorg.crm.dynamics.com/image/download.aspx?attribute=entityimage&entity=contact&id={ECB6D3DF-4A04-E311-AFE0-00155D9C3020}&timestamp=635120312218444444
EntityImageId	UniqueIdentifierType	The unique identifier of the image

Schema Name

Attribute Type Name

Description

EntityImage_Timestamp

BigIntType

The value represents when the image was last updated and is used to help make sure that the latest version of the image is downloaded and cached on the client.

EntityImage_URL

StringType

An absolute URL to display the entity image in a client.

The URL is composed this way:

{0}/image/download.aspx?entity={1}&attribute={2}&id={3}&timestamp={4}

0 : The organization URL
1 : The entity logical name
2 : The attribute logical name
3 : The EntityImageId value.
4 : The EntityImage_Timestamp value

For example:
https://myorg.crm.dynamics.com/image/download.aspx?attribute=entityimage&entity=contact&id={ECB6D3DF-4A04-E311-AFE0-00155D9C3020}&timestamp=635120312218444444

EntityImageId

UniqueIdentifierType

The unique identifier of the image

Note

Clients that do not use the current .NET assemblies need to include SdkClientVersion with a value of ‘6.0.0.0’ or higher in order to receive ImageAttributeMetadata attributes. More information: SdkClientVersion.

When you use RetrieveMultiple or Retrieve the EntityImage is not included when the ColumnSet.AllColumns property is set to true. Because of the potential size of data in this attribute, to return this attribute you must explicitly request it.

The binary data representing the image isn’t returned using the deprecated ExecuteFetchRequest class. You should use RetrieveMultipleRequest instead.

To update images set the value of the EntityImage to a byte[] that contains the content of the file. All images are displayed in a 144x144 pixel square. Images will be cropped and resized to reduce the size of the data before being saved.

Images with at least one side larger than 144 pixels are cropped on center to 144x144.
Images with both sides smaller than 144 are cropped square to their smallest side.

The following table shows two examples.