遙[言]糖

FW : Edit your Site Map

You can customize the contents of the Navigation Pane in Microsoft Dynamics CRM Online 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

The requirements to perform these customizations are that you have the necessary privileges to export and import customizations.

Additional information related to this task can be found in the Microsoft Dynamics CRM SDK.

On This Page

Site Map

Recovering from errors

Site Map schema overview

Editing the Site Map

Using schema validation

Tasks

Summary

Site Map

The Site Map is a part of the customizations.xml document that is the result of exporting customizations.

Exporting the Site Map

1. In the Navigation Pane, click Settings, click Customization, and then click Export Customizations.
2. In the View drop-down, select Client Extensions.
3. Select Site Map.
4. Click Export Selected Customizations and then click OK to close the notice about information that may be exported.
5. In the File Download dialog, click Save and save the customizations.zip file to a location of your choice.
6. Click Close to close the Download Complete dialog.

After you modify the XML contents of the Site Map, you import the modified customizations.xml containing the Site Map to apply your changes.

Importing the Site Map

1. In the Navigation Pane, click Settings, click Customization, and then click Import Customizations.
2. Click Browse to locate an XML file or a compressed (.zip) file that contains customizations and settings exported from Microsoft Dynamics CRM Online.
3. In the Choose File dialog, double-click the file or select the file and click Open.
4. Click Upload.

   After the file is processed, if the Site Map could not be successfully processed, a dialog box will display error messages.

Top

Recovering from errors

If you import a customizations.xml file that contains an incorrect Site Map, Microsoft Dynamics CRM Online will fall back to 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 back-up customizations.xml file containing a correct Site Map.

Worst-case scenario

There is a slight chance that the error 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. Be prepared for this by knowing how you can access the Import Customizations area directly.

To access the Import Customizations area directly, type the following URL into the address field of Internet Explorer:

https://<Organization_name>.crm.dynamics.com/tools/systemcustomization/ImportCustomizations/importCustomizations.aspx

Locate your back-up copy of the exported XML file. Upload and import this back-up file to return to your original working state. You can then use the Navigation Pane again.

Important

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.

Top

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 this:

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 present there can be configured as optional. Users can select which groups they will see in the Workplace area if they click thePersonalize 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 within the Microsoft Dynamics CRM Online 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 simply contains one or more Title elements. If you want to re-name an existing Area, Group or SubArea, define your Titles for the wanted language. 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.

Note

Because Microsoft Dynamics CRM Online supports a multi-lingual 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 Online multi-lingual 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 the Microsoft Dynamics CRM Online 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>

Top

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 Online Software Development Kit. See SiteMap (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, which will help you avoid errors. 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 providing 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.

See the Related Links at the bottom of this document for links to download these applications.

Note

While 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 Online Navigation Pane. If so, you would need to use the steps described in "Recovering from Errors" 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, then make the necessary changes to ensure that you are conforming to schema requirements and getting the outcome you want.

Top

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.

This allows the customizations.xsd file to provide a schema for all customizations that are exported from Microsoft Dynamics CRM Online. 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:

1. Export the Site Map and extract the customizations.xml file from the customizations.zip file.

   Important

   Remember to keep that customizations.zip file as your backup!

2. 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.

1. Open Microsoft Visual Web Developer 2008 Express Edition and from the File menu, select Open File....
2. In the Open File dialog, select the customizations.xml file and click Open.
3. In the View menu, select Properties Window.
4. In the Properties area, select the Schemas box and type ISVConfigAndSiteMap.xsd and press Enter.
5. Locate the Resource Center Area in the customizations.xml and place the cursor after the Area ending tag: "</Area>".
6. 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.

7. Type A to select the Area element and press Enter
8. Press the spacebar to add a space.

   You should see a list of valid attributes for the Area element

   

9. 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.

10. 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>

11. Continue to define your elements. Use the information in the SiteMap (Microsoft Dynamics CRM SDK) and the schema validation in IntelliSense to define the appearance and behavior for the elements.
12. 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.

1. Open XML Notepad 2007 and from the File menu select Open.
2. In the Open dialog, select the customizations.xml file and click Open.
3. In the View menu select Schemas… .
4. In the XML Schemas dialog, from the File menu, select Add Schemas….
5. In the Open dialog, browse to the ISVConfigAndSiteMap.xsd and select it. Then click Open.
6. Click OK to close the XML Schemas dialog.
7. In the Tree View tab, expand the SiteMap node and select the last Area element.

   

8. Right-click the Area node and select Element > After from the context menu.

   

9. Any valid element names appear in a box. Select the Area element.

   

   Note

   The Error List area provides the description of "The required attribute 'Id' is missing.". This indicates that a valid Area element must have an Id attribute.

10. To add an attribute, right click the Area element you created and select Attribute > Child from the context menu.

    

11. Select Id from the list of available attributes

    Note

    • 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.
12. Type a unique value for the Area Id attribute value.
13. 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 (Microsoft Dynamics CRM SDK).
14. Save your changes and import your customizations.xml file to see your changes.

Top

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 within 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.

Important

Be aware that each major element must have a unique Id attribute value. If you copy a SubArea from one Area 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 within the Areas.

Change the names of links in an Area

Most of the links created by SubAreas 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. See State your terms: Use your organization's nomenclature for information about changing the names of entities.

However, for SubAreas 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 below.

<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"/>

Tip

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

Groups provide a way to group SubAreas with collapsible rows. By default, only the Workplace area uses Groups. But any Area can use Groups. 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, to 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:

• The Area element includes the attribute ShowGroups="true"
• Both Groups now include a Title within a Titles element.
• The new Group has a unique value for the Id attribute.
• Some of the SubAreas have been moved into the new Group.

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.