Entity Customization: Relationships, Custom Entities, and Site Map

Application Navigation

Because of the flexibility and power of custom entities, you will find yourself creating multiple custom entities in your Microsoft CRM system. Simple deployments might use just a few custom entities, but a complex deployment might contain 25, 50, or 100 custom entities! By default, Microsoft CRM adds custom entities to the user interface and site navigation in the order in which you create them, listing the first custom entity at the top of the list. In addition, Microsoft CRM lists the custom entities together under an extensions group in the navigation pane. If you use more than a handful of custom entities, you will want to alter where and how they appear in the user interface. Microsoft CRM uses multiple tools to configure how users access entities and navigate in the application. These application navigation customization tools include:

1. Site map
2. Entity display areas
3. ISV.config

Microsoft CRM combines data from these three tools to create the user interface on a system-wide level. After it determines the system navigation, Microsoft CRM also provides a Personalize Workplace feature in which individual users can customize the groups that appear in their workplaces. Before we discuss what each application navigation tool configures, let's quickly review the Microsoft CRM terminology for the screen region names in the Web application and the Microsoft CRM client for Outlook application. Use the following figures and list to map the screen regions to their names.
Figure 6-26 shows the user interface screen regions.

1. Application menu bar
2. Application toolbar
3. Grid tool bar
4. Application navigation pane
5. Wunderbar

6. Entity menu bar

7. Entity toolbar
8. Entity navigation pane

Table 6-6 summarizes which customization tool you should use to modify the Microsoft CRM application navigation, depending on the type of customization that you want to make and where in the application navigation that customization resides.

These four tools allow you to customize almost every part of the user interface. In general, the site map allows you to add, reorder, and remove items in the application navigation pane and the wunderbar. Use ISV.config to add new links and buttons to the application menu bar and toolbar, in addition to adding new links and buttons to individual entities.

More Info You might be wondering, what does ISV.config mean, anyway? Unlike the site map, the name of the ISV.config feature does not exactly indicate its purpose. Microsoft CRM 3.0 uses the ISV.config terminology as a carryover from earlier versions of Microsoft CRM. The ISV.config file originally allowed independent software vendors (ISVs) to configure their enhancements in the Microsoft CRM interface. The term ISV refers to third-party companies that develop software enhancements and add-ons for the Microsoft CRM platform. Although ISVs do make heavy use of the ISV.config file, customers can also use ISV.config for their own internally developed customizations and enhancements. Because the ISV.config file deals mostly with extending Microsoft CRM, we discuss how to work with it in Chapter 10 along with the other extension features.

Now that you understand which tools to use to customize the navigation components of Microsoft CRM, let's discuss the details of how to edit the site map and Personalize Workplace features.

Modifying the site map allows you to customize the user interface of the application navigation pane, the wunderbar, and parts of the application menu bar. As we discussed earlier, if you add more than a few custom entities, you will probably want to modify the site map so that your custom entities appear exactly where you want them in the user interface. Conceptually, the site map is just an .xml file that you edit (with the XML editing tool of your choice) to configure different parts of the Microsoft CRM navigation. Before we explain how to edit the site map, it will help to further define the screen components in the application navigation pane and the wunderbar (as shown in Figure 6-28) because the site map uses new terms to describe these areas of the user interface.

Microsoft CRM displays five buttons in the wunderbar by default:

1. Workplace
2. Sales
3. Marketing
4. Service
5. Settings

When you are working with the site map, Microsoft CRM refers to these five buttons as areas. When users click an area, Microsoft CRM updates the application navigation pane to show the appropriate links for that area. As the example in Figure 6-28 shows, the Workplace area contains three main elements:

1. My Work
2. Customers
3. Marketing

The site map refers to these elements as groups. Microsoft CRM formats groups in the Web client's application navigation pane with bold text and with the expand/collapse control.

Within each group are additional links that the site map refers to as subareas. For example, the My Work group in Figure 6-28 includes six subareas:

1. Activities
2. Calendar
3. Queues
4. Articles
5. Reports
6. Announcements

In addition to updating the application navigation pane and the wunderbar, editing the site map concurrently updates the Go To menu on the application menu bar. Figure 6-29 shows the Go To menu for our example.

As you can see, the application menu bar lists the same areas that appear in the wunderbar (and in the same order). In addition, the application menu bar also displays all of an area's subareas nested in the menu. However, you will notice that the application menu bar does not display the group name. Instead of the group name, Microsoft CRM displays a horizontal line to graphically divide the groups.

