Attributes

Attributes provide additional data about entities, and every entity in Microsoft CRM contains multiple attributes. For example, the Contact entity uses attributes such as first name, last name, and phone number. Each attribute has a data type (such as integer, money, and bit) that determines the type of data that you can store in a field.

When you install Microsoft CRM, it creates almost 120 entities, and each entity possesses up to 125 attributes. So we're talking about potentially 15,000 data attributes right out of the box!

But of course you know that even 15,000 attributes won't be enough for your business. Everyone wants a system as highly customized to their business as possible, and Microsoft CRM makes it easy for you to add new attributes or customize the default attributes.

However, before you start customizing attributes, let's review the terminology and concepts related to attributes.

Attribute Properties

Every attribute has multiple attribute properties that further define how the attribute behaves within Microsoft CRM. Figure 4-12 shows the attribute editor and the properties of an attribute.

Figure 4-12: Attribute properties for a single attribute

The following attribute properties apply to every attribute:

• Display name Sets the text that users see throughout Microsoft CRM, such as on the forms, views, and advanced find feature.

• Schema name Displays the metadata schema name. The schema name also correlates to the column name in the underlying SQL Server database.

• Requirement level Dictates the type of data validation that Microsoft CRM should enforce when users enter or update data on a form (Business Required, Business Recommended, or No Constraint).

• Type Specifies the data type of the attribute. Data types include integer, picklist, and bit, among others.

• Description Text that describes the attribute. End users do not see this text, but system customizers can.

Tip 

When you create a new custom attribute, you might be tempted to skip the description field because it's optional. However, we strongly encourage you to invest an extra 20 to 30 seconds to enter the purpose of this new attribute. This might save you time down the road when you (or someone who takes over the project from you) look at the attribute and wonder, "Why did we add this field?" We suggest that, at a minimum, you enter your name and the date that you created the attribute.

Depending on the data type of the attribute, some attributes include additional properties. Table 4-5 outlines the additional attribute properties and the data types to which they apply.

Table 4-5: Data Type—Specific Attribute Properties

Attribute property	Applicable data types
Format	nvarchar, int, ntext, datetime
Maximum Length	nvarchar, ntext
List Value	bit, picklist
Default Value	bit, picklist
Minimum Value	int, float, money
Maximum Value	int, float, money
Precision	float, money

Next, let's review each of these data types in detail to understand how they work within Microsoft CRM.

Data Types

If you've worked with relational databases, you probably already understand data types in great detail, so we'll just review how they relate specifically to Microsoft CRM. If you are not familiar with data types, it's critical for you to develop an understanding of how they work, because data types drastically affect how Microsoft CRM stores, manages, and displays data in the system. For example, Microsoft CRM won't allow users to enter a text value such as abc into an attribute with a money data type. The attribute data types also determine how Microsoft CRM sorts records and the types of operations that you can perform by using the advanced find feature.

Microsoft CRM uses the following 13 data types to store attribute data:

• nvarchar Stores text and numeric data in one field.

• picklist Allows you to specify a predefined list of values for the attribute. Users see a drop-down list on the form.

• bit Stores data as one of two values: 0 or 1. In Microsoft CRM, you can relabel the 0 and 1 values so that users see Yes and No, True and False, and so on. Many people use the word Boolean when referring to bit data types.

• int Allows you to store only whole numbers, such as -2, -1, 0, 1, and 2. Int is an abbreviation for integer.

• float Stores numeric values with a configurable number of decimals, such as 1.23 or 3.145.

• money Stores currency amounts.

• ntext Stores text and numeric data in one field.

• datetime Stores date and time data.

• status System data type that stores status information about an entity.

• state System data type that stores state information about an entity.

• primarykey System data type that stores cross-reference information.

• owner System data type that stores the entity's owner.

• lookup System data type that stores information about related records.

Microsoft CRM automatically creates and manages the system data types, so you really don't have to worry about too much. However, you should know that they exist, because you will see attributes with system data types listed on every entity.

We'll explain the different data types in more detail later in this chapter when we explain how to add custom attributes to an entity.

Requirement Levels

For every attribute, Microsoft CRM defines a requirement level. The requirement level dictates the type of data validation that Microsoft CRM should enforce when users enter or update data on a form. In addition to enforcing data validation, Microsoft CRM automatically formats fields on a form with color codes to indicate the requirement level of the attribute. Table 4-6 explains the three requirement levels and their color coding.

Table 4-6: Requirement Levels

Requirement level	Description	Attribute label formatting on form
Business Required	Users must enter a value for this attribute. If they leave it blank, the system prompts them when they try to save.	Red and bold
Business Recommended	Provides a visual cue to users that your business recommends completion of this field. Users can save the record with no data if necessary. Saving a record with no data in a Business Recommended field does not prompt or warn the user.	Blue and bold
No Constraint	Indicates to users that no constraint exists on the data field.	Black with no special formatting

If you specify an attribute as Business Required, you cannot remove it from the entity form. Likewise, you shouldn't set an attribute as Business Required if it isn't displayed on the form.

Reviewing the Current Schema

Before you start adding or modifying attributes, we recommend that you become familiar with the entity attributes that Microsoft CRM creates upon installation. In other words, you should check the default database schema to determine whether a field already exists in the database before you create a new custom attribute.

Warning 

Just because you do not see a field on the default forms, do not assume that the field doesn't exist in the database. The default forms contain only some of the attributes for each entity. For example, there are more than 50 Account attributes that do not appear on the default Account form.

Because Microsoft CRM creates up to 15,000 attributes upon installation, we're sure that you're wondering what's the best way to quickly determine which attributes already exist in the system. Microsoft CRM provides two excellent tools to browse the attributes of an entity: the entity editor and the metadata browser.

Entity Editor

To browse the attributes of an entity by using the entity editor, go to the Customization section of Microsoft CRM and click Customize Entities. You'll see a list of all the entities in Microsoft CRM. If you double-click any record, the entity editor appears. Click Attributes to see a list of all the attributes for that entity, as shown in Figure 4-13.

Figure 4-13: Attributes for the Account entity

Before you add a new attribute to an entity, you should review the list of attributes for that entity to make sure that a similar field doesn't already exist. If you want more detail about any one attribute, simply double-click it to open the attribute editor. The attribute editor shows you all of the attribute properties for that attribute, including type, description, schema name, and so on.

Metadata Browser

In addition to the entity editor, you can also use the metadata browser to quickly view all of the attributes for a given entity. To view the metadata browser (as shown in Figure 4-14), use a Web browser to navigate to http://<crmserver>/sdk/list.aspx, where <crmserver> is the name of your server.

Figure 4-14: Metadata browser

This Web-based metadata browser lists only the entities available through the SDK, so there is not necessarily a one-to-one correlation with the list of entities that you'll see in the Customization section. However, you will find all of the system-customizable and custom entities in the SDK list. If you can't find the entity you're looking for, note that the metadata browser displays the entity schema name instead of the name. For example, the metadata browser displays the Address entity under its schema name of customeraddress. To view all of the attributes for an entity, click the icon in the Definition column. The entity navigator page for an entity displays all of the attribute and relationship information on one page, as shown in Figure 4-15.

Figure 4-15: Contact entity navigator in the metadata browser

Depending on the type of attribute information you're looking for, this format might be more convenient for you than using the entity editor. We prefer using the metadata browser for several reasons:

• You can view all of the attributes for an entity on one page.

• You can use Internet Explorer to search on the page (by using Ctrl+F) for specific terms that interest you.

• You can easily (and cleanly) copy and paste all of the entity attributes from the definition detail page into a Microsoft Office Excel worksheet if you want to work with them some more.

Although the metadata browser does list all of an entity's attributes, it unfortunately does not display all of the attribute properties. Some of the important attribute properties not shown in the metadata browser include Display Name, Type Format, and Requirement Level.

Caution 

