Edit

Introduction to entities

  • Article

The entities are used to model and manage business data in Dynamics 365 Customer Engagement (on-premises). 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 Dynamics 365 Customer Engagement (on-premises) 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 Dynamics 365 Customer Engagement (on-premises) to handle all internal processes, such as workflows and asynchronous jobs. You cannot delete or customize system entities.

Business entities are part of the Dynamics 365 Customer Engagement (on-premises) 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 Dynamics 365 Customer Engagement (on-premises) to address specific business needs of the organization. In a Dynamics 365 Customer Engagement (on-premises) 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 with Dynamics 365 Customer Engagement (on-premises) 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 WCF Early Bound (strong typed) Programming. Alternatively, you can write programs that work with entity data by using a dynamic approach. For more information, see WCF Late Bound (loosely typed) Programming.

Note

In the Dynamics 365 Customer Engagement (on-premises) Web Services, the term “entity attribute” is used interchangeably with the term “attribute” and the term “property” (class property).

Entity metadata

The metadata for a Dynamics 365 Customer Engagement (on-premises) organization contains the definitions for the entities, attributes, and the relationships between the entities. For more information, see The Metadata and Data Models in Dynamics 365 Customer Engagement (on-premises). 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:

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. More information: Valid operations on attributes.

To perform an action, you call one of the methods inIOrganizationService. For example, to create a record in Dynamics 365 Customer Engagement (on-premises), 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 Dynamics 365 Customer Engagement (on-premises).

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 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 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 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 Privileges and access rights on the entity records retrieved.

Retrieve multiple

To perform this action, the caller must have Retrieve 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 Creating Queries to Retrieve Data.

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

Note

After changing a record’s ownership to another user, a user will receive an ‘Access Denied’ error when trying to access that record if the user only has ‘User’ level record privilege to that 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, ModifyAccess, and RevokeAccess 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 Dynamics 365 Customer Engagement (on-premises) 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 Dynamics 365 Customer Engagement (on-premises). 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 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 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 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 either owned by the organization or by a user or 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. Ownership type is configured at the time of entity (table) creation and changing ownership type later is not supported. 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 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

Administration and security entities
Generate entity relationship diagrams
Define custom state model transitions
Model Your Business Data With Dynamics 365 Customer Engagement (on-premises)
Entity Relationship Metadata
Entity Relationship Behavior
The Metadata and Data Models in Dynamics 365 Customer Engagement (on-premises)
Extend the Metadata Model for Dynamics 365 Customer Engagement (on-premises)
Package and Distribute Extensions with Dynamics 365 Customer Engagement (on-premises) Solutions
IOrganizationService Entities
The Security Model of Dynamics 365 Customer Engagement (on-premises)
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 State of the Record
Sample: Rollup records related to a specific record