Important Editing the site map updates the Web client's application navigation pane, the wunderbar, and the Go To menu in the application menu bar all at the same time.
We also want to show you how the site map references screen regions in the context of the Outlook client. Although the Outlook client uses some of the same screen region names as the Web client, it also includes a few unique region names. Figure 6-30 shows the Microsoft CRM desktop client for Outlook, and the region names are identified in the subsequent list.

1. Application toolbar

2. Microsoft CRM folder

3. Areas
4. Groups
5. Icon
6. Description

You can see that the Outlook client displays areas and subareas in the Outlook navigation pane as folders instead of as the buttons and links that the Web client uses.

Important Remember that the Web client and the Outlook client share the same site map to configure the application navigation. Therefore, you should always consider how changes you make in the site map will appear to Web and Outlook users.

Now that you understand the terminology that Microsoft CRM uses for the site map, we'll show you how to modify it to meet your needs. As we explained earlier, the site map is simply an .xml configuration file that you manually edit. To get a copy of the current site map of your deployment to edit, you must export it from Microsoft CRM. As with any customization, you export the site map by browsing to Settings, clicking Customization, and then clicking Export Customizations. Select the Site Map record, click More Actions in the grid toolbar, and then click Export Selected Customizations. Microsoft CRM prompts you to open or save the file, as shown in Figure 6-31.

Because you want to edit the site map file, you should save a copy to your local drive. Best Practices Microsoft CRM uses customizations.xml as the default file name for all exported customizations. When you export the site map customizations, a best practice is to rename the customizations.xml file to Sitemap.xml. Although it is not required, using this naming convention makes the contents of the file obvious to you and others.

You can edit .xml files by using any text editor, such as Notepad or WordPad, but using an XML-specific editor such as Microsoft Visual Studio .NET 2005 makes the editing process much easier because you can expand and collapse the different XML elements. You can use Microsoft Internet Explorer to view an .xml file (as shown in Figure 6-32), but you won't be able to edit it there.

Microsoft CRM creates a sitemap.xml file with the XML structure shown in Figure 6-33.

Only the SiteMap element in the Sitemap.xml file will contain any data. The Entities, Entity-Maps, and EntityRelationships elements should be empty. Let's discuss each of the SiteMap elements and its attributes in detail.

SiteMap It might seem a little confusing initially, but Microsoft CRM uses the name SiteMap as the root node of the SiteMap element (illustrated in Figure 6-33). Your Sitemap.xml file can include only one occurrence of the SiteMap node under the SiteMap elements. Table 6-7 lists the only attribute for the SiteMap node.

The SiteMap Url attribute lets you display the Web page of your choice when users click the Microsoft CRM folder in the Outlook client. Figure 6-34 shows an example in which we specified the URL http://sharepoint to display a Microsoft SharePoint intranet Web site.

To implement the example in Figure 6-34, you would change the SiteMap node from the default value. Simply add the Url attribute to the node so that it looks like the following sample. In the real world, you might want to display a custom Web page that you created, or perhaps some other intranet site. Note that changing this attribute affects both the laptop and desktop Outlook clients, but it does not affect users who access Microsoft CRM through the Web client. Area The default sitemap.xml file includes five area elements (Workplace, Sales, Marketing, Service, and Settings), and you can modify, reorder, or remove any of these areas. You can also add entirely new areas to the Microsoft CRM navigation by adding new area elements to sitemap.xml. Remember, Microsoft CRM displays areas in the wunderbar, the application menu bar, and in the Outlook client folders. Caution Although you can technically remove the Settings area from the application navigation by removing it from the site map, you might accidentally lock yourself out of the customizations section by doing so. Therefore, we strongly recommend that you never remove the Settings area from the site map. If you do not want users to see this area in the application navigation, you should change their security role settings instead of modifying the site map. Table 6-8 lists the attributes for the Area node

Group Within each area of the site map, you can specify multiple groups (or no groups at all). Groups allow you to categorize the subareas in a manner that makes the most sense for your end users. The Group element in Sitemap.xml uses the attributes listed in Table 6-9.

Most of these attributes behave in exactly the same way as the Area element's attributes. We want to highlight one attribute unique to the group element: IsProfile.

When users navigate to the Workplace area, they can click a Personalize Workplace link in the navigation pane. Microsoft CRM displays the dialog box shown in Figure 6-35.

