Document Maps in SSRS

What's a document map?

A document map is an interactive feature of an SSRS report that can generate a hierarchy of links that you can use to navigate the report. The document map will take on different forms, depending on the render format.

If you have any long paginated SSRS reports, consider using document maps. They've been around since SSRS 2005, but I think they're still underutilized, considering how many reports get exported to Excel and PDF.

What does it look like?

In the web viewer, it'll appear in a pane to the left of the report body. Clicking a section in the map will take you directly there in the report.

In Excel, you'll get a sheet named "Document map", which contains links for each section. In addition, each section will be formatted as an Excel group, and any child groups in SSRS will end up as child groups in Excel.

Any pagination in your report will be retained, as it normally is in Excel exports.

Finally, when exporting to PDF, your document map will appear in the bookmarks pane.

How do I do it?

Implementing a document map is simple. Click on a report item or data region, then check the properties pane for the DocumentMapLabel property. Once you have one label on the report, a document map will be generated.

In this property, you can put pretty much anything that can evaluate to a string. Setting it to the value of a field, for example, will generate a link in the document map for each value of that field.

However, you'll have to be careful with where you set the DocumentMapLabel property.

Data regions vs. report items

If you set a document map label on a text box (as pictured above), the document map will not contain the expected nesting.

Therefore, you'll generally want to set the property on a data region such as a tablix member (row groups or column groups) instead. When you click on the tablix member, you might not see the DocumentMapLabel property at first - if that's the case, just expand the "Group" node in the properties grid.

Setting the property on the tablix member instead of a text box will generate the document map pictured earlier, with the expected nesting.

Sometimes, however, you'll want to put the document map label on a static item, such as a rectangle, using a simple text value rather than a field's value.

Using hard-coded document map labels

You might want to create distinct sections in the document map that aren't dynamically generated. For example, you might want a cover page or an appendix that contains definitions for report metrics.

As I mentioned earlier, you can set the value of the DocumentMapLabel property to any expression that returns a string. This includes hard-coded values, which you'll generally want to set on an item that isn't nested inside a data region.

In the example below, I've set a document map label on a rectangle at the top of my report. This rectangle contains a couple summary statistics.

07_rectangle.png

In addition, I've added a label to the tablix itself.

And when I run the report, the document map combines all the labels in a logical manner.

Notice that the yearly labels (generated using the CalendarYear field) are nested within the label assigned to the tablix, and the tablix is sectioned at the same level as the rectangle. If I were to add further nesting (e.g. putting a couple rectangles within the first rectangle), the document map would accomodate this as well.

Summary

In this post, I've covered:

  • What a document map is and what it looks like
  • How to add a document map to a report
  • Making sure nesting is maintained by using tablix members
  • Combining hard-coded document map labels and dynamically generated labels

As I mentioned at the beginning, this is a feature that I don't often see utilized. It's a huge usability boost, especially when a report is frequently generated as a PDF, and is very easy to implement. Try it out on your next SSRS report.

I've also uploaded a zipped Visual Studio solution containing the examples used in this post. You'll just need the AdventureWorksDW2014 database.