Learn more about SQL Server tools

mssqltips logo
 

Tutorials          DBA          Dev          BI          Career          Categories          Webcasts          Whitepapers          Today's Tip          Join

Tutorials      DBA      Dev      BI      Categories      Webcasts

DBA    Dev    BI    Categories

 

SQL Server Reporting Services Bookmarks and Document Maps


By:   |   Last Updated: 2015-03-16   |   Comments (2)   |   Related Tips: > 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.

Tablix Document Map

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. 

Tablix Document Map Page 1

Tablix Document Map page 2

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.

hide map

show map

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. 

pdf document map

Excel Document Map

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.

document map hierarchye)

These document map hierarchies flow through to exported PDF and Excel documents.

hierarchy document map pdfhierarchy document map excel

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.

bookmark

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.

BookMark Properties

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. 

BookMark Link 1
bookmark link page 2

Unfortunately, bookmarks are not functional in PDF files; however, as shown below, bookmarks are enabled when exported to Excel (and Word)!

bookmarks excel

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


Last Updated: 2015-03-16


next webcast button


next tip button



About the author
MSSQLTips author Scott Murray Scott Murray has a passion for crafting BI Solutions with SharePoint, SSAS, OLAP and SSRS.

View all my tips




Post a comment or let the author know this tip helped.

All comments are reviewed, so stay on subject or we may delete your comment. Note: your email address is not published. Required fields are marked with an asterisk (*).

*Name    *Email    Email me updates 


Signup for our newsletter
 I agree by submitting my data to receive communications, account updates and/or special offers about SQL Server from MSSQLTips and/or its Sponsors. I have read the privacy statement and understand I may unsubscribe at any time.



    



Tuesday, March 20, 2018 - 12:03:04 PM - Courtney Fay Back To Top

So is there another way to get a table of bookmarks to render and work in PDF?  Can you create a hyperlink to a bookmark, or a tablix, or a textbox in a tablix? hyperlinks work, right?  

I would love a solution to having a clickable TOC in SSRS render to PDF with full functionality.

 


Wednesday, April 01, 2015 - 1:14:15 PM - array Back To Top

Great tip, thank you! I wasn't familiar with these two properties before, so I'm happy to add them to my toolbox. 


Learn more about SQL Server tools