In this dialog box, users can select the groups that they want to see in their personal workplaces. Changing the groups displayed affects what they will see, but it does not affect what other users see.

Tip The Microsoft CRM user interface uses the phrase "Select Workplace Areas," but users actually select which workplace groups they want to display.

Microsoft CRM does not display all of the groups in the Personalize Workplace area; it shows only groups with an IsProfile attribute value of true. So if you want a particular group in the Workplace area to always appear for all users, set the IsProfile attribute of the group to false so that Microsoft CRM won't allow users to deselect the group in the Personalize Workplace area.

Tip Although users can personalize their workplace only by using the Web client, their changes will also appear in their Outlook client.

SubArea Each group element in the sitemap.xml file can contain multiple SubArea elements (or no SubAreas elements at all). SubArea elements possess the attributes shown in Table 6-10.

Privilege The last element of the sitemap.xml document is the Privilege element. Each SubArea element can include only one Privilege element, and using the Privilege element within a SubArea element is optional. The Privilege element allows you to specify security criteria that Microsoft CRM evaluates to determine whether it will display a subarea to a user.

It's important to note that the Privilege element does not override the Microsoft CRM security settings for custom and system entities. Therefore, even if you tried to assign display (read) rights to a user by adding a site map privilege, the Microsoft CRM security settings would not display the subarea to a user who did not have read rights to that entity.

So if the Microsoft CRM security settings always make the final determination on whether to display a subarea to a user, you might wonder why anyone would ever need to use a Privilege element. We think the most obvious benefit of the Privilege element is that you can use it to configure security display rights for custom Web pages that you integrate with Microsoft CRM (which you cannot do by using the native Microsoft CRM security settings).

The Privilege element has the attributes listed in Table 6-11.

Let's look at an example that uses the Privilege element.



In this example, if the user had Delete or Write privileges for the account entity, Microsoft CRM would display the subarea in the application navigation pane. Conversely, if you added the custom Web page Custompage.aspx to your system and you didn't want a particular user to see this page, you would simply use the Privilege element in your site map to specify a security privilege that you knew the user didn't have. If you don't specify a Privilege attribute, Microsoft CRM defaults to the Read privilege of the entity.


In this example, if the user had Read rights to the Account entity, Microsoft CRM would display the subarea.

Editing the sitemap.xml file might initially appear as a very straightforward process, but here are a few tips and tricks that might save you some time:

Editing the order of elements in the site map works only in the Web client The Microsoft CRM Web client displays navigation elements (such as subareas) in the order that you specify in the site map. However, the Microsoft CRM Outlook clients use folders to display the navigation. Outlook always displays folders in alphabetical order, not in the order that you specified in the site map.

Don't confuse the Title and Description attributes It's easy to confuse what the Title and Description attributes do. The Description attribute appears only in the Microsoft CRM Outlook client; the Title attribute appears in both the Web and Outlook clients

Watch out for default attributes When we first opened the Sitemap.xml file to edit the name of a group or area (such as Sales), we looked for the text "Sales" so that we could change it. However, that text does not appear in the default sitemap.xml file. Instead, the Area element for sales looks like the following.

<Area Id="SFA" ResourceId="Area_Sales" Icon="/_imgs/sales_24x24.gif"
 DescriptionResourceId="Sales_Description">

It isn't obvious what text you need to change because the word that we want to update ("Sales") does not appear anywhere in this element. To change the text to a new value, you must add a Title attribute to the Area element.

<Area Id="SFA" ResourceId="Area_Sales" Icon="/_imgs/sales_24x24.gif"
 DescriptionResourceId="Sales_Description" Title="New Sales Title">

Id attributes must be unique Each element requires an Id attribute. Remember that it must be unique from all of the other Id attributes in the site map

As you learned earlier in this chapter, custom entities allow you to select the areas where you want Microsoft CRM to display your custom entities. You select or clear the appropriate areas by using the entity editor in the Web client, as shown in Figure 6-36

When you select new areas or remove existing areas with the entity editor, Microsoft CRM automatically edits the site map for you. Because of this nuance, you should always export the site map before you edit it to make sure that you are working with the latest version.

Conversely, editing the different areas of the site map to include different entities and then importing the new file will automatically update the custom entity in Microsoft CRM. Therefore, the display area check boxes will update accordingly the next time you access this Web page.