August 25, 2011 at 1:54 pm
I am curious to know how my fellow SSRS report authors and admins out there approach the task of documenting metadata for their reports.
I am developing a series of reports that will need companion metadata – essentially explanations and detailed descriptions of report fields, calculations, datasets, etc. for the end user.
My SSRS spidey-senses are telling me that I should probably do something like:
1.Store this metadata in a database table somewhere
2.Create a parameterized ‘master’ report that returns all of this metadata
3.Use links from my reports that point to the master metadata report, and pass along their ReportID (or something) as a parameter, so that only pertinent report metadata is returned
My only squabble with the solution above is that it drives the user away from the report that they are viewing. I suppose that I could use some javascript to have the report appear in a pop-up window, but I was curious to learn what others had done.
Any feedback is appreciated...
- Simon
August 26, 2011 at 7:47 am
I take the very simple approach of putting info like that in tool tips. It doesn't clutter the report at all, but the user can find it easily by hovering the field in question.
August 26, 2011 at 7:57 am
Daniel Bowlin (8/26/2011)
I take the very simple approach of putting info like that in tool tips. It doesn't clutter the report at all, but the user can find it easily by hovering the field in question.
Me too. I keep the extra technical stuff (like the how's and why's) in a separate word document. Tooltips are great.
Leonard
Madison, WI
August 29, 2011 at 6:30 am
Thanks for the feedback, Leonard and Daniel.
I will probably use a combination of tooltips for the quick and easy metadata definitions, and a more comprehensive document/data model for the reports and report elements that require a greater level of explanation.
Thanks again.
-Simon
August 30, 2011 at 3:21 am
I use two methods: for the technical back-end I use a word document along with a freeware screen grabbing utility that also quickly allows me to draw circles, lines, and annotate text. The problem is how time consuming this is to get ready on the initial run, and then to keep up to date! I myself have failed at this endeavour.
Something else I worked on was an SSIS script that populates a database with the list of reports and who has access to them; which is referenced by an Index report which groups and links to all of those (and, of course, only showing what the user is allowed to use). I planned to add in an extra field to store a thumbnail and short description of the report to show alongside it, but I don't think users would care for it right now.
So that's two sides, technical and user-oriented.
What I would like to do for the technical side is use one of the proper programs that lets you document the RDL; there's one by Red Gate (but which is expensive and extremely limited; requiring you to work online and have write access to the database schema). The other one is BI Documenter which is also extremely expensive, too much for me to pay.
I "plan" to put my own program together to do it instead so all of us can benefit (and to pop it on the ol' resume), but I just haven't had time 😛
August 30, 2011 at 6:52 am
I like the idea of an annotated screenshot as well.
Thanks for the feedback!
-Simon
August 31, 2011 at 1:22 am
I always attempt to pull together a comprehensive word document for each report project.
This set out the data source, tables etc used from the data source, any links between reports and also if anything requires updating on an irregular basis. Oh and also where the project is saved, etc.
The aim is to give another repotr writer to look into any issues that might develop in future.
The hard part is getting time to do the documentation and also keeping it current when it is done.
We tend to use a similar format for each document.
August 31, 2011 at 1:28 am
Oh - I forgot to say that we also sometime produce a seperate user guide which is published to the report server. For different groups of users I tend to create a reports menu and these guidelines are one the of the options to choose from.
In the guidelines I add screen shots, navigation tips and tips on how to export reports. If there is anything that is specific to the reports that is not obvious I also highlight this in the notes. Once again the hard part is finding time to do the notes and keep them updated.
If requested I will do demos and give phone/ email help. After all what is the use of reports if no one uses them.:-D
Despite any shorcomings that reporting services may have it is relatively easy for colleagues with varying degrees of ICT skills to use.
August 31, 2011 at 4:01 am
What are the chances of sharing your technical template, and a few screenshots (with stuff blacked out) of the user-end side you mentioned?
August 31, 2011 at 6:23 am
As to whether it is a technical document is probably a moot point, however it suits our needs. It is simply not possible to document every setting in the reports but what this includes is sufficient for a.n.other person to pick up on where things are stored and where the data comes from.
I struggled to attach a copy of the word document so have copied out the text into the message. As such the formating / tables are all over the place. I have taken out any references to my organisation. Hope it helps. Please feel free to add suggested improvements.
Report Project Basic Details
?Report Name –
?Service –
?Who is the audience of the report –
?Reporting Database –
?Link to report (just include link to menu, etc)
?Reporting Services Security Group –
Data SourceData Source Details
?Original Data Source: –
?Reports Data Source – following tables
Update FrequencyUpdate Frequency Details
?View –
?Stored Procedure -
Report Documentation
Documentation
?Project Location -
?Query Location -
?Guidance Notes Location -
Annual Updates Required
Detail Any Annual Updates Required
?Fields in Query / View / Stored Procedure that need amending –
?Fields in report datasets that need amending –
?Text fields in reports that need updating –
List of Reports within ProjectDetail of Reports
Report Links Details of Links
Other Information Details
Revision History
DateVersion
NumberAmended byDescription of Amendments
August 31, 2011 at 6:32 am
Thank you, Tim, that's great info!
August 31, 2011 at 6:39 am
Hope it is useful for someone to adapt or use as a starting point. We had no method of documenting visual studio projects prior to this so had to make something up that worked for us without being too much of a burden. In this respect it does as it is the first point of reference if something goes wrong with a report that someone else has produced. 9 times out 10 it will be a data error that has caused the issue. Hence the importance of the links to tables and queries.
Sorry I could not work out how to attach the word document, however I was in a hurry... Technically challenged you may say:hehe:
Look forward to any suggestions on adding further details.:-D
August 31, 2011 at 8:20 am
Document each report in an MS Office doc (Word/Excel/Visio/Powerpoint as appropriate) stored in a sharepoint library and add the hyperlink to the document as a description via report manager or just straight into the Catalog table.
August 31, 2011 at 8:39 am
One thing I will say is that it is easier to write/maintain documentation if it is a short template vs a long one. In my experience, I've found two main benefits from documentation:
1) As a checklist to make sure I've done everything. E.g. have I added tooltips? Have I updated the footer? Did I set report caching up? Small things that are easy to miss.
2) As an explanation of "why". Looking at reports/stored procedures, it's easy for me to see what another developer has done. But why is a whole other matter. Did they try a different way and it didn't work? Is there some weird scenario that they were accommodating or accounting for? If I see an explanation I can instantly go "Oh, that makes sense", or "Oh, that doesn't apply any more".
Leonard
Madison, WI
June 16, 2014 at 3:31 pm
We had similar requirements with regard to the report metadata including the ability to manage security and report categories within the application.
With that in mind we decided to build everything into the app, so that the app now has an import export interface for the reports, and the database has a reporting schema for the metadata. The import process will accept zipped report(s) or it will accept zipped report(s) w/corresponding xml metadata file(s) that model the reporting schema. The export process exports both reports and xml metadata files that are related to each other using a GUID.
We have a Report Server configuration tab within this interface that is used to store the deployment details. The import process will deploy reports one by one grabbing the metadata file if it exists in the zip file. Upon deployment a report identifier is returned from the report server that uniquely identifies the report and the metadata is then updated/inserted using that identifier.
The process works well, but we have had some challenges. Here are the things I would recommend thinking about:
The initial population of metadata is a large task
Maintaining consistency across Visual Studio, Source Control, Zipped xml files and database is difficult (we've had to remap data a couple of times)
Subreports are painful to deal with because their only link to the parent is through the Report Name (A strict naming convention helped a little)
Since we are committed to this process, it would be cool to hear some thoughts on how to improve.
Viewing 15 posts - 1 through 15 (of 20 total)
You must be logged in to reply to this topic. Login to reply