Because Microsoft CRM stores all of its underlying system data in SQL Server, it is technically possible for you to also view the entity schemas within SQL Enterprise Manager. However, we don't recommend doing this because it creates additional work for you. The entity editor and the metadata browser display the metadata, which automatically consolidates the complex Microsoft CRM data relationships into an easy-to-use format. By viewing the SQL tables directly, you're bypassing the metadata, which means that you have to manually reconstruct where Microsoft CRM stores all of the data, which can be a time-consuming process.

Both the entity editor and the metadata browser give you all of the attributes for an entity, so you simply need to choose the format that you prefer.

Modifying, Adding, and Deleting Attributes

After you've reviewed the entities and you understand their attributes, you're ready to start making some changes. Attribute customizations fall into one of three categories:

• Modifying attributes

• Adding custom attributes

• Deleting attributes

Modifying Attributes

The simplest type of attribute customization you can perform is to modify an existing attribute. When you modify attributes, you actually modify the properties of the attribute. You make changes to the attribute properties in the attribute editor, as shown in Figure 4-16.

Figure 4-16: Attribute editor for Account Number attribute

To change any one of the attribute properties, simply follow these steps.

Modifying an Attribute Property

1. Navigate to the entity that you want to customize, and then click Attributes.

2. Double-click the attribute that you want to modify. The attribute editor appears.

3. Update a value, and then click Save.

4. An "Updating Attribute" message appears. When the message disappears, your change is complete.

As we explained earlier, your users will not see the changes you make until you publish your customizations.

Although Figure 4-16 might not clearly show it, Microsoft CRM shades, or disables, some of the attribute property fields. As you probably expect, the disabled property fields indicate that you cannot edit the attribute properties. You can never edit the schema name or data type for an existing attribute. In addition, Microsoft CRM prevents you from editing attribute properties on the system entities. Of course, these few restrictions help ensure that the software always works correctly and that your system will upgrade smoothly to future releases of Microsoft CRM.

When you're modifying attributes, please take extra care in the following situations:

• Editing maximum length Although you can edit the maximum length property for a nvarchar or ntext attribute, you cannot increase the maximum length value. For example, if the default Microsoft CRM maximum length for an nvarchar or ntext attribute is 100 characters, you can change the maximum length of that attribute only to a value between 1 and 100; you cannot increase the field length to 200 characters.

• Deleting picklist values Take extra care when deleting the picklist values of existing attributes, because you might permanently lose data. Consider a set of 75 records that uses a custom picklist. The picklist contains three options: A, B, and C (with 25 records each). If you delete picklist value A, Microsoft CRM deletes that value from the form so that no new records can select picklist value A. In addition, Microsoft CRM deletes picklist value A from the 25 records that used this value. Those records will display a blank picklist value when you open them. Fortunately, Microsoft CRM reminds you of this data deletion when you attempt to delete a picklist.

Adding Custom Attributes

As you can see, changing the properties of existing attributes really couldn't be any simpler. However, the real customization fun begins when you start adding your own custom attributes. Again, before you add a custom attribute, double check all of the existing attributes for an entity to make sure a similar field doesn't already exist. When you're ready to add a custom attribute, follow these steps.

Adding a Custom Attribute

1. Go to the Customization section of Microsoft CRM and then click Customize Entities.

2. Double-click the entity that you want to modify.

3. In the navigation pane, click Attributes, and then click New in the grid toolbar.

4. Microsoft CRM prompts you to complete the following form.

   

5. Click Save.

To create a custom attribute, you must enter the following attribute properties:

• Display name

• Schema name

• Requirement level

• Type

• Description (optional)

We defined each of these properties earlier in this chapter, but now we'll cover the schema name and type in more detail.

Schema Name The schema name represents the name of the attribute in the metadata. Every custom attribute includes a prefix value within the schema name (such as New_customfield). Microsoft CRM creates the New_ default schema prefix. When you're creating a custom attribute, you'll notice that the schema prefix field is read-only, and you can't edit it.

Tip 

