Beginning to documenting RDLs/RDLCs in RS 2008

I’ve been trying to work my way up to a full-blown RS 2008 RDL Documenter implementation. (Better do it before RS 2010 is out…)

While C was visiting family a few weeks ago, I made a start on the complete rewrite of the Designer widget that will be necessary. I’ve also slightly upgraded the TestHarness application so that it comes with a 2008 Compact sample db, if you want to use it.

The Designer widget is necessary if you want to add custom documentation, to RDLs, and have output documentation files that are similar to XML Comments for your other code files. This concept, which I call XMLRSDocs, was central to my original drive to write the tool. It really bugs me that a declarative module, which is what the RDL format is, can’t have XML Comments like other application components.

But our team has been working a lot with RS 2008 semantic models, and we have a significant need to document the attributes and entities being used in multiple reports, before doing an upgrade. (Wow, how unusual: data and the need to document it are driving my work…)

The work I’ve already done, for that purpose, is good enough to give some results, with really minor changes for RS 2008.

As a result, you can now pick up an RS-2008-usable version of this tool from our Spacefold downloads page.

What is critical, and already done?

Very little has changed so far.

There is a 2008-valid extraction XSLT — not done, but done enough — that will work with RS 2008 RDLs. RDLs in RS 2008 have a new namespace, and that’s all I’ve changed so far.  I haven’t upgraded the code to recognize the tablix data region type, and numerous other enhancements.  For our purposes, we really only care that the data elements get in.  I’ll upgrade the XSLT for layout elements later.

To get a picture of the fields in use in reporting datasets, which is what we really need right now for our team, you only need to get the embedded information into a database so you can query it properly.

I’ve added a new button to TestHarness, to load a full folder of RDL/RDLCs to a server at once, if you’re storing your results in the Compact db. But TestHarness is more of a teaching device where all of the elements of RDL Documenter come together in one place.  In this release, I’ve also added the production-grade SSIS package into the deployment set of files now, and this is what you would normally want to use.

I don’t consider myself an SSIS expert, so earlier I just described the steps in the package, and didn’t include it in the delivered files earlier.  But, for whatever it’s worth, you have my idea of this somewhat-unique set of steps now.

What’s not done?

You’ll find that each sub-dir of the zip file has a readme saying, basically, “this isn’t done yet”.

The Designer widget was fun and exciting the first time; who wouldn’t get a thrill out of integrating something directly into the IDE? But I really can’t get up for it now, especially since the Custom Properties for individual report layout items and the “global” report is now much better exposed, even by Report Builder.

TestHarness really doesn’t need much work.  I will provide more exiting RDLCs for it, when I expand the supported db schema — see below — but really the “shape” of the standard RDL elements as they are ported into your db schema was never very important to me.  The package supports whatever you want to do here.  My real interest was adding custom doc information, which was woefully hard to do.  How you choose to store and display that information should be up to you — that’s the whole point.  The SSIS package just shows you the key actions I expect to be necessary, and a couple of key output types (XML and documenting reports). But the package should let you move your RDLs right into whatever you’re doing with your other XML Comments.  I hope.

I expect that I will be expanding this sample package to load information from SMDLs into a separate table at some point.  Compared to messing around with RDLs, it should really easy to extract attribute and entity GUIDs and Names, to tie them directly to report usage later.  I could get a simple list of all Entity-Attribute combinations, showing both names and GUIDs, with this single XPATH statement:

/*/*/*/*/*:Attribute/concat(../../*:Name,‘ (‘,../../@ID,‘)” – ‘,./*:Name,‘ (‘,@ID,‘)’)

… which would look something like:

• Glossary (Gb355f720-11df-43d9-9b6d-f9e863abde4b)’ – Term (G4a1f954b-13eb-48cd-b75a-c538c0efd0ba)
• Glossary (Gb355f720-11df-43d9-9b6d-f9e863abde4b)’ – Institution (G58288fcd-1422-47dc-b9d7-c3c4062e8f5c)
• Glossary (Gb355f720-11df-43d9-9b6d-f9e863abde4b)’ – Date Time Created (G7db0f4e0-74e7-4cc1-a91b-c069bb4b24aa)
• Glossary (Gb355f720-11df-43d9-9b6d-f9e863abde4b)’ – Date Time Modified (G04c93e2b-173f-4272-b402-7d2e96746b05)
• Glossary (Gb355f720-11df-43d9-9b6d-f9e863abde4b)’ – Note (G6d8953ff-3ab3-44e6-9e46-86dd151677c4)

This and other ideas, plus a quick-start guide to use, are in the readme for the package.  But, for now, our team will be able to run the package as-is and then list the information relevant to their needs simply by doing this:

SELECT RDLFileName, RDLLayoutParentName, Value
  FROM [Test].[dbo].[RDLDocPrimary]
  WHERE RDLLayoutType = ‘Field’ ORDER BY 2, 3

… and they can do fancy things by shredding the semantic model query directly out of CommandText if they want to:

— base query for talking to the XML that forms
— each semantic model query…
SELECT RDLFileName, RDLLayoutParentName,
   CONVERT(xml,Value) AS XmlQueryable
FROM RDLDocPrimary WHERE RDLLayoutType = ‘CommandText’

— a list of all lead entities and their guids…
SELECT RDLFileName, RDLLayoutParentName,
   CONVERT(xml,Value).value(‘(//*:Grouping/@Name)[1]’,‘NVARCHAR(300)’) AS Entity,
   CONVERT(xml,Value).value(‘(//*:Grouping/*/*/*:EntityID)[1]’,‘NVARCHAR(300)’) AS EntityGUID
FROM RDLDocPrimary WHERE RDLLayoutType = ‘CommandText’
   ORDER BY 1,2,3

— a list of all attribute in use…
SELECT DISTINCT
   ISNULL(Ents.value(‘(../@Name)[1]’,‘NVARCHAR(300)’),‘CalcExpr’) AS AttributeName,
   Ents.value(‘(./*:AttributeID)[1]’,‘NVARCHAR(300)’) AS AttributeGuid
FROM (SELECT CONVERT(xml,Value) AS XmlQueryable FROM RDLDocPrimary
   WHERE RDLLayoutType = ‘CommandText’ ) RDL1
CROSS APPLY
XmlQueryable.nodes(‘//*:AttributeRef’) AS RDL2(Ents)
ORDER BY 1
— so far the above includes filters and query fields,
— I’ve not worked out that it includes everything possible, but it
— should be close

So Wise for one so young

Long way to go, but this should help Wisdom and the team figure out the impact of a model change on existing RDLs.

Meanwhile, Wisdom’s working on the companion SSIS Doc Generator for the team that I suggested to him.  Maybe he’ll let me borrow it to properly document all the XMLRSDocs ETL package options before my next upload.

As he would say, although maybe he’s picked it up from me, so far, so good.