Export (0) Print
Expand All

Introduction to entities in Microsoft Dynamics CRM

Applies To: CRM 2015 on-prem, CRM Online

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.

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

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

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

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.

Share

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.

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

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 *

More information: Image data attributes.

See Also

Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online
Send comments about this topic to Microsoft.
© 2014 Microsoft Corporation. All rights reserved.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft