Edit the site map

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You can edit default or app-specific site maps in any of the following ways:

  • Using the new SiteMap designer introduced in December 2016 update for Dynamics 365 (online and on-premises) or a third-party site map editor if you are using an earlier version of Microsoft Dynamics 365.

  • Programmatically updating the SiteMap entity record to update the XML in the SiteMap.SiteMapXml attribute.

  • Manually editing the XML in the SiteMap node in the customizations.xml file of an exported unmanaged solution and then by importing the solution as managed or unmanaged.

In This Topic

Use site map editors

Programmatically update the site map

Editing the SiteMap manually

Editing with schema validation

Encode the ampersand character

Recovering from errors

Use site map editors

If you are using December 2016 update for Dynamics 365 (online and on-premises), use the new SiteMap designer to create and manage site maps. More information:  Create a site map for the app

Otherwise, you can use one of the third-party site map editors to edit the default site map. As app-specific site maps are introduced in December 2016 update for Dynamics 365 (online and on-premises), third-party site map editors might not work as expected for editing site maps for business apps. A popular sitemap editor for editing default site maps is included in the Toolbox for Dynamics CRM 2011/2013 released by Microsoft Dynamics 365 MVP Tanguy Touzard.

While these applications streamline the process to edit the site map, they still require that you have some understanding of the site map XML schema. For more information, see SiteMap XML reference.

Note

Microsoft Dynamics 365 technical support doesn’t provide support for third-party applications. If you have questions about these applications, contact the application publisher.

Programmatically update the site map

Retrieve the SiteMap entity record that you want to update, and then update the XML in the SiteMap.SiteMapXml attribute of the record. Make sure you have understanding of the site map XML schema before you edit the XML. For more information, see SiteMap XML reference.

When you update a SiteMap record programmatically using the Update method, the site map XML that you specify will overwrite the existing XML in the SiteMap.SiteMapXml attribute of the record.

Note

  • You can also programmatically create and delete app-specific SiteMap records. To create an app-specific SiteMap record, one must specify values for the following attributes at the minimum: SiteMap.SiteMapNameUnique and SiteMap.SiteMapXml. However, we recommend that instead of programmatically creating and deleting app-specific site maps, you must use the new SiteMap designer to create and delete app-specific site maps. More information:  Create a site map for the app

  • You cannot programmatically create and delete default SiteMap record. You can use the SiteMap.IsAppAware attribute to distinguish between the two types of site maps: 0 indicates the default site map; 1 indicates the app-specific site map.

Editing the SiteMap manually

You can manually edit the SiteMap node in the customizations.xml file of an exported unmanaged solution and then import it back in Dynamics 365 to update the site map. Depending on whether you are importing an unmanaged or managed solution decides how the SiteMap record is updated.

  • Importing an unmanaged solution overwrites the existing site map XML in the SiteMap record.

  • Importing a managed solution creates a new SiteMap record with the latest changes, and the SiteMap.OverwriteTime attribute value of the latest/active SiteMap record is set to the default value of the DateTime field (1900-01-01 00:00:00.000). The SiteMap.OverwriteTime attribute value of the existing SiteMap record is set to the datetime value when it was updated.

To edit the site map

  1. Click Settings, click Customizations, and then click Solutions.

  2. Add the default or app-specific site maps to a new or existing unmanaged solution. In the solution, select Client Extensions from the list of Components on the left. Select Add Existing, and then select Site Map. From the list of site maps:

    • To add the default site map, select Site Map.

    • To add an app-specific site map, select a custom business app site map . The dialog box displays site maps for all the custom business apps that you have access to. For example, in this case, you can select Contoso Sales App or Contoso Service App.

      Select default or app-specific site map to add

      Note

      The app-specific site maps display only if you have December 2016 update for Dynamics 365 (online and on-premises) or later and have custom business apps in your Dynamics 365 instance. You can also select multiple app-specific site maps and default site map to be added to the same solution.

    • Click OK in the Select solution components screen.

  3. Click Save to save changes to your solution.

  4. Click Export Solution and follow steps in the solution export wizard to export the solution.

  5. After the solution is exported, extract the files from the compressed .zip file.

    Tip

    Keep the compressed .zip file as your backup.

  6. In the customizations.xml file, locate the:

    • SiteMap node under ImportExportXml/SiteMap to edit the default site map.

    • SiteMap node under ImportExportXml/AppModuleSiteMaps/AppModuleSiteMap to edit the app-specific site map.

        

      Tip

      If you added multiple app-specific site maps in a solution before exporting the solution, you can use the SiteMapUniqueName and SiteMapName nodes under ImportExportXml/AppModuleSiteMaps/AppModuleSiteMap to determine the SiteMap node in the customizations.xml file that you should edit for your app site map.

  7. Edit the SiteMap node as required.

    Note

    Editing XML is much easier if you use an editor that provides schema validation. For more information, see Editing with schema validation.

  8. Create a new compressed .zip file, including the extracted solution files and your edited customizations.xml.

    Tip

    In Windows Explorer, select all the files. Then right-click and select Send To and Compressed (zipped) folder.

  9. Import the new solutions file.

    1. In Microsoft Dynamics 365, click Settings, click Customization, and then click Solutions.

    2. Click Import.

    3. Click Browse, locate your modified solutions .zip file, click Next, and then click Import.

    4. When the import is finished, click Close.

  10. Publish the customizations.

    Tip

    If you don’t see the changes right away, refresh your browser page.

Editing with schema validation

For a better experience, edit the customizations.xml file with an application that can use schema validation to provide IntelliSense support. For more information, see Edit the customizations XML file with schema validation.

Encode the ampersand character

When you add a URL to the site map that includes the ampersand character (&), you must encode it by replacing it with “&”. XML validation fails if you don’t encode this character and you won’t be able to import the solution. For example:

  • Correct:
    <SubArea Id="new_customSubArea" Url="http://mysite/mypage.aspx?parameter1=value&amp;parameter2=value ">

  • Incorrect:
    <SubArea Id="new_customSubArea" Url="http://mysite/mypage.aspx?parameter1=value&parameter2=value">

Recovering from errors

The solution import tool performs validations on the site map. If errors occur, the default site map is applied and an error message is displayed. You must fix the errors in the site map and import it again. However, it’s still possible that some errors might occur.

Some errors that you might encounter when running a custom business app after manually editing/importing the custom business app site map are:

  • Site map with no subarea

  • Site map has subareas, but user does not have the privileges to see them

  • Invalid entity (not a legal Dynamics 365 entity name)

  • Invalid url

  • Site map has dashboard node, but no dashboard selected in the modular business app definition

See Also

Customize SiteMaps
Change application navigation using the SiteMap
Pass parameters to a URL using the SiteMap
Control access to the Help & Training site
SiteMap XML reference
SiteMap schema

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright