Export (0) Print
Expand All

Customize entity attribute metadata

Applies To: CRM 2015 on-prem, CRM Online

[This topic is pre-release documentation and is subject to change in future releases.]

Use the AttributeMetadata class to retrieve existing attributes. This class is returned by the RetrieveAttributeRequest message. The AttributeMetadata class inherits from the abstract MetadataBase class.

Use the specific class for each attribute type with the CreateAttributeRequest message to update attributes or create custom attributes.

noteNote
You can access custom attributes programmatically after you create them, but you must add them to an entity form and publish them before users can see them.

The following table lists each type of Attribute you can work with. Each attribute inherits from the AttributeMetadata class.

 

Class Application Label Description

BooleanAttributeMetadata

Two Option

A Boolean attribute. You can specify the text for both options. When added to a form, the field properties control whether the attribute is displayed as two radio buttons, a check box, or a list.

DateTimeAttributeMetadata

Date and Time

A date and time attribute. You can specify the behavior and format of the attribute to store and show date and time values with or without time zone information. More information: DateTimeAttributeMetadata behavior and format

DecimalAttributeMetadata

Decimal Number

A decimal attribute. You can specify the level of precision up to ten decimal places and the minimum and maximum values from -100,000,000,000 to 100,000,000,000.

DoubleAttributeMetadata

Floating Point Number

A double attribute. You can specify the level of precision up to five decimal places and the minimum and maximum values from -100,000,000,000 to 100,000,000,000.

noteNote
DoubleAttributeMetadata replaces the FloatAttributeMetadata used in Microsoft Dynamics CRM 4.0.

ImageAttributeMetadata

Image

An image attribute. Each entity can have one image attribute. Certain system entities have image attributes and new image attributes cannot be added to system entities that do not have them. You can add an image attribute to custom entities

All image attributes have the SchemaName ‘EntityImage’ and the LogicalName ‘entityimage’. Custom image attributes will not use the solution publisher customization prefix in the name. More information: Entity images.

IntegerAttributeMetadata

Whole Number

An integer attribute. You can specify the maximum and minimum values from -2,147,483,648 to 2,147,483,647.

This attribute can be formatted to create the following types of fields using the IntegerFormat enumeration:

  • Duration: Displays a drop-down list that contains time intervals. A user can select a value from the list or type an integer value that represents the number of minutes.

  • TimeZone: Displays a drop-down list that contains a list of time zones.

  • Language: Displays a drop-down list that contains a list of languages that have been enabled for the organization. If no other languages have been enabled, the base language will be the only option. The value saved is the LCID value for the language.

LookupAttributeMetadata

Lookup

An attribute created when an entity relationship is created by using the CreateOneToManyRequest message.

MemoAttributeMetadata

Multiple Lines of Text

A memo attribute. Displays as a text box field in a form. The maximum length is 1048576 characters.

MoneyAttributeMetadata

Currency

A money attribute. You can specify the maximum and minimum values between - 922,337,203,685,477 and 922,337,203,685,477.

The level of precision can be set by using the PrecisionSource property:

  • When the precision is set to zero (0), the MoneyAttributeMetadata.Precision value is used.

  • When the precision is set to one (1), the Organization.PricingDecimalPrecision value is used.

  • When the precision is set to two (2), the TransactionCurrency.CurrencyPrecision value is used.

PicklistAttributeMetadata

Options Set

A picklistattribute. This attribute provides a set of options that are displayed in a drop-down list. You can create the picklist attribute so that it can contain its own options or use a global options set.

StateAttributeMetadata

Status

The state attribute is created automatically when the entity is created.

noteNote
The options available for this attribute are read-only.

StatusAttributeMetadata

Status Reason

The status attribute is created automatically when the entity is created. Each of the options must be associated with the StateAttributeMetadata attribute for the entity. Use the InsertStatusValueRequest message to update options available for this attribute.

noteNote
Each StatusOption must reference a specific state attribute value because status values depend on a specific state value.

