SQL Server Reporting Services Bookmarks and Document Maps


By:   |   Updated: 2015-03-16   |   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.

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





get scripts

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


Article Last Updated: 2015-03-16

Comments For This Article




Thursday, August 26, 2021 - 1:34:29 PM - Rudy Chavez Back To Top (89173)
Scott - thanks for the prompt response.

Yesterday evening I figured out what was happening.

The destination bookmark "tag" was associated with a column I had hidden. In SSRS viewer, it worked fine; however, my guess is that because it was hidden, when exported to Excel, that bookmark "tag" was lost given that the destination column was hidden (the reference "behind the scenes" was probably not kept because the column wasn't exported). When I did an unhide of the column, everything worked perfectly in both SSRS viewer and in Excel.

I had originally hidden the column as it was a "combo" column that was the result of concatenating multiple column values to reach uniqueness (for the user, such a column would be confusing so I hid it - but the reference was still there in SSRS). This is because I was linking from a summary MATRIX to a detail TABLIX (ie, for a user to explore the details that made up a given summary line).

Hence, while bookmarks work for hidden columns in SSRS, they do not work when exported to Excel if the destination column holding the bookmark "tag" is hidden. Lesson learned.

Thanks again!

Wednesday, August 25, 2021 - 8:25:14 PM - Scott Murray Back To Top (89168)
Hi Rudy,
I had not tried this functionality in a while, but make sure you are setting the bookmark on the location where the link should go, and then in the origin textbox, go to the text box properties and then actions and selected go to bookmark.

Wednesday, August 25, 2021 - 12:55:56 PM - Rudy Chavez Back To Top (89167)
Great article - thanks!

However, I implemented bookmarks that work fine within the SSRS report viewer when I run the report; however, when I export to Excel, they do NOT work. Any ideas why that is? I read that section multiple times and even tried implementing the blue/underline to see if somehow Excel would treat as a hyperlink to no avail.

Thoughts on what I'm missing?

As a side note, I also have a Document Map in that document which works fine as well and exports to Excel ok.

Monday, August 24, 2020 - 11:39:26 AM - Susan Cable Back To Top (86353)
Yes, that is how to add a item to the Document map. What I need to do is the opposite; that is, I need to add a link which takes a user to the document map tab from somewhere else in the Excel workbook. So, for example, in the document map the user clicks on "Glossary" and the workbook goes to the 27th tab with the Glossary on it. Then after reading through the glossary the user clicks a clever link in the footer which immediately takes the user back to the Document map tab. The user can click another link to whatever tab/page/worksheet strikes their fancy, then at the bottom they can easily get back to the Document map This is a standard concept, the same as any hard print media which has a table of contents at the front. How to execute this? Referring back to your response, what is the "actual item" for the Document Map tab itself? It is not yet produced in the design, so I am unable to see or find it's properties. Surely it has a default value. Thank you, kindly, for suffering through this with me!

Monday, August 24, 2020 - 8:03:52 AM - Scott Murray Back To Top (86349)
You would add the actual items from your list. For instance if you are using sales territory as the value, you would add sales territory in your document map / bookmark.

Friday, August 21, 2020 - 5:16:23 PM - Susan Cable Back To Top (86343)
Hello, Scott: Thank you kindly for your quick response. I'm not quite following. Use the code/expression for what? What code/expression will send the Excel user to the document map tab? So far as I can tell, the document map itself is not visible in the design. I've only added Document Map links to the tables I can see and access. I would like each page to have a link back to the Document Map which I cannot see in the design. So users click on the document map to go to a tab way on the right side of the tab bar, then click a link at the bottom to go back to the document map way on the left side.

Friday, August 21, 2020 - 2:38:54 PM - Scott Murray Back To Top (86341)
Have you tried to use the same code / expression in your bookmark as you are using in your document map?

Friday, August 21, 2020 - 2:02:12 PM - Susan Cable Back To Top (86340)
Hello, Scott:
I know this is an old post, but perhaps you are still around to help me. Do you know how to link back to the document map from other places? My report is generating many tabs, and I like users to be able to quickly return to the map. However, since I can't see the map in the report design, I can't figure out how to bookmark it.
Thank you, kindly!

Sunday, April 28, 2019 - 2:28:06 AM - Dhanalakshmi K Back To Top (79793)

Can you please show document map when export to word , In msdn site they mentioned any document map labels exist in the report, they are rendered as Word Table of Contents (TOC) labels on the respective report items and groups. but this one is not working when export to word.


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

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 1, 2015 - 1:14:15 PM - array Back To Top (36793)

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



download














get free sql tips
agree to terms