SiteMap XML in Dynamics 365 Explained

The SiteMap is the navigation structure of a model-driven app: the areas on the left, the groups inside them, the individual entries. We think of it as the most fundamental navigation element in the CRM. It is where we choose which kind of records we want to work on next. In the solution export it sits as its own XML definition, and that definition is pleasantly simple.

Three levels, nothing more

The structure consists of exactly three nested elements. Area is the top level, a work area such as Sales or Service. Below it, Group elements bundle entries into named blocks. The lowest level, SubArea, is the individual navigation entry.

An excerpt makes this tangible:

<SiteMap>
  <Area Id="Sales" ResourceId="Area_Sales">
    <Group Id="Customers">
      <SubArea Id="nav_accounts" Entity="account" />
      <SubArea Id="nav_contacts" Entity="contact" />
    </Group>
    <Group Id="Reports">
      <SubArea Id="nav_report" Url="$webresource:fab_/pages/report.html" />
    </Group>
  </Area>
</SiteMap>

A SubArea points either to a table (attribute Entity, the platform then automatically renders the default view) or to a URL, such as a web resource or a dashboard. On top of that come icons, localized titles and visibility switches for different clients. Permission control is possible too: a SubArea can be tied to table privileges, so that users without read access never see the entry in the first place.

By the way, nobody has to edit the XML anymore today: the modern app designer covers navigation completely. Reading the XML is still worthwhile, because the designer only ever shows one app, while the export lays all SiteMaps side by side and only then answers the question of how many navigation states exist at all.

One SiteMap per app

In the past there was a single SiteMap for the whole organization. Today every model-driven app brings its own, linked through the app definition. The export of a grown solution therefore often contains several SiteMaps side by side, sometimes including the old organization-wide one that nobody maintains anymore but that still gets exported.

Where legacy leftovers collect

Navigation is one of the places where history settles, because entries are rarely removed. Three patterns come up again and again.

Entries pointing to tables that no longer exist or are empty: the entry seems to work but leads nowhere. URL entries pointing to old web resources, often HTML pages from an earlier project phase that were replaced by something else long ago. And visibility rules for clients that no longer exist, leftovers from the days of the legacy web client and Dynamics for Outlook.

A fourth observation from practice: SubAreas that point to web resources via URL are one of the places where seemingly orphaned web resources are still in use after all. Anyone cleaning up the stock of scripts and HTML pages should therefore include the SiteMaps in the reference search, otherwise a page gets thrown out that is still linked in the menu. The broader approach is described in finding dead components.

None of this is dangerous. But navigation is the first thing every user sees, and a tidy menu is the cheapest improvement to user experience this system has to offer. The check is quick: hold every SubArea against the list of existing tables and web resources. Whatever points into the void can go. Small, regular cleanups like this are what solution hygiene is made of.