You can change the default schema prefix by navigating to Organization Settings in the Settings section. Click System Settings and then click the Customization tab. The prefix must contain between two and eight alphanumeric characters, and it cannot start with mscrm.

When you enter text in the display name field and you lose focus on the field (by pressing the Tab key or clicking elsewhere in the page), Microsoft CRM automatically fills in the rest of the schema name after the prefix. Because the schema name can consist of alphanumeric and underscore characters only, Microsoft CRM removes any inappropriate characters. When you are creating a schema name, keep the following in mind:

1. Your users will never see the schema name.

2. You cannot change the schema name after you create the attribute.

3. Any advanced customizations you create, such as the SDK code, scripting, and reports, will reference the schema name instead of the display name, so save your developers some keystrokes by keeping the name just long enough to describe its function but not so long that it takes forever to type.

Type When creating new attributes, you can choose from one of eight data types, some of which allow you to further specify how Microsoft CRM should format the data. Table 4-7 summarizes the data types and data formatting options available for custom attributes.

Table 4-7: Data Types and Formats for Custom Attributes

Attribute data type	Format	Description
nvarchar	E-mail	Displays text as a clickable mailto: hyperlink.
	Text	Displays text on one line.
	Text area	Displays a multiline text box with scroll bars.
	URL	Displays text as a live hyperlink. Microsoft CRM automatically adds http:// to whatever the user enters.
	Ticker symbol	Displays text as a live hyperlink that will launch a stock quote request on http://moneycentral.msn.com.
picklist	Picklist	Drop-down list control. You can use the additional buttons to add, modify, and delete picklist values. You can also specify a sort order and assign a default picklist value.
bit	Bit	Displays two possible options on the form. You can change No and Yes to new values such as True and False, and you can specify the order in which the values appear. You can also specify the default value. On the form editor, you can determine whether you want the text to appear with option buttons, a check box, or a drop-down list.
int	None	Whole numbers only (1, 2, 3, and so on). You can also set a minimum and maximum range for this value.
	Duration	Displays a picklist with 23 predefined duration values ranging from one minute to three days.
	Time zone	Displays a picklist from which users can select one of 75 time zones from around the world.
float	Float	Used to store numeric values with a configurable precision (such as 1.23 or 3.145). You can also specify a minimum and maximum range.
money	Money	Used to store currency amounts. You can specify the precision and a minimum and maximum range. If you select this data type, the local currency symbol (for example, $ in the U.S.) appears automatically on the form label.
ntext	None	Displays a multiline text box with scroll bars. You must specify maximum length up to 5,000 characters.
datetime	Date only	Date formatted as MM/DD/YYYY. A calendar control automatically appears on the form.
	Date and time	Date formatted as MM/DD/YYYY HH:MM. A calendar control and time selection drop-down list automatically appear on the form.

Figure 4-17 shows a mockup of how each of these data types would appear to users on the entity form. As you can see, each data type saves and displays information differently, so it's important that you select the appropriate data type for your custom attribute.

Figure 4-17: How different data types and formats appear on an entity form

More Info 

Both the ntext and nvarchar data types store text and numeric data, and both data types format the data on the format by using a text area, so how should you decide which data type to use? For attributes with a length greater than eight characters, the nvarchar data type consumes more bytes in SQL Server. However, data stored using the nvarchar data type provides better performance than data stored using ntext. Therefore, a good rule of thumb is to use the nvarchar data type attributes with up to 200 characters and then use ntext for attributes with more than 200 characters.

As we explained earlier, you cannot modify the maximum length of the nvarchar and ntext attributes, so carefully consider the appropriate length of each attribute when you create it.

Attribute Icons When you view a list of attributes for an entity, you can quickly distinguish the custom attributes that you created from the system attributes by looking at the icon in the far left column. Microsoft CRM displays a different icon for custom attributes than for system attributes, as shown in Figure 4-18.

Figure 4-18: Custom attribute and system attribute icons

Deleting Attributes

Because it's easy to add to custom attributes, you might find yourself getting a little overzealous and adding more attributes than you need. Of course, you could simply remove any unused attributes from an entity's form, but they will still appear in Advanced Find, SDK, database and filtered views, and so on. If these extra attributes bother you and you decide to delete old or unused custom attributes, you'll find the process very simple.

Warning 

Deleting a custom attribute also deletes all of the data stored in that field, and you cannot retrieve that data later. Make sure to take the appropriate steps to back up all of your data before deleting an attribute.

Before you delete an attribute, make sure that you remove any existing references to that attribute from Microsoft CRM. To remove references to an attribute, you should remove the attribute from the following:

• The entity's form. Then you can publish the form.

• Any reports that contain the attribute.

• Any filter criteria used in views.

• Any script or code references.

Fortunately, Microsoft CRM does most of the hard work for you by automatically checking all the forms and views in the system. If you miss a reference of an attribute you're trying to delete, you'll see an error message like the one shown in Figure 4-19.

Figure 4-19: Error message shown when you attempt to delete a referenced attribute

Even though Microsoft CRM checks the forms and views for references to deleted attributes, you're on your own to scrub the reports and code to remove any references to the deleted attribute.

After you're certain that you removed all references to the attribute, you can delete the attribute by following these steps.

Deleting a Custom Attribute

1. Go to the Customization section of Microsoft CRM, and then click Customize Entities.

2. Double-click the entity of the attribute that you want to delete.

3. Click Attributes, and then select the custom attribute to remove.

4. In the grid toolbar, click Delete.

5. A warning appears that says, "Deleting this attribute will result in loss of all data stored in it. Continue with the deletion of the attribute?" Click OK.

Attributes and Closing Dialogs

Closing dialogs present a special case you need to consider when you're customizing entity attributes. A closing dialog is a dialog box that appears when a user takes one of the following actions:

• Closes an activity such as Task or Phone Call

  

• Converts a Lead

  

• Closes an Opportunity

  

• Resolves a Case

  

• Converts a Campaign Response

  

When a user initiates one of these actions, a closing dialog prompts the user to specify how he or she wants to close the entity. It might not be obvious where you should customize the closing dialog picklist values because these closing dialogs aren't entity forms; however, they do display attributes of the entity. To edit the closing dialog picklist values, you must modify the statuscode attribute (Status Reason display name) of the entity you're closing. We'll quickly show you how to edit the closing dialog values for the Phone Call entity, and then you can apply the same concept and process to the other closing dialogs referenced in the preceding list.

Important 

For entities that users can close in Microsoft CRM (such as the Phone Call), the statuscode attribute behaves a little differently than a standard picklist attribute. In these examples, you can specify different picklist values for each statecode value (Activity Status display name) where most picklists contain only one range of values. You can specify different statuscode picklist values for each of the three statuscode values: Open, Completed, and Canceled.

Editing the Phone Call Closing Dialog Values

When you close activities such as Tasks and Phone Calls, a closing dialog appears in which the user determines whether he wants to mark the activity Completed or Canceled. The following procedure explains how to customize those picklist values.

1. Go to the Customization section of Microsoft CRM, and then click Customize Entities.

2. Double-click the Phone Call entity.

3. In the navigation pane, click Attributes, and then double-click the statuscode schema name. The attribute editor appears.

   

4. In the State list, select Completed. The picklist values change from the Open value (Open) to the Completed values (Sent, Received).

5. Click Add, and then in the Label field, type Left Message. Click OK.

   

6. In the State list, click Canceled. Then click Add, and in the Label field, type Wrong Number. Click OK. You will see that the Wrong Number picklist value is added under the Canceled value.

   

7. In the attribute editor toolbar, click Save and Close.

8. In the Phone Call entity editor menu bar, click Actions, and then click Publish.

9. Now when your users close a Phone Call activity, they will see the following closing dialog that incoporates your new customizations.

   

Important 

If users click the Save As Completed button on the entity toolbar, they will not see the closing dialog. In this case, Microsoft CRM uses the picklist value that you specify as the default value of the Completed state. Because most users will probably click the Save As Completed button, make sure you choose the default value that you want.