By: Scott Murray | Comments (11) | Related: > Reporting Services Formatting
Problem
What are the SQL Server Reporting Services Document Map and Bookmark properties? How can they be used? Do they work for all rendering formats? Can you show me any examples?
Solution
Any report designer will often need to find ways to offer easy navigation paths to report consumers. SQL Server Reporting Services (SSRS) provides two main options to serve this objective: bookmarks and document maps.
Document maps create a separate windows pane with a set of hyperlinks which can be used to navigate around a report, a virtual table of contents. Bookmarks are similar to document maps in that they provide navigation links within a report; however they differ from a document map in that the links are sourced within the report objects themselves as opposed to being displayed in a separate document map.
Document maps also offer specific rendering functionality options that are not available for bookmarks. Furthermore, the document map rendering options function slightly different within each of the various rendering formats, and some functionality does not work at all in certain renderings. Thus, for PDF renderings, the document map functionality is expressed through PDF bookmarks. In Report Viewer and Report Preview (online), the document map actually opens on the left side of a report. For Excel, document maps are expressed through the use of a table of contents worksheet which is linked to specific worksheets. Similarly, Word expresses document maps via the Word Table of Contents functionality although you have to build the table of contents yourself (see Next Steps). Finally, the TIFF, XML, CSV, and Atom feeds do not use document maps.
Similarly Bookmarks can create a hyperlink in both Word and Excel and are utilized in the report viewer. Let's see both of these technologies in action.
We will use the Adventure Works databases as the basis for our SSRS report examples. The 2014 versions of the regular and data warehouse databases are available on Codeplex at https://msftdbprodsamples.codeplex.com/releases/view/125550. Once you download and install the SQL Server databases, we will subsequently use SQL Server Data Tools for Business Intelligence (SSDT-BI) for Visual Studio 2013 to develop reports.
Using Document Maps in SQL Server Reporting Services
Using document maps in SQL Server Reporting Services is a fairly simple process; most report objects allow you to set the document map property. One of the most common methods is to define the document map for each tablix in a report. Of course, you could also similarly set it for a rectangle, table, or list among other SSRS objects. For the below example, we are first selecting the tablix, and then on the properties screen we fill in a fixed name for the tablix document map property.
I follow this same process for the other two tablixes on the report. The below screen prints quickly show how the document map panel appears on the left side of the report preview. By clicking on each name in the document map, we can easily navigate to each tablix in the report preview which is much quicker than using the page navigators. Of course, on reports with a large number of pages, this benefit is even greater.
You will notice about half way down the page is a small left facing arrow as illustrated below; this arrow allows you to hide the document map. Similarly, once the document map is hidden, you can make it reappear by clicking the right facing arrow, as show in the second illustration. You can also hover over the border area between the report and document until a cross hair icon appears in order to manually increase or decrease the document map width.
These document map are exported with Excel and PDF render formats as shown below; PDF files use Bookmarks (not the same as SSRS Bookmarks) where as Excel creates links.
Now here is where the neat stuff comes into play; we can add a hierarchy of document map links by embedding one document map item within another object. For our examples, we will add a document map to the StateProvince field on the second tablix and on the SalesTerritoryName field on the third matrix. As shown below, we now have a full hierarchy that allows report consumers to quickly navigate not only to a specific tablix but also to a group within that tablix.
e)These document map hierarchies flow through to exported PDF and Excel documents.
One last tidbit about the document map; if for some reason you do
not want it to show, you can add the following text to the end of your
report to prevent the document from displaying when in the Report
Manager:
&rs%3aCommand=Render&rc%3aFormat=HTML4.0&rc%3aDocMap=False.
To be honest, I am not sure why you would do that.
Using Bookmarks in SQL Server Reporting Services
Bookmarks work quite similar to document maps except instead of having a separate pane for the navigation, you actually embed the bookmark somewhere within your report objects. To initiate a bookmark we first need to identify the field we want to navigate to and add the bookmark "name" to the object properties. Note that the value can be an SSRS expression or a constant. If the bookmark value occurs multiple times, navigation will occur to the first bookmark found in the report. In the below example, we are adding the StateProvinceCode field as the bookmark name for the StateProvinceCode text box on one of our tablixes.
Next, we create a quick matrix which lists all our available State
Province Codes as shown in the above screen print, step 3. As shown
next, within
this same text box, we navigate to our text box properties, by right
mouse clicking on the text box and selecting Text Box Properties. We
then click on the Action tab, then on the Go to bookmark radio button,
and finally select StateProvinceCode as our bookmark. This process
basically marries up the StateProvinceCode bookmark in our detail
tablix with the same code in the State Province listing tablix. SSRS
does not "show" this field as a hyperlink, so we also adjust the text
box's font color to blue and implement the underline format.
Now we can see the results of our bookmark addition. The first screen print below shows our mouse pointer changes over to a hand signifying we have a link available to click on. The second screen print shows how the report navigates to the GA listing when I clicked on GA.
Unfortunately, bookmarks are not functional in PDF files; however,
as shown below, bookmarks are enabled when exported to Excel (and Word)!
Conclusion
Navigation within SSRS reports can be a challenge especially on very large reports which contains many objects and many pages. Document maps and bookmarks are two tools which can be used to provide report consumers with a method of quickly navigating through a report and instead of moving just page by page. A document map creates a separate window alongside an existing report when previewed online in Report Manager; this pane contains links to report objects which were tagged with a specific document map name. The name can either be a constant or a SSRS expression. Furthermore, a hierarchy of document map items can be created to navigate within a set of SSRS objects. In a similar fashion, bookmarks also allow navigation functionality for report users. However, bookmarks utilize links contained within the report itself as opposed to an external pane. Some render formats such as Excel carry the document map and bookmark functionality into its worksheets when a report is exported to Excel. PDF files only honor documents maps. Both bookmarks and document maps are another set of tools to make your SSRS reports exceptional for report consumers.
Next Steps
- Check out the following resources:
- Document Maps in Word - http://msdn.microsoft.com/en-us/library/dd283105.aspx#Interactivity
- All SQL Server Reporting Services Tips
About the author
Scott Murray has a passion for crafting BI Solutions with SharePoint, SSAS, OLAP and SSRS.This author pledges the content of this article is based on professional experience and not AI generated.
View all my tips