StringAttributeMetadata

Single Line of Text

See StringAttributeMetadata formats.

StringAttributeMetadata formats

String attributes can be formatted to allow links to initiate phone calls by using Lync or Skype. This changes requires that a new FormatName property be added to the StringAttributeMetadata class and the deprecation of the Format property.

Using the StringFormat enumeration to define the format for StringAttributeMetadata.Format is deprecated. Instead, use the StringFormatName class to set the value of StringAttributeMetadata.FormatName.

This allows for setting the format value of PhoneNumber, which does not exist in the StringFormat enumeration.

For backwards compatibility, you can set a value to control how the attribute is formatted by using either the Format or FormatName property. Your existing code will continue to work if you only use Format, but you will not be able to format an attribute as a phone number without using FormatName. If both properties are set, the value set using FormatName is the one that will be applied.

The StringFormatName class contains the following members; each member returns a string with the same value as the member name:

 

Member name and value Description

Email

The form field will validate the text value as an e-mail address and create a mailto link in the field.

PhoneNumber

The form field will contain a link to initiate a phone call by using Lync or Skype.

PhoneticGuide

For internal use only.

Text

The form will display a text box.

TextArea

The form will display a text area field.

TickerSymbol

The form will display a link that will open to display a quote for the stock ticker symbol.

URL

The form will display a link to open the URL.

VersionNumber

For internal use only.

DateTimeAttributeMetadata behavior and format

Use the new DateTimeAttributeMetadata.DateTimeBehavior property to store date and time values with or without time zone information. Until now, all the date and time values in CRM were stored using the user’s local time zone information, including those with the DateOnly format. The CRM system use to convert values from the user’s local time zone to Coordinated Universal Time (UTC) on update, and back to the current user’s time zone when displayed on the form. This was not an optimal experience for storing and using:

  • Date only values without the time information, such as birthdays and anniversaries.

  • Date and time values without the time zone information so that users across multiple time zones see the same date and time value, such as the hotel check-in time.

You can use the DateTimeBehavior enumeration to specify a value for the DateTimeBehavior property, or can directly specify the string value. The DateTimeBehavior property can have any of the following three values:

 

Value Description

UserLocal

Stores the date and time value with current user local time zone information, and returns a DateTime value in UTC when retrieved. The update operation performs time zone conversion based on user’s time zone.

DateOnly

Stores the date value with the time value as 12:00 AM without the time zone information so that the date value remains the same across time zones. The update operation does not perform any time zone conversions.

TimeZoneIndependent

Stores the date and time values without the time zone information so that the date and time values remain the same across time zones. The update operation does not perform any time zone conversions.

noteNote
The new DateTimeBehavior property is available only if you are using CRM Online, and have updated your instance to Microsoft Dynamics CRM Online 2015 Update 1. This property is not available for Microsoft Dynamics CRM (on-premises).

The following sample code demonstrates how to set a DateOnly behavior for a new attribute:

// Create a date time attribute
DateTimeAttributeMetadata dtAttribute = new DateTimeAttributeMetadata
{
    // Set base properties
    SchemaName = "new_Birthday",
    DisplayName = new Label("Birthday", _1033),
    Description = new Label("Birthday", 1033),
    DateTimeBehavior = DateTimeBehavior.DateOnly
    Format = DateTimeFormat.DateOnly,
    ImeMode = ImeMode.Disabled
};

In the above code, you can also set the value of the DateTimeBehavior property by directly specifying the string value: DateTimeBehavior = "DateOnly"

Use the DateTimeAttributeMetadata.Format property to specify the date/time display format of the attribute irrespective of how it is stored in the database. You can use the DateTimeFormat enumeration to specify the display format: DateAndTime or DateOnly.

If the DateTimeBehavior property is set to DateOnly, you cannot set or change the value of the Format property to DateAndTime.

See Also

Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online
Send comments about this topic to Microsoft.
© 2015 Microsoft. All rights reserved.
Show:
© 2015 Microsoft