Entity Operations using the Organization service
When you work with Common Data Service data using the organization service you will use the Entity class with the late-bound style or with generated entity classes using the early-bound style. The generated entity classes inherit from the Entity class, so understanding the Entity class is important for either style.
This topic will describe some of the most frequently used properties and methods of the Entity class.
When you instantiate a new Entity instance using the late-bound style you must provide a valid string value to specify what type of entity it is. The
LogicalName is defined in the entity metadata.
When using the early-bound style, this value is set by the constructor of the generated class. For example:
var account = new Entity("account");
In your code, if you later want to retrieve the string value that describes the type of entity, you can use the LogicalName property. This is useful for the many APIs that require an entity logical name as a parameter.
When you instantiate an entity instance, whether using the late-bound or early-bound style, it doesn't have a unique id set. If you are creating an entity, you shouldn't set it, but allow it to be set by the system when you create (save) it.
If you are retrieving an entity, it will include the primary key attribute value whether you request it or not. The primary key attribute name is different for each type of entity. Generally, the name of the primary key attribute is the entity
id. So for an account entity it is
accountid and for contact it is
While you can get or set the primary key value using the primary key attribute, you can also use the Id property to access the value without having to remember the name of the primary key attribute.
Early bound access to attributes
If you are using the early-bound style with generated classes, you will find typed properties for each attribute in the class. The properties for the attributes use the AttributeMetadata.SchemaName and they can be accessed directly on the entity instance. For example:
//Using the early-bound Account entity class var account = new Account(); // set attribute values // string primary name account.Name = "Contoso"; // Boolean (Two option) account.CreditOnHold = false; // DateTime account.LastOnHoldTime = new DateTime(2017, 1, 1); // Double account.Address1_Latitude = 47.642311; account.Address1_Longitude = -122.136841; // Int account.NumberOfEmployees = 500; // Money account.Revenue = new Money(new decimal(5000000.00)); // Picklist (Option set) account.AccountCategoryCode = new OptionSetValue(1); //Preferred customer
Late bound access to attributes
The data contained within an entity is in the Entity.Attributes property. This property is an AttributeCollection that provides a whole set of methods to add new attributes, check whether an attribute exists, or remove attributes.
Discover attribute names and data types
In the late-bound style, you need to know the AttributeMetadata.LogicalName for the attribute and the data type. The
LogicalName is the lowercase version of the
SchemaName. You can discover the
LogicalName and type for attributes in several ways:
- View the definition of the attribute in the customization tools
- For system entities, you can review the Entity Reference
- Use a tool to browse the metadata for entities, such as the Metadata Browser described in Browse the metadata for your environment
Attribute types can be any of the following:
|EntityReference||A Lookup attribute. A link to another record.|
|BooleanManagedProperty||Used only for entities that can be solution components, such as the WebResource Entity. More information: Use managed properties|
|Money||A Currency attribute.|
|OptionSetValue||An Option Set attribute. State and Status attributes also use this type.|
|Boolean||A Two Option attribute.|
|Byte||An Image attribute. Each entity can have one image and the attribute is named
|DateTime||A Date and Time attribute usually uses a UTC value. More information: Behavior and format of the date and time attribute|
|Decimal||A Decimal Number attribute.|
|Double||A Floating Point Number attribute.|
|Guid||Usually used as the unique identifier for the entity.|
|Int32||A Whole Number attribute.|
|String||Multiple Lines of Text and Single Line of Text attributes use this type.|
There are three different ways to interact with entity attributes using the late-bound style:
- Use the indexer on the entity
- Use the indexer on the
- Use the entity methods provided
Use the indexer on the entity
In most cases using the late-bound style, you can interact with collection by using the indexer to get or set the value of an attribute using the
LogicalName for the attribute. For example, to set the name attribute of an account:
//Use Entity class with entity logical name var account = new Entity("account"); // set attribute values // string primary name account["name"] = "Contoso"; // Boolean (Two option) account["creditonhold"] = false; // DateTime account["lastonholdtime"] = new DateTime(2017, 1, 1); // Double account["address1_latitude"] = 47.642311; account["address1_longitude"] = -122.136841; // Int account["numberofemployees"] = 500; // Money account["revenue"] = new Money(new decimal(5000000.00)); // Picklist (Option set) account["accountcategorycode"] = new OptionSetValue(1); //Preferred customer
Use the indexer on the Attributes collection
Just like you would on the entity, you can also access a value using the indexer on the Attributes collection.
string accountName = account.Attributes["name"];
Use the entity methods
You can also use Entity methods to get or set attribute values.
|GetAttributeValue<T>(String)||Use this to return a typed attribute value|
|SetAttributeValue(String, Object)||Use this to set a typed attribute value|
account.SetAttributeValue("name", "Account Name"); var accountName = account.GetAttributeValue<string>("name");
Any entity attribute value that can be displayed in the UI and is not a string will have a string formatted value that can be used to display the value in the UI. For example:
- Money values will have a string value with the appropriate currency and precision formatting.
- Date values will have the formatting set depending on how the system is configured
- OptionSet values will display the localized label that represents the integer value
Formatted values only apply to entities that have been retrieved. Once you set the value, a new formatted value is not calculated until you save the entity and retrieve the entity again. The formatted value is generated on the server.
For example, both of these retrieve the same formatted value:
var formattedRevenueString1 = account.FormattedValues["revenue"]; var formattedRevenueString2 = account.GetFormattedAttributeValue("revenue");
More information: Access formatted values
When you create an entity you can also define a set of related entity records to create in the same operation. More information: Create related entities in one operation
When you retrieve an entity you can compose use the RetrieveRequest to by setting the RelatedEntitiesQuery with a query to include related entities in the results. More information: Retrieve with related records
If you include related entities in the results, you can also update values on those related entities and include them when you update the entity. More information: Update related entities in one operation
Convert to an EntityReference
Convert to an entity class
If you are using the early bound style, you will need to convert the Entity instance to the type of generated entity class you are using. This can usually be done with a cast, but you can also use the Entity.ToEntity<T>() method.
Account account1 = (Account)retrievedEntity; Account account2 = retrievedEntity.ToEntity<Account>();
This method cannot be used to convert a generated entity instance to another generated class or to Entity . It can only be used to convert an Entity instance to one of the generated classes that inherit from it. If the Entity instance isn't actually an instance of the generated class this message will throw an error.
These topics will explain more about working with Common Data Service entities.