You can customize the contents of the Navigation Pane, for example, add or edit areas, in Microsoft Dynamics CRM 4.0 by editing the Site Map. The Site Map is an XML document, and if you've never edited an XML document before, using tools that provide schema validation can make this much easier.
Applies To
Microsoft Dynamics CRM 4.0
Introduction
You can customize the contents of the Navigation Pane in Microsoft Dynamics CRM by editing the Site Map. The Site Map is an XML document, and if you've never edited an XML document before, using tools that provide schema validation can make this much easier.
Some of the customizations you can perform include:
- Change the name of areas in the Navigation Pane
- Change the order of areas in the Navigation Pane
- Reorganize or add new areas
- Change the order of the links presented within areas
- Change the names of links in an area
- Group links in areas
- Change the Workplace profile options that people can choose from
To perform these customizations, you must have the necessary privileges to export and import customizations.
Additional information related to this task can be found in the Microsoft Dynamics CRM 4.0 Software Development Kit (SDK).
SiteMap
The Site Map is a part of the customizations.xml document that is the result of exporting customizations. Customizations.xml is exported as a compressed customizations.zip file.
The process of customizing the Site Map consists of the following steps:
- Export the Site Map as part of the customizations.zip file
- Extract the customizations.xml file from the exported customizations.zip file
- Edit the Site Map Element in the customizations.xml file
- Import the edited customizations.xml file.
Exporting the Site Map
-
In the Navigation Pane, click Settings, click Customization, and then click Export Customizations.
-
In the View drop-down, select Client Extensions.
-
In the list, select Site Map.
-
Click Export Selected Customizations and then click OK to close the notice about information that may be exported.
-
Click Save and save the customizations.zip file to a location of your choice.
-
Click Close.
After you modify the Site Map element in the customizations.xml file, you import the modified customizations.xml file to apply your changes.
Importing the Site Map
-
In the Navigation Pane, click Settings, click Customization, and then click Import Customizations.
-
Click Browse to locate an XML file or a compressed (.zip) file that contains customizations and settings exported from Microsoft Dynamics CRM.
-
Double-click the file or select the file, and then click Open.
-
Click Upload.
If the Site Map cannot be successfully processed, a dialog box will display error messages.
Recovering from Errors
If you import a customizations.xml file that contains an incorrect Site Map, Microsoft Dynamics CRM will ignore your customizations and use the default Site Map and display a message that there is an error in the customized Site Map. In this case you should navigate to the Import Customizations area and import your backup customizations.xml file containing a correct Site Map.
Worst-case scenario
There is a slight chance that an error in the Site Map could cause the Navigation Pane to not render correctly and it could become impossible to navigate to the Import Customizations area to fix the problem. In this event, you can access the Import Customizations area directly.
To do this, type the following URL into the address field of Internet Explorer:
http://<CRM_Servername>/<Organization_name>/tools/systemcustomization/ImportCustomizations/importCustomizations.aspx
Locate your backup copy of the exported XML file. Upload and import this backup file to return to your original working state. You can then use the Navigation Pane again.
It is always a good idea to keep a backup of a known, working customizations.xml file that contains a valid Site Map. The customizations.zip file that was exported provides this; be sure to keep it handy.
Site Map Schema Overview
Before you can edit the Site Map, you must understand the structure of the XML. By opening the customizations.xml file in Internet Explorer you can review the structure of the XML contents. This file represents a customizations.xml that includes the default Site Map. You may want to review this file to better understand the Site Map schema.
Like any valid XML document, the Site Map must conform to a specific structure. The Site Map uses an XML schema, which is an XML file that defines structure and uses the file extension .xsd. The Site Map schema is defined in a file called SiteMapType.xsd.
When viewed in Microsoft Visual Studio, the graphical view of the schema looks like the following illustration.
There are three major elements in the Site Map.
Area
The Area element controls the major sections visible in the bottom of the Navigation Pane. The default Areas are Workplace, Sales, Marketing, Service, Settings, and Resource Center.
Group
The Group element is a child of the Area element. The Group element provides divisions in which to group the SubArea elements in the top. Most areas don't use Groups by default. The exception is the Workplace area. The Workplace area has six default Groups; My Work, Customers, Sales, Marketing, Service, and Scheduling.
The Workplace area is also unique because the groups in this area can be configured as optional. Users can select which groups they will see in the Workplace area if they click the Personalize Workplace link at the bottom of the Workplace area.
SubArea
The SubArea element provides the clickable links that change the content displayed in the main pane of the application. By default, most links in the Navigation Pane point to pages in the Microsoft Dynamics CRM application. One exception is the Resource Center, which creates links to pages on the Internet.
There are also five minor elements
Titles and Title
With the Titles and Title elements you can control the localized text Titles to be added in different languages. The Titles element contains one or more Title elements. If you want to rename an existing Area, Group, or SubArea, define your Titles for the language that you want. Use the same method to add titles to new elements. Languages are identified using the locale ID (LCID) attribute, which is a four-digit number. For example, the LCID for US English is 1033. You can find valid LCID values for other languages at the Locale ID (LCID) Chart.
Because Microsoft Dynamics CRM supports a multilingual user interface, the Title text displayed for Areas, Groups, and SubAreas may need to be presented in different languages for different users. The Microsoft Dynamics CRM multilingual functionality is managed by internal resources designated by ResourceId attributes in the Area, Group, and SubArea elements. Therefore, the default Site Map doesn't use any Titles or Title elements and you shouldn't use the ResourceId attributes for your customizations.
Descriptions and Description
Descriptions can be added to Areas, Groups, and SubAreas. Descriptions only appear in Microsoft Dynamics CRM for Microsoft Office Outlook.
The Descriptions element contains one or more Description elements. Each Description contains attributes to assign an LCID and text for the description.
Privilege
The Privilege element is a child element of the SubArea element. This element defines specific privileges required to view the SubArea. You might use this if you create a SubArea that points to a page that requires special privileges to view.
Privileges are defined as the name of an entity and a comma-separated list of values representing actions.
The following example is a Privilege. The Privilege element will prevent users (who do not have permissions to read, write, and create knowledge-base articles) from seeing the SubArea.
<SubArea Id="nav_managekb"
ResourceId="Homepage_KBManager"
Icon="/_imgs/ico_18_126.gif"
Url="/cs/home_managekb.aspx"
Client="Web">
<Privilege Entity="kbarticle"
Privilege="Read,Write,Create" />
</SubArea>
Editing the Site Map
When exported, the Site Map is in a compressed file called customizations.zip. From this file you extract the customizations.xml file that contains the Site Map.
The valid elements and attributes to use for the Site Map are fully documented in the Microsoft Dynamics CRM SDK. For more information, see Application Navigation Configuration (Microsoft Dynamics CRM SDK) and SiteMap XML Reference (Microsoft Dynamics CRM SDK).
Applications for editing XML documents
Because XML files are simple text, they can be edited with a variety of text-editing programs. Many people who are familiar with editing XML files use Notepad.
If you are not familiar with editing XML files that match a specified schema, you may want to use an XML editing tool that provides schema validation. Two free applications that support schema validation are Microsoft Visual Web Developer 2008 Express Edition and XML Notepad 2007.
Microsoft Visual Web Developer 2008 Express Edition has many of the capabilities of Microsoft Visual Studio and includes many features for developing Web applications. It is a large application that might take an hour to download and install. It provides schema validation in a text view using IntelliSense, which provides guidance as you type. Errors or missing required elements are underlined.
XML Notepad 2007 is a small application for editing XML files. It has a tree-view interface of the nodes for an XML document.
For links to download these applications, see the Related Links section later in this document.
Note :
Although the Import Customizations feature does perform validation of the modified customizations file, it is possible that the validation will not detect every error. An error can break the Microsoft Dynamics CRM Navigation Pane. If so, you would need to use the steps described in "Recovering from Errors" earlier in this document to return to your starting point. If you are not familiar with editing XML documents that must conform to a specified schema, it is highly recommended that you use an application that supports schema validation.
It is also a very common practice to copy and paste existing elements as a starting point to get the correct structure, and then make the necessary changes to ensure that you are conforming to schema requirements and getting the outcome you want.
Using Schema Validation
The Site Map is just one of the items that may be exported in the customizations.xml file. To edit the customizations.xml file with schema validation, you need a schema that represents all the possible contents of the customizations.xml file. The XML schema definition (XSD) for the customizations.xml file is the customizations.xsd file. The customizations.xsd schema includes a reference to the SiteMapType.xsd file as well as the isv.config.xsd file, as shown in the following illustration.
This allows the customizations.xsd file to provide a schema for all customizations that are exported from Microsoft Dynamics CRM. However, the way that the customizations.xsd references the SiteMapType.xsd in the _root folder introduces several additional steps before it can be used for XML validation.
For convenience, this article provides a modified version of the customizations.xsd called ISVConfigAndSiteMap.xsd. The ISVConfigAndSiteMap.xsd file simply consolidates the customizations.xsd, the SiteMapType.xsd, and the Isv.config.xsd files into one file. It also removes some references to Site Map element attributes that were deprecated for Microsoft Dynamics CRM.
When you use Microsoft Visual Web Developer 2008 Express Edition (or other Microsoft Visual Studio editions), you can link an exported customizations.xml file to the ISVConfigAndSiteMap.xsd to get IntelliSense, which will help you understand the valid schema elements and avoid mistakes. This isn't required, but it does make the job of modifying the XML easier.
To begin editing the files
Export the Site Map and extract the customizations.xml file from the customizations.zip file.
Remember to keep that customizations.zip file as your backup.
Download this ISVConfigAndSiteMap.zip file. Extract the ISVConfigAndSiteMap.xsd file and place it in the same folder as the customizations.xml file.
Editing the Customizations.xml File using Microsoft Visual Web Developer 2008 Express Edition
These steps introduce the process of editing XML documents with schema validation. This example begins by adding a new Area element to the Site Map to introduce how Microsoft Visual Web Developer 2008 Express Edition uses IntelliSense to provide schema information as you type.
Edit XML documents with schema validation
Open Microsoft Visual Web Developer 2008 Express Edition and from the File menu, select Open File….
Select the customizations.xml file and click Open.
In the View menu, select Properties Window.
In the Properties area, select the Schemas box and type ISVConfigAndSiteMap.xsd and press Enter.
Locate the Resource Center Area in the customizations.xml and place the cursor after the Area ending tag: "
</Area>".Type the
<symbol to use IntelliSense to see the valid options for this area of the document.You should see this:
Area is the only valid element in this part of the document.
Type A to select the Area element and press Enter.
Press the spacebar to add a space.
You should see a list of valid attributes for the Area element
Type I and then press the down arrow key to select Id and then press Enter. You are now ready to enter the value for the attribute.
The Id attribute requires a unique string value.
To understand schema errors, place your cursor over the text underlined in red.
Both of these errors indicate that the Area tag is not closed. The error information will disappear when the tag for the Area element and any required attributes are provided. For example:
<Area Id="my_unique_ID_value"></Area>
Continue to define your elements. Use the information in the SiteMap XML Reference (Microsoft Dynamics CRM SDK) and the schema validation in IntelliSense to define the appearance and behavior for the elements.
Save your changes when you are finished and import your customizations.xml file.
Editing the customizations.xml file using XML Notepad 2007
These steps introduce the process of editing XML documents with schema validation. This example begins by adding a new Area element to the Site Map to introduce how XML Notepad 2007 uses a tree view and a graphical user interface (GUI) to provide structure for editing XML documents.
Edit XML documents with schema validation
Open XML Notepad 2007 and from the File menu select Open.
Select the customizations.xml file and click Open.
In the View menu, select Schemas.
In the XML Schemas dialog box, from the File menu, select Add Schemas.
Browse to the ISVConfigAndSiteMap.xsd, select it, and then click Open.
Click OK.
In the Tree View tab, expand the SiteMap node and select the last Area element.
Right-click the Area node and select Element > After from the context menu.
Any valid element names appear in a box. Select the Area element.
The Error List area has the description of "The required attribute 'Id' is missing." This indicates that a valid Area element must have an Id attribute.
To add an attribute, right-click the Area element you created and select Attribute > Child from the context menu.
Select Id from the list of available attributes
- The last four items in the list are not valid attributes. Type, nil, schemaLocation, and noNamespaceSchemaLocation are not relevant when editing the Site Map. These options are provided by XML Notepad 2007.
- The Error List area provides the description of "The 'Id' attribute is invalid – The value '' is invalid according to the datatype 'CRM_Identifier_SiteMap' – The Pattern constraint failed." This indicates that a valid Area element Id attribute must have a value.
- The last four items in the list are not valid attributes. Type, nil, schemaLocation, and noNamespaceSchemaLocation are not relevant when editing the Site Map. These options are provided by XML Notepad 2007.
Type a unique value for the Area Id attribute value.
Continue to configure the necessary elements and attributes to achieve your goal. Use the options provided by schema validation and the information in the SiteMap XML Reference (Microsoft Dynamics CRM SDK).
Save your changes and import your customizations.xml file to see your changes.
Tasks
These are some of the tasks you can perform by configuring the Site Map
Change the name of areas in the Navigation Pane
If you want to change the name of the Service area from "Service" to "Support" for the English Language:
Change this:
<Area Id="CS" ResourceId="Area_Service" Icon="/_imgs/services_24x24.gif"
DescriptionResourceId="Customer_Service_Description">
<Group Id="CS">To this:
<Area Id="CS" ResourceId="Area_Service" Icon="/_imgs/services_24x24.gif"
DescriptionResourceId="Customer_Service_Description">
<Titles>
<Title LCID="1033" Title="Support"/>
</Titles>
<Group Id="CS">
You don't need to remove the ResourceId attribute. Adding the Titles element will override it.
Change the order of areas in the Navigation Pane
This is simply a matter of manipulating the order in which the areas in the Site Map are listed in the customizations.xml file.
Reorganize or add new areas
SubArea elements can be copied and pasted into different areas to achieve a different organization.
Creating new areas is usually a matter of copying an existing Area and making modifications.
Be aware that each major element must have a unique Id attribute value. If you copy a SubArea element from one Area element and paste it into another, you must give it a different and unique Id attribute value if the other SubArea still exists.
Change the order of the links in areas
You can change the order in which the SubArea elements are listed in the Areas element.
Change the names of links in an area
Most of the links created by SubArea elements are actually views of specific entities, such as Leads or Opportunities. The way to change the names of those links is to change the Display Name of the entity. Those changes will be reflected in the Navigation Pane because the SubArea is associated with a specific entity using the Entity attribute. For information about changing the names of entities, see State your terms: Use your organization's nomenclature.
However, for SubArea elements not associated with a particular entity, you can change the name. For example, if you want to change the name of the Product Catalog area in the Settings area to "Product List", add the Titles element as shown here.
<SubArea Id="nav_productcatalog" ResourceId="Homepage_ProductCatalog"
DescriptionResourceId="ProductCatalog_SubArea_Description"
Icon="/_imgs/ico_18_productcatalog.gif"
Url="/tools/productcatalog/productcatalog.aspx"
AvailableOffline="false">
<Titles>
<Title LCID="1033" Title="Product List"/>
</Titles>
<Privilege Entity="product" Privilege="Read" />Depending on the application that you use to edit XML files, you can usually locate a known area of the XML file quickly by using CTRL+F to find a specific word in the file.
Group links in areas
Group elements provide a way to group SubArea elements with collapsible rows. By default, only the Workplace area uses Group elements, but any Area can use Group elements. However, you must be sure to set the ShowGroups attribute in the Area to "true" for the Groups to appear. Also, the IsProfile attribute only applies to Groups located in the Workplace area.
For example, you can break up the SubArea elements in the Service area into two groups.
Change this:
<Area Id="CS" ResourceId="Area_Service" Icon="/_imgs/services_24x24.gif"
DescriptionResourceId="Customer_Service_Description">
<Group Id="CS">
<SubArea Id="nav_apptbook" ResourceId="Homepage_AppointmentBook"
DescriptionResourceId="AppointmentBook_SubArea_Description"
Icon="/_imgs/ico_18_servicecal.gif" Url="/sm/home_apptbook.aspx"
AvailableOffline="false">
<Privilege Entity="activitypointer" Privilege="Read" />
<Privilege Entity="service" Privilege="Read" />
</SubArea>
<SubArea Id="nav_cases" Entity="incident"
DescriptionResourceId="Cases_SubArea_Description" Url="/CS/home_cases.aspx" />
<SubArea Id="nav_accts" Entity="account" DescriptionResourceId="Account_SubArea_Description" />
<SubArea Id="nav_contacts" Entity="contact" DescriptionResourceId="Contact_SubArea_Description" />
<SubArea Id="nav_managekb" ResourceId="Homepage_KBManager"
DescriptionResourceId="KBManager_SubArea_Description" Icon="/_imgs/ico_18_126.gif"
Url="/cs/home_managekb.aspx" AvailableOffline="false">
<Privilege Entity="kbarticle" Privilege="Read,Write,Create" />
</SubArea>
<SubArea Id="nav_contracts" Entity="contract"
DescriptionResourceId="Contract_SubArea_Description" />
<SubArea Id="nav_products" Entity="product" DescriptionResourceId="Product_SubArea_Description" />
<SubArea Id="nav_services" Entity="service" DescriptionResourceId="Service_SubArea_Description" />
</Group>
</Area>To this:
<Area Id="CS" ResourceId="Area_Service" Icon="/_imgs/services_24x24.gif" ShowGroups="true"
DescriptionResourceId="Customer_Service_Description">
<Group Id="CS">
<Titles>
<Title LCID="1033" Title="Group 1"/>
</Titles>
<SubArea Id="nav_apptbook" ResourceId="Homepage_AppointmentBook"
DescriptionResourceId="AppointmentBook_SubArea_Description"
Icon="/_imgs/ico_18_servicecal.gif" Url="/sm/home_apptbook.aspx"
AvailableOffline="false">
<Privilege Entity="activitypointer" Privilege="Read" />
<Privilege Entity="service" Privilege="Read" />
</SubArea>
<SubArea Id="nav_cases" Entity="incident"
DescriptionResourceId="Cases_SubArea_Description" Url="/CS/home_cases.aspx" />
<SubArea Id="nav_accts" Entity="account" DescriptionResourceId="Account_SubArea_Description" />
<SubArea Id="nav_contacts" Entity="contact" DescriptionResourceId="Contact_SubArea_Description" />
</Group>
<Group Id="CS_New_Group">
<Titles>
<Title LCID="1033" Title="Group 2"/>
</Titles>
<SubArea Id="nav_managekb" ResourceId="Homepage_KBManager"
DescriptionResourceId="KBManager_SubArea_Description" Icon="/_imgs/ico_18_126.gif"
Url="/cs/home_managekb.aspx" AvailableOffline="false">
<Privilege Entity="kbarticle" Privilege="Read,Write,Create" />
</SubArea>
<SubArea Id="nav_contracts" Entity="contract"
DescriptionResourceId="Contract_SubArea_Description" />
<SubArea Id="nav_products" Entity="product" DescriptionResourceId="Product_SubArea_Description" />
<SubArea Id="nav_services" Entity="service" DescriptionResourceId="Service_SubArea_Description" />
</Group>
</Area>The changes are as follows:
- The Area element includes the attribute ShowGroups="true"
- Both Group elements now include a Title in a Titles element.
- The new Group has a unique value for the Id attribute.
- Some of the SubArea elements have been moved into the new Group.
- The Area element includes the attribute ShowGroups="true"
Change the Workplace profile options that people can choose from
When you add groups to the Workplace area, you can set the IsProfile attribute to "true". This will allow users to choose whether they want this group to be displayed in their Workplace area, in their personal options.
